server/pod/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 add_bonus (item creator difficulty max_magic flags)

A basic item has been created (e.g. for shops, monsters drops etc.)
that needs bonus values applied. The B<creator> object is a template
object that can be used to inherit stuff (and can be NULL). Flags is a
combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP
on item or set its value to 0) or GT_MINIMAL (???)

When overriden, built-in bonus generation is skipped, otherwise
treasure generation continues as it would without this hook.

In general, if flags != 0 or creator != 0 you should just return and leave
item generation to the standard code.

=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 cleanup ()

Called when the server is cleaning up, just before it calls exit.

=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 newmap x y -- )

Invoked before a player moves from one map to another, can override the movement.

=head3 command (player command args -- time)

Execute a user command send by the client. Programmable plug-ins usually
handle this event internally.

=head3 extcmd (player string)

Invoked whenever a client issues the C<extcmd> protocol command.
Programmable plug-ins usually handle this event internally.

=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 x y -- )

Invoked whenever a player tries to enter the B<map>, while he/she is still
on the old map. Overriding means the player won't be able to enter, and,
if newmap/x/y are given, will be redirected to that map instead.

=head3 leave (map player -- )

Invoked whenever a player tries to leave the B<map>. Overriding means the
player won't be able to leave.

=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.7
Committed:	Mon Dec 11 22:56:57 2006 UTC (17 years, 5 months ago) by root
Branch:	MAIN
Changes since 1.6:	+7 -2 lines
Log Message:	- use new event mechanism for command handling instead of the old plugin system
#	User	Rev	Content
1	elmex	1.2	=head1 CROSSFIRE+ PLUG-IN EVENTS
2	pippijn	1.1
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			missing, the event will be invoked but cannot change wether the event gets
13			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			=head3 instantiate (object init-args...)
30
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			=head3 reattach (object)
39
40			Invoked whenever attachments/plug-ins need to get reattached to the
41			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			=head3 clone (object destination)
46
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.6	=head3 add_bonus (item creator difficulty max_magic flags)
54
55			A basic item has been created (e.g. for shops, monsters drops etc.)
56			that needs bonus values applied. The B<creator> object is a template
57			object that can be used to inherit stuff (and can be NULL). Flags is a
58			combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP
59			on item or set its value to 0) or GT_MINIMAL (???)
60
61			When overriden, built-in bonus generation is skipped, otherwise
62			treasure generation continues as it would without this hook.
63
64			In general, if flags != 0 or creator != 0 you should just return and leave
65			item generation to the standard code.
66
67	pippijn	1.1	=head3 destroy (object)
68
69			Invoked when the crossfire object gets destroyed, and only when the object
70			has a handler for this event. This event can occur many times, as its
71			called when the in-memory object is destroyed, not when the object itself
72			dies.
73
74			=head3 tick (object)
75
76			Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
77			during ticks should an objetc process any movement or other events.
78
79			=head3 kill (object hitter -- )
80
81			Invoked whenever an object is dead and about to get removed. Overriding
82			processing will skip removal, but to do this successfully you have to
83			objetc from dieing, otherwise the event gets invoked again and again.
84
85			=head3 apply (object who -- applytype)
86
87			Invoked whenever the object is being applied in some way. The applytype is one of:
88
89			=over 4
90
91			=item B<0> player or monster can't apply objects of that type
92
93			=item B<1> has been applied, or there was an error applying the object
94
95			=item B<2> objects of that type can't be applied if not in inventory
96
97			=back
98
99			=head3 throw (object thrower)
100
101			Invoked when an B<object> is thrown by B<thrower>.
102
103			=head3 stop (object -- )
104
105			Invoked when a thrown B<object> (arrow, other stuff) hits something and is
106			thus being "stopped".
107
108			=head3 can_apply (who object -- reason)
109
110			=head3 can_be_applied (object who -- reason)
111
112			Check wether the B<object> can be applied/readied/etc. by the
113			object B<who> and return reason otherwise. Reason is a bitset composed of
114			C<CAN_APPLY_*>-flags.
115
116			=head3 be_ready (object who -- success)
117
118			=head3 ready (who object -- success)
119
120			Invoked whenever an B<object> is being applied by object B<who>. See
121			I<can_apply> for an alternative if you just want to check wether something
122			can apply an object.
123
124			=head3 be_unready (object who -- deleted)
125
126			=head3 unready (who object -- deleted)
127
128			Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
129			currently applied by B<who>. If your override, make sure you give 'who'
130			(if it is a player) an indication of whats wrong. Must return true if the
131			object was freed.
132
133			=head3 use_skill (skill who part direction strignarg -- )
134
135			Invoked whenever a skill is used by somebody or something.
136
137			=head3 cast_spell (spell casting_object owner direction stringarg -- )
138
139			Invoked whenever a given spell is cast by B<casting_object> (used by
140			B<owner>).
141
142			=head3 drop (object who -- )
143
144			Invoked whenever an item gets dropped by somebody, e.g. as a result of a
145			drop command.
146
147			=head3 drop_on (floor object who -- )
148
149			Invoked whenever some B<object> is being dropped on the B<floor> object.
150
151			=head3 say (object player message)
152
153			Invoked whenever the I<object> can hear a B<message> being said by
154			B<player> in its vicinity.
155
156			=head3 monster_move (monster enemy -- )
157
158			Invoked whenever the B<monster> tries to move, just after B<enemy> and
159			other parameters have been determined, but before movement is actually
160			executed.
161
162			=head3 attack (object hitter -- damage)
163
164			Object gets attacked by somebody - when overriden, should return the
165			damage that has been dealt.
166
167			=head3 skill_attack (attacker victim message skill -- success)
168
169			Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill
170			cna be C<undef>). B<message> is the message that describes the attack when
171			damage is done.
172
173			=head3 weapon_attack (weapon hitter victim)
174
175			Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
176			B<victim>.
177
178			=head3 inscribe_note (book pl message skill -- )
179
180			Used whenever a book gets inscribed with a message.
181
182			=head3 trigger (object who -- )
183
184			Invoked whenever a lever-like B<object> has been activated/triggered in some
185			(manual) way.
186
187			=head3 move_trigger (object victim originator -- )
188
189			Invoked whenever a trap-like B<object> has been activated, usually by
190			moving onto it. This includes not just traps, but also buttons, holes,
191			signs and similar stuff.
192
193			=head3 close (container who -- )
194
195			Invoked whenever a container gets closed (this event is not yet reliable!).
196
197
198			=head2 GLOBAL EVENTS
199
200			Global events have no relation to specific objects.
201
202	root	1.3	=head3 cleanup ()
203
204			Called when the server is cleaning up, just before it calls exit.
205
206	pippijn	1.1	=head3 clock ( )
207
208			Is invoked on every server tick, usually every 0.12 seconds.
209
210	root	1.3
211	pippijn	1.1	=head2 PLAYER EVENTS
212
213			Player events always have a player object as first argument.
214
215			=head3 reattach (player)
216
217			Invoked whenever attachments/plug-ins need to get reattached to the player
218			object. This usually happens when the player gets loaded from disk, or
219			when the server is reloaded.
220
221			=head3 birth (player)
222
223			Invoked as very first thing after creating a player.
224
225			=head3 quit (player)
226
227			Invoked wheneever a player quits, before actually removing him/her.
228
229			=head3 kick (player params -- )
230
231			Invoked when the given plaer is being kicked, before the kick is executed.
232
233			=head3 load (player)
234
235			Invoked whenever a player has been loaded from disk, but before
236			actual login.
237
238			=head3 save (player)
239
240			Invoked just before a player gets saved.
241
242			=head3 login (player)
243
244			Invoked whenever a player logs in.
245
246			=head3 logout (player)
247
248			Invoked whenever a player logs out, gets disconnected etc.
249
250			=head3 death (player)
251
252			Invoked whenever a player dies, before the death actually gets processed.
253
254	root	1.4	=head3 map_change (player newmap x y -- )
255	pippijn	1.1
256	root	1.4	Invoked before a player moves from one map to another, can override the movement.
257	pippijn	1.1
258	root	1.7	=head3 command (player command args -- time)
259
260			Execute a user command send by the client. Programmable plug-ins usually
261			handle this event internally.
262
263	pippijn	1.1	=head3 extcmd (player string)
264
265	root	1.7	Invoked whenever a client issues the C<extcmd> protocol command.
266			Programmable plug-ins usually handle this event internally.
267	pippijn	1.1
268			=head3 move (player direction -- )
269
270			=head3 pray_altar (player altar skill -- )
271
272			Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
273
274			=head3 tell (player name message -- )
275
276			Invoked whenever the player uses the B<tell> or B<reply> command, before
277			it gets processed.
278
279			=head3 say (player message --)
280
281			=head3 chat (player message --)
282
283			=head3 shout (player message --)
284
285			Invoked whenever the player uses the B<say>, B<chat> or B<shout> command,
286			before it gets processed.
287
288
289			=head2 MAP EVENTS
290
291			These events are generally dependent on a map and thus all have a map
292			as first argument.
293
294			=head3 instantiate (map)
295
296			Original B<map> has been loaded (e.g. on first use, or after a map
297			reset).
298
299			=head3 reattach (map)
300
301			Invoked whenever attachments/plug-ins need to get reattached to the
302			B<map>. This usually happens when the map was loaded from disk, or when the
303			server was reloaded.
304
305			=head3 destroy (map)
306
307			Invoked when the map object gets destroyed, and only when the map object
308			has a handler for this event. This event can occur many times, as its
309			called when the in-memory object is destroyed, not when the object itself
310			dies.
311
312			=head3 swapin (map)
313
314			Invoked when a previously swapped-out temporary B<map> has been loaded again.
315
316			=head3 swapout (map)
317
318			Invoked after a B<map> has been swapped out to disk.
319
320			=head3 reset (map)
321
322			Invoked when a B<map> gets reset.
323
324			=head3 clean (map)
325
326			Invoked when a temporary B<map> gets deleted on-disk.
327
328	root	1.4	=head3 enter (map player x y -- )
329	pippijn	1.1
330	root	1.4	Invoked whenever a player tries to enter the B<map>, while he/she is still
331	root	1.5	on the old map. Overriding means the player won't be able to enter, and,
332			if newmap/x/y are given, will be redirected to that map instead.
333	pippijn	1.1
334	root	1.4	=head3 leave (map player -- )
335	pippijn	1.1
336	root	1.4	Invoked whenever a player tries to leave the B<map>. Overriding means the
337			player won't be able to leave.
338	pippijn	1.1
339			=head3 trigger (map connection state)
340
341			Invoked whenever something activates a B<connection> on the B<map>. If B<state>
342			is true the connection was 'state' and if false it is 'released'.
343	root	1.5