server/pod/events.pod

=head1 DELIANTRA 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 deliantra 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 was killed (hp < 0 caused by an attack) and is
about to get removed. Overriding processing will skip removal, but to do
this successfully you have to keep the object 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 reset (object)

Invoked whenever the object is initialised on a map after it was
loaded. This can be used to emulate shop-floor behaviour for example.

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

Invoked whenever a skill is used by somebody or something.

=head3 cast_spell (spell owner casting_object 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.

=head3 resource_update ()

Is invoked after each time the server reloads its resources, which is
usually one of the earliest things it does when starting up.


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

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 region_change (player newregion oldregion -- )

Invoked when a player entered a new region. Cannot be overriden.

=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 what? who? -- )

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.31
Committed:	Thu Jan 8 04:35:04 2009 UTC (17 years, 2 months ago) by root
Branch:	MAIN
CVS Tags:	rel-2_81, rel-2_80, rel-2_76, rel-2_77, rel-2_75, rel-2_79, rel-2_78
Changes since 1.30:	+1 -1 lines
Log Message:	add originator
#	Content
1	=head1 DELIANTRA 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 ATTACHABLE EVENTS
24
25	No time to document this, screw me.
26
27	=head3 instantiate (object init-args...)
28
29	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	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 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 deliantra 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
67	=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	=head3 remove (object -- )
82
83	Invoked before the object is removed from its environment.
84
85	=head3 insert (object -- )
86
87	Called after the object was inserted into a container or map.
88
89	=head3 tick (object -- )
90
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 was killed (hp < 0 caused by an attack) and is
97	about to get removed. Overriding processing will skip removal, but to do
98	this successfully you have to keep the object from dieing, otherwise the
99	event gets invoked again and again.
100
101	=head3 apply (object who -- applytype)
102
103	Invoked whenever the object is being applied in some way. The applytype is one of:
104
105	=over 4
106
107	=item B<0> player or monster can't apply objects of that type
108
109	=item B<1> has been applied, or there was an error applying the object
110
111	=item B<2> objects of that type can't be applied if not in inventory
112
113	=back
114
115	=head3 reset (object)
116
117	Invoked whenever the object is initialised on a map after it was
118	loaded. This can be used to emulate shop-floor behaviour for example.
119
120	=head3 throw (object thrower)
121
122	Invoked when an B<object> is thrown by B<thrower>.
123
124	=head3 stop (object -- )
125
126	Invoked when a thrown B<object> (arrow, other stuff) hits something and is
127	thus being "stopped".
128
129	=head3 can_apply (who object -- reason)
130
131	=head3 can_be_applied (object who -- reason)
132
133	Check wether the B<object> can be applied/readied/etc. by the
134	object B<who> and return reason otherwise. Reason is a bitset composed of
135	C<CAN_APPLY_*>-flags.
136
137	=head3 be_ready (object who -- success)
138
139	=head3 ready (who object -- success)
140
141	Invoked whenever an B<object> is being applied by object B<who>. See
142	I<can_apply> for an alternative if you just want to check wether something
143	can apply an object.
144
145	=head3 be_unready (object who -- deleted)
146
147	=head3 unready (who object -- deleted)
148
149	Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
150	currently applied by B<who>. If your override, make sure you give 'who'
151	(if it is a player) an indication of whats wrong. Must return true if the
152	object was freed.
153
154	=head3 use_skill (skill who part direction stringarg -- )
155
156	Invoked whenever a skill is used by somebody or something.
157
158	=head3 cast_spell (spell owner casting_object direction stringarg -- )
159
160	Invoked whenever a given spell is cast by B<casting_object> (used by
161	B<owner>).
162
163	=head3 drop (object who -- )
164
165	Invoked whenever an item gets dropped by somebody, e.g. as a result of a
166	drop command.
167
168	=head3 drop_on (floor object who -- )
169
170	Invoked whenever some B<object> is being dropped on the B<floor> object.
171
172	=head3 say (object player message)
173
174	Invoked whenever the I<object> can hear a B<message> being said by
175	B<player> in its vicinity.
176
177	=head3 monster_move (monster enemy -- )
178
179	Invoked whenever the B<monster> tries to move, just after B<enemy> and
180	other parameters have been determined, but before movement is actually
181	executed.
182
183	=head3 attack (object hitter -- damage)
184
185	Object gets attacked by somebody - when overriden, should return the
186	damage that has been dealt.
187
188	=head3 skill_attack (attacker victim message skill -- success)
189
190	Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill
191	cna be C<undef>). B<message> is the message that describes the attack when
192	damage is done.
193
194	=head3 weapon_attack (weapon hitter victim)
195
196	Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
197	B<victim>.
198
199	=head3 inscribe_note (book pl message skill -- )
200
201	Used whenever a book gets inscribed with a message.
202
203	=head3 trigger (object who -- )
204
205	Invoked whenever a lever-like B<object> has been activated/triggered in some
206	(manual) way.
207
208	=head3 move_trigger (object victim originator -- )
209
210	Invoked whenever a trap-like B<object> has been activated, usually by
211	moving onto it. This includes not just traps, but also buttons, holes,
212	signs and similar stuff.
213
214	=head3 open (container who -- )
215
216	Invoked whenever a container gets opened. When overriden, the container will not
217	get opened, but you must tell op about the reason.
218
219	=head3 close (container who -- )
220
221	Invoked whenever a container gets closed. When overriden, the container
222	will not get closed, but you must tell op about the reason. This event
223	is not crash-safe, i.e. containers might be closed due to a server crash
224	without this event being invoked.
225
226
227	=head2 GLOBAL EVENTS
228
229	Global events have no relation to specific objects.
230
231	=head3 cleanup ()
232
233	Called when the server is cleaning up, just before it calls exit.
234
235	=head3 clock ()
236
237	Is invoked on every server tick, usually every 0.12 seconds.
238
239	=head3 resource_update ()
240
241	Is invoked after each time the server reloads its resources, which is
242	usually one of the earliest things it does when starting up.
243
244
245	=head2 PLAYER EVENTS
246
247	Player events always have a player object as first argument.
248
249	=head3 birth (player)
250
251	Invoked as very first thing after creating a player.
252
253	=head3 quit (player)
254
255	Invoked wheneever a player quits, before actually removing him/her.
256
257	=head3 kick (player params -- )
258
259	Invoked when the given player is being kicked, before the kick is
260	executed.
261
262	=head3 load (player -- )
263
264	Invoked whenever a player has been loaded from disk, but before
265	actual login.
266
267	=head3 save (player -- )
268
269	Invoked just before a player gets serialised.
270
271	=head3 save_done (player -- )
272
273	Invoked just after a player was serialised.
274
275	=head3 connect (player -- )
276
277	Invoked just after the player object was connected to a client.
278
279	=head3 disconnect (player -- )
280
281	Invoked just before the player gets disconnected from the client.
282
283	=head3 login (player)
284
285	Invoked whenever a player logs in.
286
287	=head3 logout (player cleanly -- )
288
289	Invoked whenever a player logs out, gets disconnected etc.
290
291	=head3 death (player)
292
293	Invoked whenever a player dies, before the death actually gets processed.
294
295	=head3 map_change (player newmap x y -- )
296
297	Invoked before a player moves from one map to another, can override the movement.
298
299	=head3 region_change (player newregion oldregion -- )
300
301	Invoked when a player entered a new region. Cannot be overriden.
302
303	=head3 command (player command args -- time)
304
305	Execute a user command send by the client. Programmable plug-ins usually
306	handle this event internally.
307
308	=head3 extcmd (player string)
309
310	Invoked whenever a client issues the C<extcmd> protocol command.
311	Programmable plug-ins usually handle this event internally.
312
313	=head3 move (player direction -- )
314
315	Called whenever the player is supposed to move or attack. The handler
316	must handle the cases of speed_left or weapon_sp_left being negative,
317	fire being on, is responsible for decreaseing the speed_left value
318	on successful moves etc. etc.. When overriden, must return a boolean
319	indicating wether a move could be effected.
320
321	=head3 pray_altar (player altar skill -- )
322
323	Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
324
325	=head3 tell (player name message -- )
326
327	Invoked whenever the player uses the B<tell> or B<reply> command, before
328	it gets processed.
329
330	=head3 told (player player message -- )
331
332	Invoked right before a message is being told to a player using B<tell> or
333	B<reply>.
334
335	=head3 say (player message --)
336
337	=head3 chat (player message --)
338
339	=head3 shout (player message --)
340
341	Invoked whenever the player uses the B<say>, B<chat> or B<shout> command,
342	before it gets processed.
343
344
345	=head2 MAP EVENTS
346
347	These events are generally dependent on a map and thus all have a map
348	as first argument.
349
350	=head3 instantiate (map)
351
352	Original B<map> has been loaded (e.g. on first use, or after a map
353	reset).
354
355	=head3 swapin (map)
356
357	Invoked when a previously swapped-out temporary B<map> has been loaded again.
358
359	=head3 swapout (map)
360
361	Invoked after a B<map> has been swapped out to disk.
362
363	=head3 reset (map)
364
365	Invoked when a B<map> gets reset.
366
367	=head3 clean (map)
368
369	Invoked when a temporary B<map> gets deleted on-disk.
370
371	=head3 enter (map player x y -- )
372
373	Invoked whenever a player tries to enter the B<map>, while he/she is still
374	on the old map. Overriding means the player won't be able to enter, and,
375	if newmap/x/y are given, will be redirected to that map instead.
376
377	=head3 leave (map player -- )
378
379	Invoked whenever a player tries to leave the B<map>. Overriding means the
380	player won't be able to leave.
381
382	=head3 trigger (map connection state what? who? -- )
383
384	Invoked whenever something activates a B<connection> on the B<map>. If B<state>
385	is true the connection was 'state' and if false it is 'released'.
386
387
388	=head2 CLIENT EVENTS
389
390	These events are very similar to player events, but they are might be
391	handled asynchronously as soon as the command reaches the server, even when
392	the player hasn't logged in yet (meaning there is no player yet).
393
394	=head3 connect (client -- )
395
396	Called as soon as a new connection to the server is established. Should
397	not be overriden.
398
399	=head3 setup (client string -- )
400
401	Client sent the setup command to negotiate parameters. Handling is
402	mandatory and done by F<login.ext>.
403
404	=head3 addme (client -- )
405
406	The client sent an addme, thus ending the initial handshaking. Handling is mandatory
407	and done by F<login.ext>.
408
409	=head3 reply (client replystring -- )
410
411	Called when the client submits a reply in the ST_CUSTOM state. Usually
412	handled internally by language plugins.
413
414	=head3 exticmd (client string -- )
415
416	Like C<extcmd>, but can be called before a player has logged in.
417
418	Programmable plug-ins usually handle this event internally.
419