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 ATTACHABLE EVENTS

No time to document this, screw me.

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

An object was instantiated.

For objects, this event occurs when a map is loaded for the first time
when it was instantiated from an archetype, 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 plugin_ 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.


=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 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 remove (object -- )

Invoked before the object is removed from its environment.

=head3 insert (object -- )

Called after the object was inserted into a container or map.

=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 open (container who -- )

Invoked whenever a container gets opened. When overriden, the container will not
get opened, but you must tell op about the reason.

=head3 close (container who -- )

Invoked whenever a container gets closed. When overriden, the container
will not get closed, but you must tell op about the reason. This event
is not crash-safe, i.e. containers might be closed due to a server crash
without this event being invoked.


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

=head3 save_done (player -- )

Invoked just after a player was serialised.

=head3 connect (player -- )

Invoked just after the player object was connected to a client.

=head3 disconnect (player -- )

Invoked just before the player gets disconnected from the client.

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

Called whenever the player is supposed to move or attack. The handler
must handle the cases of speed_left or weapon_sp_left being negative,
fire being on, is responsible for decreaseing the speed_left value
on successful moves etc. etc.. When overriden, must return a boolean
indicating wether a move could be effected.

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

Invoked right before a message is being told to a player using B<tell> or
B<reply>.

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


=head2 CLIENT EVENTS

These events are very similar to player events, but they are might be
handled asynchronously as soon as the command reaches the server, even when
the player hasn't logged in yet (meaning there is no player yet).

=head3 connect (client -- )

Called as soon as a new connection to the server is established. Should
not be overriden.

=head3 setup (client string -- )

Client sent the setup command to negotiate parameters. Handling is
mandatory and done by F<login.ext>.

=head3 addme (client -- )

The client sent an addme, thus ending the initial handshaking. Handling is mandatory
and done by F<login.ext>.

=head3 reply (client replystring -- )

Called when the client submits a reply in the ST_CUSTOM state. Usually
handled internally by language plugins.

=head3 exticmd (client string -- )

Like C<extcmd>, but can be called before a player has logged in.

Programmable plug-ins usually handle this event internally.

Revision:	1.18
Committed:	Fri May 18 19:46:22 2007 UTC (17 years ago) by root
Branch:	MAIN
Changes since 1.17:	+6 -0 lines
Log Message:	new speed management: - weapon speed and object speed is now completekly decoupled for players. - both can be used at the same time, or indeepndent, when running or firing. - still only one command per object speed can be issued.
#	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	root	1.12	=head2 ATTACHABLE EVENTS
24	pippijn	1.1
25	root	1.12	No time to document this, screw me.
26	pippijn	1.1
27			=head3 instantiate (object init-args...)
28
29	root	1.12	An object was instantiated.
30
31			For objects, this event occurs when a map is loaded for the first time
32			when it was instantiated from an archetype, or when the object was created
33	pippijn	1.1	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	root	1.12	An object with _attached plugin_ is cloned, that is, a copy was made. The
48			copy automatically has all attachments the original object had. The perl
49			variables get copied in a shallow way (references are shared between
50			instances). If this is not the behaviour you need, you have to adjust the
51			B<destination> object as you see fit.
52
53			=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
61			=head2 OBJECT EVENTS
62
63			Object events always relate to a specific object, which is always the
64			first argument. Not all events get generated for every object, some are
65			specific to an object type.
66	pippijn	1.1
67	root	1.6	=head3 add_bonus (item creator difficulty max_magic flags)
68
69			A basic item has been created (e.g. for shops, monsters drops etc.)
70			that needs bonus values applied. The B<creator> object is a template
71			object that can be used to inherit stuff (and can be NULL). Flags is a
72			combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP
73			on item or set its value to 0) or GT_MINIMAL (???)
74
75			When overriden, built-in bonus generation is skipped, otherwise
76			treasure generation continues as it would without this hook.
77
78			In general, if flags != 0 or creator != 0 you should just return and leave
79			item generation to the standard code.
80
81	root	1.12	=head3 remove (object -- )
82
83			Invoked before the object is removed from its environment.
84
85			=head3 insert (object -- )
86	pippijn	1.1
87	root	1.12	Called after the object was inserted into a container or map.
88	pippijn	1.1
89	root	1.12	=head3 tick (object -- )
90	pippijn	1.1
91			Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
92			during ticks should an objetc process any movement or other events.
93
94			=head3 kill (object hitter -- )
95
96			Invoked whenever an object is dead and about to get removed. Overriding
97			processing will skip removal, but to do this successfully you have to
98			objetc from dieing, otherwise the event gets invoked again and again.
99
100			=head3 apply (object who -- applytype)
101
102			Invoked whenever the object is being applied in some way. The applytype is one of:
103
104			=over 4
105
106			=item B<0> player or monster can't apply objects of that type
107
108			=item B<1> has been applied, or there was an error applying the object
109
110			=item B<2> objects of that type can't be applied if not in inventory
111
112			=back
113
114			=head3 throw (object thrower)
115
116			Invoked when an B<object> is thrown by B<thrower>.
117
118			=head3 stop (object -- )
119
120			Invoked when a thrown B<object> (arrow, other stuff) hits something and is
121			thus being "stopped".
122
123			=head3 can_apply (who object -- reason)
124
125			=head3 can_be_applied (object who -- reason)
126
127			Check wether the B<object> can be applied/readied/etc. by the
128			object B<who> and return reason otherwise. Reason is a bitset composed of
129			C<CAN_APPLY_*>-flags.
130
131			=head3 be_ready (object who -- success)
132
133			=head3 ready (who object -- success)
134
135			Invoked whenever an B<object> is being applied by object B<who>. See
136			I<can_apply> for an alternative if you just want to check wether something
137			can apply an object.
138
139			=head3 be_unready (object who -- deleted)
140
141			=head3 unready (who object -- deleted)
142
143			Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
144			currently applied by B<who>. If your override, make sure you give 'who'
145			(if it is a player) an indication of whats wrong. Must return true if the
146			object was freed.
147
148			=head3 use_skill (skill who part direction strignarg -- )
149
150			Invoked whenever a skill is used by somebody or something.
151
152			=head3 cast_spell (spell casting_object owner direction stringarg -- )
153
154			Invoked whenever a given spell is cast by B<casting_object> (used by
155			B<owner>).
156
157			=head3 drop (object who -- )
158
159			Invoked whenever an item gets dropped by somebody, e.g. as a result of a
160			drop command.
161
162			=head3 drop_on (floor object who -- )
163
164			Invoked whenever some B<object> is being dropped on the B<floor> object.
165
166			=head3 say (object player message)
167
168			Invoked whenever the I<object> can hear a B<message> being said by
169			B<player> in its vicinity.
170
171			=head3 monster_move (monster enemy -- )
172
173			Invoked whenever the B<monster> tries to move, just after B<enemy> and
174			other parameters have been determined, but before movement is actually
175			executed.
176
177			=head3 attack (object hitter -- damage)
178
179			Object gets attacked by somebody - when overriden, should return the
180			damage that has been dealt.
181
182			=head3 skill_attack (attacker victim message skill -- success)
183
184			Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill
185			cna be C<undef>). B<message> is the message that describes the attack when
186			damage is done.
187
188			=head3 weapon_attack (weapon hitter victim)
189
190			Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
191			B<victim>.
192
193			=head3 inscribe_note (book pl message skill -- )
194
195			Used whenever a book gets inscribed with a message.
196
197			=head3 trigger (object who -- )
198
199			Invoked whenever a lever-like B<object> has been activated/triggered in some
200			(manual) way.
201
202			=head3 move_trigger (object victim originator -- )
203
204			Invoked whenever a trap-like B<object> has been activated, usually by
205			moving onto it. This includes not just traps, but also buttons, holes,
206			signs and similar stuff.
207
208	root	1.15	=head3 open (container who -- )
209
210			Invoked whenever a container gets opened. When overriden, the container will not
211			get opened, but you must tell op about the reason.
212
213	pippijn	1.1	=head3 close (container who -- )
214
215	root	1.15	Invoked whenever a container gets closed. When overriden, the container
216			will not get closed, but you must tell op about the reason. This event
217			is not crash-safe, i.e. containers might be closed due to a server crash
218			without this event being invoked.
219	pippijn	1.1
220
221			=head2 GLOBAL EVENTS
222
223			Global events have no relation to specific objects.
224
225	root	1.3	=head3 cleanup ()
226
227			Called when the server is cleaning up, just before it calls exit.
228
229	pippijn	1.1	=head3 clock ( )
230
231			Is invoked on every server tick, usually every 0.12 seconds.
232
233	root	1.3
234	pippijn	1.1	=head2 PLAYER EVENTS
235
236			Player events always have a player object as first argument.
237
238			=head3 birth (player)
239
240			Invoked as very first thing after creating a player.
241
242			=head3 quit (player)
243
244			Invoked wheneever a player quits, before actually removing him/her.
245
246			=head3 kick (player params -- )
247
248	root	1.14	Invoked when the given player is being kicked, before the kick is
249			executed.
250	pippijn	1.1
251	root	1.14	=head3 load (player -- )
252	pippijn	1.1
253			Invoked whenever a player has been loaded from disk, but before
254			actual login.
255
256	root	1.14	=head3 save (player -- )
257	pippijn	1.1
258	root	1.14	Invoked just before a player gets serialised.
259	pippijn	1.1
260	root	1.14	=head3 save_done (player -- )
261	root	1.13
262	root	1.14	Invoked just after a player was serialised.
263	root	1.13
264			=head3 connect (player -- )
265
266			Invoked just after the player object was connected to a client.
267
268			=head3 disconnect (player -- )
269
270			Invoked just before the player gets disconnected from the client.
271
272	pippijn	1.1	=head3 login (player)
273
274			Invoked whenever a player logs in.
275
276			=head3 logout (player)
277
278			Invoked whenever a player logs out, gets disconnected etc.
279
280			=head3 death (player)
281
282			Invoked whenever a player dies, before the death actually gets processed.
283
284	root	1.4	=head3 map_change (player newmap x y -- )
285	pippijn	1.1
286	root	1.4	Invoked before a player moves from one map to another, can override the movement.
287	pippijn	1.1
288	root	1.7	=head3 command (player command args -- time)
289
290			Execute a user command send by the client. Programmable plug-ins usually
291			handle this event internally.
292
293	pippijn	1.1	=head3 extcmd (player string)
294
295	root	1.7	Invoked whenever a client issues the C<extcmd> protocol command.
296			Programmable plug-ins usually handle this event internally.
297	pippijn	1.1
298			=head3 move (player direction -- )
299
300	root	1.18	Called whenever the player is supposed to move or attack. The handler
301			must handle the cases of speed_left or weapon_sp_left being negative,
302			fire being on, is responsible for decreaseing the speed_left value
303			on successful moves etc. etc.. When overriden, must return a boolean
304			indicating wether a move could be effected.
305
306	pippijn	1.1	=head3 pray_altar (player altar skill -- )
307
308			Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
309
310			=head3 tell (player name message -- )
311
312			Invoked whenever the player uses the B<tell> or B<reply> command, before
313			it gets processed.
314
315	pippijn	1.16	=head3 told (player player message -- )
316
317			Invoked right before a message is being told to a player using B<tell> or
318			B<reply>.
319
320	pippijn	1.1	=head3 say (player message --)
321
322			=head3 chat (player message --)
323
324			=head3 shout (player message --)
325
326			Invoked whenever the player uses the B<say>, B<chat> or B<shout> command,
327			before it gets processed.
328
329
330			=head2 MAP EVENTS
331
332			These events are generally dependent on a map and thus all have a map
333			as first argument.
334
335			=head3 instantiate (map)
336
337			Original B<map> has been loaded (e.g. on first use, or after a map
338			reset).
339
340			=head3 swapin (map)
341
342			Invoked when a previously swapped-out temporary B<map> has been loaded again.
343
344			=head3 swapout (map)
345
346			Invoked after a B<map> has been swapped out to disk.
347
348			=head3 reset (map)
349
350			Invoked when a B<map> gets reset.
351
352			=head3 clean (map)
353
354			Invoked when a temporary B<map> gets deleted on-disk.
355
356	root	1.4	=head3 enter (map player x y -- )
357	pippijn	1.1
358	root	1.4	Invoked whenever a player tries to enter the B<map>, while he/she is still
359	root	1.5	on the old map. Overriding means the player won't be able to enter, and,
360			if newmap/x/y are given, will be redirected to that map instead.
361	pippijn	1.1
362	root	1.4	=head3 leave (map player -- )
363	pippijn	1.1
364	root	1.4	Invoked whenever a player tries to leave the B<map>. Overriding means the
365			player won't be able to leave.
366	pippijn	1.1
367	root	1.9	=head3 trigger (map connection state -- )
368	pippijn	1.1
369			Invoked whenever something activates a B<connection> on the B<map>. If B<state>
370			is true the connection was 'state' and if false it is 'released'.
371	root	1.5
372	root	1.8
373			=head2 CLIENT EVENTS
374
375			These events are very similar to player events, but they are might be
376			handled asynchronously as soon as the command reaches the server, even when
377			the player hasn't logged in yet (meaning there is no player yet).
378
379	root	1.9	=head3 connect (client -- )
380
381			Called as soon as a new connection to the server is established. Should
382			not be overriden.
383
384	root	1.17	=head3 setup (client string -- )
385
386			Client sent the setup command to negotiate parameters. Handling is
387			mandatory and done by F<login.ext>.
388
389	root	1.9	=head3 addme (client -- )
390
391	root	1.17	The client sent an addme, thus ending the initial handshaking. Handling is mandatory
392			and done by F<login.ext>.
393	root	1.9
394	root	1.10	=head3 reply (client replystring -- )
395
396			Called when the client submits a reply in the ST_CUSTOM state. Usually
397			handled internally by language plugins.
398
399	root	1.9	=head3 exticmd (client string -- )
400	root	1.8
401			Like C<extcmd>, but can be called before a player has logged in.
402
403			Programmable plug-ins usually handle this event internally.
404