server/doc/events.pod

=head1 CROSSFIRE PLUG-IN EVENTS

This document briefly describes each plug-in event. It is also used to
generate the event-list itself, so is always complete. Be careful wehn
changing it, though.

=head2 NOTATION

the event description below uses a variant of the forth stack notation -
an opening parenthesis followed by the type of each parameter, optionally
followed by two dashes and the returning parameters. If the latter is
missing, the event will be invoked but cannot change wether the event gets
processed.

If it is specified (even if no return values are supported), a plug-in
can override (e.g. using C<cf::override> in Perl) event processing,
basically short-circuiting it. For example, if you override from within a
player BIRTH event, nothing much will happen with respect to the built-in
processing, but if you override from within a player TELL event, the tell
will be ignored (presumably your plug-in took care of it).


=head2 GLOBAL EVENTS

Global events have no relation to specific objects.

=head3 clock ( )

Is invoked on every server tick, usually every 0.12 seconds.


=head2 PLAYER EVENTS

Player events always have a player object as first argument.

=head3 reattach (player)

Invoked whenever attachments/plug-ins need to get reattached to the player
object. This usually happens when the player gets loaded from disk, or
when the server is reloaded.

=head3 birth (player)

Invoked as very first thing after creating a player.

=head3 quit (player)

Invoked wheneever a player quits, before actually removing him/her.

=head3 load (player)

Invoked whenever a player has been loaded from disk, but before
actual login.

=head3 save (player)

Invoked just before a player gets saved.

=head3 login (player)

Invoked whenever a player logs in.

=head3 logout (player)

Invoked whenever a player logs out, gets disconnected etc.

=head3 death (player)

Invoked whenever a player dies, before the death actually gets processed.

=head3 map_change (player oldmap newmap)

Invoked whenever a player moves from one map to another.

=head3 extcmd (player string)

Invoked whenever a client issues the C<extcmd> protocol command. It's
argument is passed without any changes.

=head3 pray_altar (player altar skill -- )

Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.

=head3 tell (player -- )

Invoked whenever the player uses the B<tell> command, before it gets processed.

=head3 say (player --)

Invoked whenever the player uses the B<say> command, before it gets processed.

=head3 shout (player --)

Invoked whenever the player uses the B<shout> command, before it gets processed.


=head2 OBJECT EVENTS

Object events always relate to a specific object, which is always the
first argument. Not all events get generated for every object, some are
specific to an object type.

=head3 instantiate (object init-args...)

An archetype was instantiated into an object. This event occurs when
a map is loaded for the first time, or when the object was created
dynamically. The arguments are as specified in the C<attach> attribute of
the object or archetype.

This is useful to initialise any per-object state you might need.

=head3 reattach (object)

Invoked whenever attachments/plug-ins need to get reattached to the
object. This usually happens when it was loaded from disk, or when the
server was reloaded. This event will only be generated if the object has
attachments.

=head3 clone (object destination)

An object with _attached extension_ is cloned, that is, a copy was
made. The copy automatically has all attachments the original object
had. The perl variables get copied in a shallow way (references are shared
between instances). If this is not the behaviour you need, you have to
adjust the B<destination> object as you see fit.

=head3 destroy (object)

Invoked when the crossfire object gets destroyed, and only when the object
has a handler for this event. This event can occur many times, as its
called when the in-memory object is destroyed, not when the object itself
dies.

=head3 tick (object)

Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
during ticks should an objetc process any movement or other events.

=head3 kill (object hitter -- )

Invoked whenever an object is dead and about to get removed. Overriding
processing will skip removal, but to do this successfully you have to
objetc from dieing, otherwise the event gets invoked again and again.

=head3 apply (object who -- applytype)

Invoked whenever the object is being applied in some way. The applytype is one of:

=over 4

=item B<0> player or monster can't apply objects of that type

=item B<1> has been applied, or there was an error applying the object

=item B<2> objects of that type can't be applied if not in inventory

=back

=head3 use_skill (skill who part direction strignarg -- )

Invoked whenever a skill is used by somebody or something.

=head3 cast_spell (spell casting_object owner direction stringarg -- )

Invoked whenever a given spell is cast by B<casting_object> (used by
B<owner>).

=head3 drop (object who -- )

Invoked whenever an item gets dropped by somebody, e.g. as a result of a
drop command.

=head3 drop_on (floor object who -- )

Invoked whenever some B<object> is being dropped on the B<floor> object.

=head3 listen

Invoked whenever the object can hear something beign said in its
vicinity. Not yet implemented.

=head3 move (monster enemy -- )

Invoked whenever the B<monster> tries to move, just after B<enemy> and
other parameters have been determined, but before movement is actually
executed.

=head3 attack (object hitter -- damage)

Object gets attacked by somebody - when overriden, should return the
damage that has been dealt.

=head3 attacks (weapon hitter victim)

Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
B<victim>.

=head3 inscribe_note (book pl message skill -- )

Used whenever a book gets inscribed with a message.

=head3 trigger (object who -- )

Invoked whenever a lever-like B<object> has been activated/triggered in some
(manual) way.

=head3 move_trigger (object victim originator -- )

Invoked whenever a trap-like B<object> has been activated, usually by
moving onto it. This includes not just traps, but also buttons, holes,
signs and similar stuff.

=head3 close (container -- )

Invoked whenever a container gets closed (this event is not yet reliable!).


=head2 MAP EVENTS

These events are generally dependent on a map and thus all have a map
as first argument.

=head3 instantiate (map)

Original B<map> has been loaded (e.g. on first use, or after a map
reset).

=head3 reattach (map)

Invoked whenever attachments/plug-ins need to get reattached to the
B<map>. This usually happens when the map was loaded from disk, or when the
server was reloaded.

=head3 destroy (map)

Invoked when the map object gets destroyed, and only when the map object
has a handler for this event. This event can occur many times, as its
called when the in-memory object is destroyed, not when the object itself
dies.

=head3 swapin (map)

Invoked when a previously swapped-out temporary B<map> has been loaded again.

=head3 swapout (map)

Invoked after a B<map> has been swapped out to disk.

=head3 reset (map)

Invoked when a B<map> gets reset.

=head3 clean (map)

Invoked when a temporary B<map> gets deleted on-disk.

=head3 enter (map player)

Invoked whenever a player enters the B<map>. This event is likely unreliable.

=head3 leave (map player)

Invoked whenever a player leaves the B<map>. This event is likely unreliable.

=head3 upgrade (map)

(TEMPORARY EVENT) gets invoked whenever a old-style map has been upgraded.

Revision:	1.5
Committed:	Mon Aug 28 16:13:00 2006 UTC (17 years, 8 months ago) by root
Branch:	MAIN
Changes since 1.4:	+17 -3 lines
Log Message:	implement destroy event for objects and maps, implement loading of persistent map header
#	User	Rev	Content
1	root	1.1	=head1 CROSSFIRE PLUG-IN EVENTS
2
3			This document briefly describes each plug-in event. It is also used to
4			generate the event-list itself, so is always complete. Be careful wehn
5			changing it, though.
6
7			=head2 NOTATION
8
9			the event description below uses a variant of the forth stack notation -
10			an opening parenthesis followed by the type of each parameter, optionally
11			followed by two dashes and the returning parameters. If the latter is
12	root	1.2	missing, the event will be invoked but cannot change wether the event gets
13	root	1.1	processed.
14
15			If it is specified (even if no return values are supported), a plug-in
16			can override (e.g. using C<cf::override> in Perl) event processing,
17			basically short-circuiting it. For example, if you override from within a
18			player BIRTH event, nothing much will happen with respect to the built-in
19			processing, but if you override from within a player TELL event, the tell
20			will be ignored (presumably your plug-in took care of it).
21
22
23			=head2 GLOBAL EVENTS
24
25			Global events have no relation to specific objects.
26
27	root	1.4	=head3 clock ( )
28	root	1.1
29			Is invoked on every server tick, usually every 0.12 seconds.
30
31
32			=head2 PLAYER EVENTS
33
34			Player events always have a player object as first argument.
35
36	root	1.4	=head3 reattach (player)
37	root	1.1
38	root	1.2	Invoked whenever attachments/plug-ins need to get reattached to the player
39	root	1.1	object. This usually happens when the player gets loaded from disk, or
40			when the server is reloaded.
41
42	root	1.4	=head3 birth (player)
43	root	1.1
44	root	1.2	Invoked as very first thing after creating a player.
45	root	1.1
46	root	1.4	=head3 quit (player)
47	root	1.1
48	root	1.2	Invoked wheneever a player quits, before actually removing him/her.
49	root	1.1
50	root	1.4	=head3 load (player)
51	root	1.1
52	root	1.2	Invoked whenever a player has been loaded from disk, but before
53	root	1.1	actual login.
54
55	root	1.4	=head3 save (player)
56	root	1.1
57	root	1.2	Invoked just before a player gets saved.
58	root	1.1
59	root	1.4	=head3 login (player)
60	root	1.1
61	root	1.2	Invoked whenever a player logs in.
62	root	1.1
63	root	1.4	=head3 logout (player)
64	root	1.1
65	root	1.2	Invoked whenever a player logs out, gets disconnected etc.
66	root	1.1
67	root	1.4	=head3 death (player)
68	root	1.1
69	root	1.2	Invoked whenever a player dies, before the death actually gets processed.
70	root	1.1
71	root	1.4	=head3 map_change (player oldmap newmap)
72	root	1.1
73	root	1.2	Invoked whenever a player moves from one map to another.
74	root	1.1
75	root	1.4	=head3 extcmd (player string)
76	root	1.1
77	root	1.2	Invoked whenever a client issues the C<extcmd> protocol command. It's
78	root	1.1	argument is passed without any changes.
79
80	root	1.4	=head3 pray_altar (player altar skill -- )
81	root	1.1
82	root	1.2	Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
83	root	1.1
84	root	1.4	=head3 tell (player -- )
85	root	1.1
86	root	1.2	Invoked whenever the player uses the B<tell> command, before it gets processed.
87	root	1.1
88	root	1.4	=head3 say (player --)
89	root	1.1
90	root	1.2	Invoked whenever the player uses the B<say> command, before it gets processed.
91	root	1.1
92	root	1.4	=head3 shout (player --)
93	root	1.1
94	root	1.2	Invoked whenever the player uses the B<shout> command, before it gets processed.
95	root	1.1
96
97			=head2 OBJECT EVENTS
98
99			Object events always relate to a specific object, which is always the
100			first argument. Not all events get generated for every object, some are
101			specific to an object type.
102
103	root	1.4	=head3 instantiate (object init-args...)
104	root	1.1
105			An archetype was instantiated into an object. This event occurs when
106			a map is loaded for the first time, or when the object was created
107			dynamically. The arguments are as specified in the C<attach> attribute of
108			the object or archetype.
109
110			This is useful to initialise any per-object state you might need.
111
112	root	1.4	=head3 reattach (object)
113	root	1.1
114	root	1.2	Invoked whenever attachments/plug-ins need to get reattached to the
115	root	1.1	object. This usually happens when it was loaded from disk, or when the
116			server was reloaded. This event will only be generated if the object has
117			attachments.
118
119	root	1.4	=head3 clone (object destination)
120	root	1.1
121			An object with _attached extension_ is cloned, that is, a copy was
122			made. The copy automatically has all attachments the original object
123			had. The perl variables get copied in a shallow way (references are shared
124			between instances). If this is not the behaviour you need, you have to
125			adjust the B<destination> object as you see fit.
126
127	root	1.5	=head3 destroy (object)
128
129			Invoked when the crossfire object gets destroyed, and only when the object
130			has a handler for this event. This event can occur many times, as its
131			called when the in-memory object is destroyed, not when the object itself
132			dies.
133
134	root	1.4	=head3 tick (object)
135	root	1.1
136	root	1.2	Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
137	root	1.1	during ticks should an objetc process any movement or other events.
138
139	root	1.4	=head3 kill (object hitter -- )
140	root	1.1
141	root	1.2	Invoked whenever an object is dead and about to get removed. Overriding
142	root	1.1	processing will skip removal, but to do this successfully you have to
143			objetc from dieing, otherwise the event gets invoked again and again.
144
145	root	1.4	=head3 apply (object who -- applytype)
146	root	1.1
147	root	1.2	Invoked whenever the object is being applied in some way. The applytype is one of:
148	root	1.1
149			=over 4
150
151			=item B<0> player or monster can't apply objects of that type
152
153			=item B<1> has been applied, or there was an error applying the object
154
155			=item B<2> objects of that type can't be applied if not in inventory
156
157	root	1.3	=back
158	root	1.1
159	root	1.4	=head3 use_skill (skill who part direction strignarg -- )
160	root	1.1
161	root	1.2	Invoked whenever a skill is used by somebody or something.
162	root	1.1
163	root	1.4	=head3 cast_spell (spell casting_object owner direction stringarg -- )
164	root	1.1
165	root	1.4	Invoked whenever a given spell is cast by B<casting_object> (used by
166	root	1.1	B<owner>).
167
168	root	1.4	=head3 drop (object who -- )
169	root	1.1
170	root	1.2	Invoked whenever an item gets dropped by somebody, e.g. as a result of a
171	root	1.1	drop command.
172
173	root	1.4	=head3 drop_on (floor object who -- )
174	root	1.1
175	root	1.2	Invoked whenever some B<object> is being dropped on the B<floor> object.
176	root	1.1
177	root	1.4	=head3 listen
178	root	1.1
179	root	1.2	Invoked whenever the object can hear something beign said in its
180	root	1.1	vicinity. Not yet implemented.
181
182	root	1.4	=head3 move (monster enemy -- )
183	root	1.1
184	root	1.2	Invoked whenever the B<monster> tries to move, just after B<enemy> and
185	root	1.1	other parameters have been determined, but before movement is actually
186			executed.
187
188	root	1.4	=head3 attack (object hitter -- damage)
189	root	1.1
190			Object gets attacked by somebody - when overriden, should return the
191			damage that has been dealt.
192
193	root	1.4	=head3 attacks (weapon hitter victim)
194	root	1.1
195	root	1.2	Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
196	root	1.1	B<victim>.
197
198	root	1.4	=head3 inscribe_note (book pl message skill -- )
199	root	1.1
200			Used whenever a book gets inscribed with a message.
201
202	root	1.4	=head3 trigger (object who -- )
203	root	1.1
204	root	1.2	Invoked whenever a lever-like B<object> has been activated/triggered in some
205	root	1.1	(manual) way.
206
207	root	1.4	=head3 move_trigger (object victim originator -- )
208	root	1.1
209	root	1.2	Invoked whenever a trap-like B<object> has been activated, usually by
210	root	1.1	moving onto it. This includes not just traps, but also buttons, holes,
211			signs and similar stuff.
212
213	root	1.4	=head3 close (container -- )
214	root	1.1
215	root	1.2	Invoked whenever a container gets closed (this event is not yet reliable!).
216	root	1.1
217
218			=head2 MAP EVENTS
219
220			These events are generally dependent on a map and thus all have a map
221			as first argument.
222
223	root	1.5	=head3 instantiate (map)
224
225			Original B<map> has been loaded (e.g. on first use, or after a map
226			reset).
227
228	root	1.4	=head3 reattach (map)
229	root	1.1
230	root	1.2	Invoked whenever attachments/plug-ins need to get reattached to the
231	root	1.1	B<map>. This usually happens when the map was loaded from disk, or when the
232			server was reloaded.
233
234	root	1.5	=head3 destroy (map)
235	root	1.1
236	root	1.5	Invoked when the map object gets destroyed, and only when the map object
237			has a handler for this event. This event can occur many times, as its
238			called when the in-memory object is destroyed, not when the object itself
239			dies.
240	root	1.1
241	root	1.4	=head3 swapin (map)
242	root	1.1
243	root	1.2	Invoked when a previously swapped-out temporary B<map> has been loaded again.
244	root	1.1
245	root	1.4	=head3 swapout (map)
246	root	1.1
247	root	1.2	Invoked after a B<map> has been swapped out to disk.
248	root	1.1
249	root	1.4	=head3 reset (map)
250	root	1.1
251	root	1.2	Invoked when a B<map> gets reset.
252	root	1.1
253	root	1.4	=head3 clean (map)
254	root	1.1
255	root	1.2	Invoked when a temporary B<map> gets deleted on-disk.
256	root	1.1
257	root	1.4	=head3 enter (map player)
258	root	1.1
259	root	1.2	Invoked whenever a player enters the B<map>. This event is likely unreliable.
260	root	1.1
261	root	1.4	=head3 leave (map player)
262	root	1.1
263	root	1.2	Invoked whenever a player leaves the B<map>. This event is likely unreliable.
264	root	1.1
265	root	1.4	=head3 upgrade (map)
266	root	1.1
267	root	1.2	(TEMPORARY EVENT) gets invoked whenever a old-style map has been upgraded.
268	root	1.1