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 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 throw (object thrower)

Invoked when an B<object> is thrown by B<thrower>.

=head3 stop (object -- )

Invoked when a thrown B<object> (arrow, other stuff) hits something and is
thus being "stopped".

=head3 can_apply (who object -- reason)

=head3 can_be_applied (object who -- reason)

Check wether the B<object> can be applied/readied/etc. by the
object B<who> and return reason otherwise. Reason is a bitset composed of
C<CAN_APPLY_*>-flags.

=head3 be_ready (object who -- success)

=head3 ready (who object -- success)

Invoked whenever an B<object> is being applied by object B<who>. See
I<can_apply> for an alternative if you just want to check wether something
can apply an object.

=head3 be_unready (object who -- deleted)

=head3 unready (who object -- deleted)

Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
currently applied by B<who>. If your override, make sure you give 'who'
(if it is a player) an indication of whats wrong. Must return true if the
object was freed.

=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 say (object player message)

Invoked whenever the I<object> can hear a B<message> being said by
B<player> in its vicinity.

=head3 monster_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 skill_attack (attacker victim message skill -- success)

Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill
cna be C<undef>). B<message> is the message that describes the attack when
damage is done.

=head3 weapon_attack (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 who -- )

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


=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 kick (player params -- )

Invoked when the given plaer is being kicked, before the kick is executed.

=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 move (player direction -- )

=head3 pray_altar (player altar skill -- )

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

=head3 tell (player name message -- )

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

=head3 say (player message --)

=head3 chat (player message --)

=head3 shout (player message --)

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


=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.

=head3 trigger (map connection state)

Invoked whenever something activates a B<connection> on the B<map>. If B<state>
is true the connection was 'state' and if false it is 'released'.
Revision:	1.12
Committed:	Fri Sep 8 02:45:16 2006 UTC (17 years, 8 months ago) by pippijn
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.11:	+0 -0 lines
State:	*FILE REMOVED*
Log Message:	- moved events.pod to pod/ - changed build order so include/ is being built before anything else and lib/ and pod/ are built last
#	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 OBJECT EVENTS
24
25			Object events always relate to a specific object, which is always the
26			first argument. Not all events get generated for every object, some are
27			specific to an object type.
28
29	root	1.4	=head3 instantiate (object init-args...)
30	root	1.1
31			An archetype was instantiated into an object. This event occurs when
32			a map is loaded for the first time, or when the object was created
33			dynamically. The arguments are as specified in the C<attach> attribute of
34			the object or archetype.
35
36			This is useful to initialise any per-object state you might need.
37
38	root	1.4	=head3 reattach (object)
39	root	1.1
40	root	1.2	Invoked whenever attachments/plug-ins need to get reattached to the
41	root	1.1	object. This usually happens when it was loaded from disk, or when the
42			server was reloaded. This event will only be generated if the object has
43			attachments.
44
45	root	1.4	=head3 clone (object destination)
46	root	1.1
47			An object with _attached extension_ is cloned, that is, a copy was
48			made. The copy automatically has all attachments the original object
49			had. The perl variables get copied in a shallow way (references are shared
50			between instances). If this is not the behaviour you need, you have to
51			adjust the B<destination> object as you see fit.
52
53	root	1.5	=head3 destroy (object)
54
55			Invoked when the crossfire object gets destroyed, and only when the object
56			has a handler for this event. This event can occur many times, as its
57			called when the in-memory object is destroyed, not when the object itself
58			dies.
59
60	root	1.4	=head3 tick (object)
61	root	1.1
62	root	1.2	Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
63	root	1.1	during ticks should an objetc process any movement or other events.
64
65	root	1.4	=head3 kill (object hitter -- )
66	root	1.1
67	root	1.2	Invoked whenever an object is dead and about to get removed. Overriding
68	root	1.1	processing will skip removal, but to do this successfully you have to
69			objetc from dieing, otherwise the event gets invoked again and again.
70
71	root	1.4	=head3 apply (object who -- applytype)
72	root	1.1
73	root	1.2	Invoked whenever the object is being applied in some way. The applytype is one of:
74	root	1.1
75			=over 4
76
77			=item B<0> player or monster can't apply objects of that type
78
79			=item B<1> has been applied, or there was an error applying the object
80
81			=item B<2> objects of that type can't be applied if not in inventory
82
83	root	1.3	=back
84	root	1.1
85	root	1.6	=head3 throw (object thrower)
86
87			Invoked when an B<object> is thrown by B<thrower>.
88
89			=head3 stop (object -- )
90
91			Invoked when a thrown B<object> (arrow, other stuff) hits something and is
92			thus being "stopped".
93
94			=head3 can_apply (who object -- reason)
95
96			=head3 can_be_applied (object who -- reason)
97
98			Check wether the B<object> can be applied/readied/etc. by the
99			object B<who> and return reason otherwise. Reason is a bitset composed of
100			C<CAN_APPLY_*>-flags.
101
102			=head3 be_ready (object who -- success)
103
104			=head3 ready (who object -- success)
105
106			Invoked whenever an B<object> is being applied by object B<who>. See
107			I<can_apply> for an alternative if you just want to check wether something
108			can apply an object.
109
110			=head3 be_unready (object who -- deleted)
111
112			=head3 unready (who object -- deleted)
113
114			Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
115			currently applied by B<who>. If your override, make sure you give 'who'
116			(if it is a player) an indication of whats wrong. Must return true if the
117			object was freed.
118
119	root	1.4	=head3 use_skill (skill who part direction strignarg -- )
120	root	1.1
121	root	1.2	Invoked whenever a skill is used by somebody or something.
122	root	1.1
123	root	1.4	=head3 cast_spell (spell casting_object owner direction stringarg -- )
124	root	1.1
125	root	1.4	Invoked whenever a given spell is cast by B<casting_object> (used by
126	root	1.1	B<owner>).
127
128	root	1.4	=head3 drop (object who -- )
129	root	1.1
130	root	1.2	Invoked whenever an item gets dropped by somebody, e.g. as a result of a
131	root	1.1	drop command.
132
133	root	1.4	=head3 drop_on (floor object who -- )
134	root	1.1
135	root	1.2	Invoked whenever some B<object> is being dropped on the B<floor> object.
136	root	1.1
137	root	1.7	=head3 say (object player message)
138	root	1.1
139	root	1.7	Invoked whenever the I<object> can hear a B<message> being said by
140			B<player> in its vicinity.
141	root	1.1
142	root	1.10	=head3 monster_move (monster enemy -- )
143	root	1.1
144	root	1.2	Invoked whenever the B<monster> tries to move, just after B<enemy> and
145	root	1.1	other parameters have been determined, but before movement is actually
146			executed.
147
148	root	1.4	=head3 attack (object hitter -- damage)
149	root	1.1
150			Object gets attacked by somebody - when overriden, should return the
151			damage that has been dealt.
152
153	root	1.10	=head3 skill_attack (attacker victim message skill -- success)
154
155			Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill
156			cna be C<undef>). B<message> is the message that describes the attack when
157			damage is done.
158
159			=head3 weapon_attack (weapon hitter victim)
160	root	1.1
161	root	1.2	Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
162	root	1.1	B<victim>.
163
164	root	1.4	=head3 inscribe_note (book pl message skill -- )
165	root	1.1
166			Used whenever a book gets inscribed with a message.
167
168	root	1.4	=head3 trigger (object who -- )
169	root	1.1
170	root	1.2	Invoked whenever a lever-like B<object> has been activated/triggered in some
171	root	1.1	(manual) way.
172
173	root	1.4	=head3 move_trigger (object victim originator -- )
174	root	1.1
175	root	1.2	Invoked whenever a trap-like B<object> has been activated, usually by
176	root	1.1	moving onto it. This includes not just traps, but also buttons, holes,
177			signs and similar stuff.
178
179	elmex	1.11	=head3 close (container who -- )
180	root	1.1
181	root	1.2	Invoked whenever a container gets closed (this event is not yet reliable!).
182	root	1.1
183
184	root	1.6	=head2 GLOBAL EVENTS
185
186			Global events have no relation to specific objects.
187
188			=head3 clock ( )
189
190			Is invoked on every server tick, usually every 0.12 seconds.
191
192			=head2 PLAYER EVENTS
193
194			Player events always have a player object as first argument.
195
196			=head3 reattach (player)
197
198			Invoked whenever attachments/plug-ins need to get reattached to the player
199			object. This usually happens when the player gets loaded from disk, or
200			when the server is reloaded.
201
202			=head3 birth (player)
203
204			Invoked as very first thing after creating a player.
205
206			=head3 quit (player)
207
208			Invoked wheneever a player quits, before actually removing him/her.
209
210			=head3 kick (player params -- )
211
212			Invoked when the given plaer is being kicked, before the kick is executed.
213
214			=head3 load (player)
215
216			Invoked whenever a player has been loaded from disk, but before
217			actual login.
218
219			=head3 save (player)
220
221			Invoked just before a player gets saved.
222
223			=head3 login (player)
224
225			Invoked whenever a player logs in.
226
227			=head3 logout (player)
228
229			Invoked whenever a player logs out, gets disconnected etc.
230
231			=head3 death (player)
232
233			Invoked whenever a player dies, before the death actually gets processed.
234
235			=head3 map_change (player oldmap newmap)
236
237			Invoked whenever a player moves from one map to another.
238
239			=head3 extcmd (player string)
240
241			Invoked whenever a client issues the C<extcmd> protocol command. It's
242			argument is passed without any changes.
243
244	root	1.8	=head3 move (player direction -- )
245
246	root	1.6	=head3 pray_altar (player altar skill -- )
247
248			Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
249
250	root	1.8	=head3 tell (player name message -- )
251	root	1.6
252	root	1.8	Invoked whenever the player uses the B<tell> or B<reply> command, before
253			it gets processed.
254	root	1.6
255	root	1.8	=head3 say (player message --)
256	root	1.6
257	root	1.8	=head3 chat (player message --)
258	root	1.6
259	root	1.8	=head3 shout (player message --)
260	root	1.6
261	root	1.8	Invoked whenever the player uses the B<say>, B<chat> or B<shout> command,
262			before it gets processed.
263	root	1.6
264
265	root	1.1	=head2 MAP EVENTS
266
267			These events are generally dependent on a map and thus all have a map
268			as first argument.
269
270	root	1.5	=head3 instantiate (map)
271
272			Original B<map> has been loaded (e.g. on first use, or after a map
273			reset).
274
275	root	1.4	=head3 reattach (map)
276	root	1.1
277	root	1.2	Invoked whenever attachments/plug-ins need to get reattached to the
278	root	1.1	B<map>. This usually happens when the map was loaded from disk, or when the
279			server was reloaded.
280
281	root	1.5	=head3 destroy (map)
282	root	1.1
283	root	1.5	Invoked when the map object gets destroyed, and only when the map object
284			has a handler for this event. This event can occur many times, as its
285			called when the in-memory object is destroyed, not when the object itself
286			dies.
287	root	1.1
288	root	1.4	=head3 swapin (map)
289	root	1.1
290	root	1.2	Invoked when a previously swapped-out temporary B<map> has been loaded again.
291	root	1.1
292	root	1.4	=head3 swapout (map)
293	root	1.1
294	root	1.2	Invoked after a B<map> has been swapped out to disk.
295	root	1.1
296	root	1.4	=head3 reset (map)
297	root	1.1
298	root	1.2	Invoked when a B<map> gets reset.
299	root	1.1
300	root	1.4	=head3 clean (map)
301	root	1.1
302	root	1.2	Invoked when a temporary B<map> gets deleted on-disk.
303	root	1.1
304	root	1.4	=head3 enter (map player)
305	root	1.1
306	root	1.2	Invoked whenever a player enters the B<map>. This event is likely unreliable.
307	root	1.1
308	root	1.4	=head3 leave (map player)
309	root	1.1
310	root	1.2	Invoked whenever a player leaves the B<map>. This event is likely unreliable.
311	root	1.1
312	root	1.4	=head3 upgrade (map)
313	root	1.1
314	root	1.2	(TEMPORARY EVENT) gets invoked whenever a old-style map has been upgraded.
315	root	1.1
316	elmex	1.9	=head3 trigger (map connection state)
317
318			Invoked whenever something activates a B<connection> on the B<map>. If B<state>
319			is true the connection was 'state' and if false it is 'released'.