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 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 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 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 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.6
Committed:	Tue Aug 29 05:03:54 2006 UTC (17 years, 8 months ago) by root
Branch:	MAIN
Changes since 1.5:	+111 -74 lines
Log Message:	- added ready/unready/can_apply events and their passive versions - removed support for event_*-fields in maps - removed support for current_weapon_script - removed timers - removed say/shout/Tell and related commands
#	Content
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	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	=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	=head3 tick (object)
61
62	Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
63	during ticks should an objetc process any movement or other events.
64
65	=head3 kill (object hitter -- )
66
67	Invoked whenever an object is dead and about to get removed. Overriding
68	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	=head3 apply (object who -- applytype)
72
73	Invoked whenever the object is being applied in some way. The applytype is one of:
74
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	=back
84
85	=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	=head3 use_skill (skill who part direction strignarg -- )
120
121	Invoked whenever a skill is used by somebody or something.
122
123	=head3 cast_spell (spell casting_object owner direction stringarg -- )
124
125	Invoked whenever a given spell is cast by B<casting_object> (used by
126	B<owner>).
127
128	=head3 drop (object who -- )
129
130	Invoked whenever an item gets dropped by somebody, e.g. as a result of a
131	drop command.
132
133	=head3 drop_on (floor object who -- )
134
135	Invoked whenever some B<object> is being dropped on the B<floor> object.
136
137	=head3 listen
138
139	Invoked whenever the object can hear something beign said in its
140	vicinity. Not yet implemented.
141
142	=head3 move (monster enemy -- )
143
144	Invoked whenever the B<monster> tries to move, just after B<enemy> and
145	other parameters have been determined, but before movement is actually
146	executed.
147
148	=head3 attack (object hitter -- damage)
149
150	Object gets attacked by somebody - when overriden, should return the
151	damage that has been dealt.
152
153	=head3 attacks (weapon hitter victim)
154
155	Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
156	B<victim>.
157
158	=head3 inscribe_note (book pl message skill -- )
159
160	Used whenever a book gets inscribed with a message.
161
162	=head3 trigger (object who -- )
163
164	Invoked whenever a lever-like B<object> has been activated/triggered in some
165	(manual) way.
166
167	=head3 move_trigger (object victim originator -- )
168
169	Invoked whenever a trap-like B<object> has been activated, usually by
170	moving onto it. This includes not just traps, but also buttons, holes,
171	signs and similar stuff.
172
173	=head3 close (container -- )
174
175	Invoked whenever a container gets closed (this event is not yet reliable!).
176
177
178	=head2 GLOBAL EVENTS
179
180	Global events have no relation to specific objects.
181
182	=head3 clock ( )
183
184	Is invoked on every server tick, usually every 0.12 seconds.
185
186	=head2 PLAYER EVENTS
187
188	Player events always have a player object as first argument.
189
190	=head3 reattach (player)
191
192	Invoked whenever attachments/plug-ins need to get reattached to the player
193	object. This usually happens when the player gets loaded from disk, or
194	when the server is reloaded.
195
196	=head3 birth (player)
197
198	Invoked as very first thing after creating a player.
199
200	=head3 quit (player)
201
202	Invoked wheneever a player quits, before actually removing him/her.
203
204	=head3 kick (player params -- )
205
206	Invoked when the given plaer is being kicked, before the kick is executed.
207
208	=head3 load (player)
209
210	Invoked whenever a player has been loaded from disk, but before
211	actual login.
212
213	=head3 save (player)
214
215	Invoked just before a player gets saved.
216
217	=head3 login (player)
218
219	Invoked whenever a player logs in.
220
221	=head3 logout (player)
222
223	Invoked whenever a player logs out, gets disconnected etc.
224
225	=head3 death (player)
226
227	Invoked whenever a player dies, before the death actually gets processed.
228
229	=head3 map_change (player oldmap newmap)
230
231	Invoked whenever a player moves from one map to another.
232
233	=head3 extcmd (player string)
234
235	Invoked whenever a client issues the C<extcmd> protocol command. It's
236	argument is passed without any changes.
237
238	=head3 pray_altar (player altar skill -- )
239
240	Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
241
242	=head3 tell (player -- )
243
244	Invoked whenever the player uses the B<tell> command, before it gets processed.
245
246	=head3 say (player --)
247
248	Invoked whenever the player uses the B<say> command, before it gets processed.
249
250	=head3 shout (player --)
251
252	Invoked whenever the player uses the B<shout> command, before it gets processed.
253
254
255	=head2 MAP EVENTS
256
257	These events are generally dependent on a map and thus all have a map
258	as first argument.
259
260	=head3 instantiate (map)
261
262	Original B<map> has been loaded (e.g. on first use, or after a map
263	reset).
264
265	=head3 reattach (map)
266
267	Invoked whenever attachments/plug-ins need to get reattached to the
268	B<map>. This usually happens when the map was loaded from disk, or when the
269	server was reloaded.
270
271	=head3 destroy (map)
272
273	Invoked when the map object gets destroyed, and only when the map object
274	has a handler for this event. This event can occur many times, as its
275	called when the in-memory object is destroyed, not when the object itself
276	dies.
277
278	=head3 swapin (map)
279
280	Invoked when a previously swapped-out temporary B<map> has been loaded again.
281
282	=head3 swapout (map)
283
284	Invoked after a B<map> has been swapped out to disk.
285
286	=head3 reset (map)
287
288	Invoked when a B<map> gets reset.
289
290	=head3 clean (map)
291
292	Invoked when a temporary B<map> gets deleted on-disk.
293
294	=head3 enter (map player)
295
296	Invoked whenever a player enters the B<map>. This event is likely unreliable.
297
298	=head3 leave (map player)
299
300	Invoked whenever a player leaves the B<map>. This event is likely unreliable.
301
302	=head3 upgrade (map)
303
304	(TEMPORARY EVENT) gets invoked whenever a old-style map has been upgraded.
305