server/pod/events.pod

=begin comment

 This file is part of Deliantra, the Roguelike Realtime MMORPG.
  
 Copyright (©) 2005,2006,2007,2008,2009 Marc Alexander Lehmann / Robin Redeker / the Deliantra team
  
 Deliantra is free software: you can redistribute it and/or modify it under
 the terms of the Affero GNU General Public License as published by the
 Free Software Foundation, either version 3 of the License, or (at your
 option) any later version.
  
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 GNU General Public License for more details.
  
 You should have received a copy of the Affero GNU General Public License
 and the GNU General Public License along with this program. If not, see
 <http://www.gnu.org/licenses/>.
  
 The authors can be reached via e-mail to <support@deliantra.net>

=end comment

=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 part is
missing, the event will be invoked but cannot change wether the event gets
processed.

Return values are given by overriding (in Perl by calling C<cf::override>)
with the return values, which will both stop further event processing and
tell the caller that it wants to override normal processing.

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

=head3 blocked_move (self who -- do_blocked)

Invoked when an C<who> tries to move to the same space as C<self>,
C<self>'s C<move_block> causes blocked movement for C<who> and nothing
else explicitly allows movement to this space.

Should return true when C<who> is blocked, i.e., should not be allowed to
move onto C<self>.

When not overriding, normal blocked_move (blocked_link) processing will
happen.


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

=head3 build (player builder map x y --)

Players tries to build using C<builder> at (map+x+y). Is invoked after the
usual sanity checks, so the coordinates are valid.


=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.35
Committed:	Fri Mar 19 22:16:27 2010 UTC (14 years, 2 months ago) by root
Branch:	MAIN
Changes since 1.34:	+3 -2 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.33	=begin comment
2
3			This file is part of Deliantra, the Roguelike Realtime MMORPG.
4
5			Copyright (©) 2005,2006,2007,2008,2009 Marc Alexander Lehmann / Robin Redeker / the Deliantra team
6
7			Deliantra is free software: you can redistribute it and/or modify it under
8			the terms of the Affero GNU General Public License as published by the
9			Free Software Foundation, either version 3 of the License, or (at your
10			option) any later version.
11
12			This program is distributed in the hope that it will be useful,
13			but WITHOUT ANY WARRANTY; without even the implied warranty of
14			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15			GNU General Public License for more details.
16
17			You should have received a copy of the Affero GNU General Public License
18			and the GNU General Public License along with this program. If not, see
19			<http://www.gnu.org/licenses/>.
20
21			The authors can be reached via e-mail to <support@deliantra.net>
22
23			=end comment
24
25	root	1.23	=head1 DELIANTRA PLUG-IN EVENTS
26	pippijn	1.1
27			This document briefly describes each plug-in event. It is also used to
28			generate the event-list itself, so is always complete. Be careful wehn
29			changing it, though.
30
31			=head2 NOTATION
32
33	root	1.32	The event description below uses a variant of the forth stack notation -
34	pippijn	1.1	an opening parenthesis followed by the type of each parameter, optionally
35	root	1.32	followed by two dashes and the returning parameters. If the latter part is
36	pippijn	1.1	missing, the event will be invoked but cannot change wether the event gets
37			processed.
38
39	root	1.32	Return values are given by overriding (in Perl by calling C<cf::override>)
40			with the return values, which will both stop further event processing and
41			tell the caller that it wants to override normal processing.
42
43			Even if no return values are supported, a plug-in can override (e.g. using
44			C<cf::override> in Perl) event processing, basically short-circuiting
45			it. For example, if you override from within a player BIRTH event,
46			nothing much will happen with respect to the built-in processing, but if
47			you override from within a player TELL event, the tell will be ignored
48			(presumably your plug-in took care of it).
49	pippijn	1.1
50
51	root	1.12	=head2 ATTACHABLE EVENTS
52	pippijn	1.1
53	root	1.12	No time to document this, screw me.
54	pippijn	1.1
55			=head3 instantiate (object init-args...)
56
57	root	1.12	An object was instantiated.
58
59			For objects, this event occurs when a map is loaded for the first time
60			when it was instantiated from an archetype, or when the object was created
61	pippijn	1.1	dynamically. The arguments are as specified in the C<attach> attribute of
62			the object or archetype.
63
64			This is useful to initialise any per-object state you might need.
65
66			=head3 reattach (object)
67
68			Invoked whenever attachments/plug-ins need to get reattached to the
69			object. This usually happens when it was loaded from disk, or when the
70			server was reloaded. This event will only be generated if the object has
71			attachments.
72
73			=head3 clone (object destination)
74
75	root	1.12	An object with _attached plugin_ is cloned, that is, a copy was made. The
76			copy automatically has all attachments the original object had. The perl
77			variables get copied in a shallow way (references are shared between
78			instances). If this is not the behaviour you need, you have to adjust the
79			B<destination> object as you see fit.
80
81			=head3 destroy (object -- )
82
83	root	1.23	Invoked when the deliantra object gets destroyed, and only when the object
84	root	1.12	has a handler for this event. This event can occur many times, as its
85			called when the in-memory object is destroyed, not when the object itself
86			dies.
87
88
89			=head2 OBJECT EVENTS
90
91			Object events always relate to a specific object, which is always the
92			first argument. Not all events get generated for every object, some are
93			specific to an object type.
94	pippijn	1.1
95	root	1.20	=head3 add_bonus (item creator difficulty max_magic flags -- )
96	root	1.6
97			A basic item has been created (e.g. for shops, monsters drops etc.)
98			that needs bonus values applied. The B<creator> object is a template
99			object that can be used to inherit stuff (and can be NULL). Flags is a
100			combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP
101			on item or set its value to 0) or GT_MINIMAL (???)
102
103			When overriden, built-in bonus generation is skipped, otherwise
104			treasure generation continues as it would without this hook.
105
106			In general, if flags != 0 or creator != 0 you should just return and leave
107			item generation to the standard code.
108
109	root	1.12	=head3 remove (object -- )
110
111			Invoked before the object is removed from its environment.
112
113			=head3 insert (object -- )
114	pippijn	1.1
115	root	1.12	Called after the object was inserted into a container or map.
116	pippijn	1.1
117	root	1.12	=head3 tick (object -- )
118	pippijn	1.1
119			Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
120			during ticks should an objetc process any movement or other events.
121
122			=head3 kill (object hitter -- )
123
124	root	1.25	Invoked whenever an object was killed (hp < 0 caused by an attack) and is
125			about to get removed. Overriding processing will skip removal, but to do
126			this successfully you have to keep the object from dieing, otherwise the
127			event gets invoked again and again.
128	pippijn	1.1
129			=head3 apply (object who -- applytype)
130
131			Invoked whenever the object is being applied in some way. The applytype is one of:
132
133			=over 4
134
135			=item B<0> player or monster can't apply objects of that type
136
137			=item B<1> has been applied, or there was an error applying the object
138
139			=item B<2> objects of that type can't be applied if not in inventory
140
141			=back
142
143	root	1.27	=head3 reset (object)
144
145			Invoked whenever the object is initialised on a map after it was
146			loaded. This can be used to emulate shop-floor behaviour for example.
147
148	pippijn	1.1	=head3 throw (object thrower)
149
150			Invoked when an B<object> is thrown by B<thrower>.
151
152			=head3 stop (object -- )
153
154			Invoked when a thrown B<object> (arrow, other stuff) hits something and is
155			thus being "stopped".
156
157			=head3 can_apply (who object -- reason)
158
159			=head3 can_be_applied (object who -- reason)
160
161			Check wether the B<object> can be applied/readied/etc. by the
162			object B<who> and return reason otherwise. Reason is a bitset composed of
163			C<CAN_APPLY_*>-flags.
164
165			=head3 be_ready (object who -- success)
166
167			=head3 ready (who object -- success)
168
169			Invoked whenever an B<object> is being applied by object B<who>. See
170			I<can_apply> for an alternative if you just want to check wether something
171			can apply an object.
172
173			=head3 be_unready (object who -- deleted)
174
175			=head3 unready (who object -- deleted)
176
177			Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
178			currently applied by B<who>. If your override, make sure you give 'who'
179			(if it is a player) an indication of whats wrong. Must return true if the
180			object was freed.
181
182	root	1.19	=head3 use_skill (skill who part direction stringarg -- )
183	pippijn	1.1
184			Invoked whenever a skill is used by somebody or something.
185
186	root	1.19	=head3 cast_spell (spell owner casting_object direction stringarg -- )
187	pippijn	1.1
188			Invoked whenever a given spell is cast by B<casting_object> (used by
189			B<owner>).
190
191			=head3 drop (object who -- )
192
193			Invoked whenever an item gets dropped by somebody, e.g. as a result of a
194			drop command.
195
196			=head3 drop_on (floor object who -- )
197
198			Invoked whenever some B<object> is being dropped on the B<floor> object.
199
200			=head3 say (object player message)
201
202			Invoked whenever the I<object> can hear a B<message> being said by
203			B<player> in its vicinity.
204
205			=head3 monster_move (monster enemy -- )
206
207			Invoked whenever the B<monster> tries to move, just after B<enemy> and
208			other parameters have been determined, but before movement is actually
209			executed.
210
211			=head3 attack (object hitter -- damage)
212
213			Object gets attacked by somebody - when overriden, should return the
214			damage that has been dealt.
215
216			=head3 skill_attack (attacker victim message skill -- success)
217
218			Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill
219	root	1.32	can be C<undef>). B<message> is the message that describes the attack when
220	pippijn	1.1	damage is done.
221
222			=head3 weapon_attack (weapon hitter victim)
223
224			Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
225			B<victim>.
226
227			=head3 inscribe_note (book pl message skill -- )
228
229			Used whenever a book gets inscribed with a message.
230
231			=head3 trigger (object who -- )
232
233			Invoked whenever a lever-like B<object> has been activated/triggered in some
234			(manual) way.
235
236			=head3 move_trigger (object victim originator -- )
237
238			Invoked whenever a trap-like B<object> has been activated, usually by
239			moving onto it. This includes not just traps, but also buttons, holes,
240			signs and similar stuff.
241
242	root	1.15	=head3 open (container who -- )
243
244			Invoked whenever a container gets opened. When overriden, the container will not
245			get opened, but you must tell op about the reason.
246
247	pippijn	1.1	=head3 close (container who -- )
248
249	root	1.15	Invoked whenever a container gets closed. When overriden, the container
250			will not get closed, but you must tell op about the reason. This event
251			is not crash-safe, i.e. containers might be closed due to a server crash
252			without this event being invoked.
253	pippijn	1.1
254	root	1.32	=head3 blocked_move (self who -- do_blocked)
255
256			Invoked when an C<who> tries to move to the same space as C<self>,
257			C<self>'s C<move_block> causes blocked movement for C<who> and nothing
258			else explicitly allows movement to this space.
259
260			Should return true when C<who> is blocked, i.e., should not be allowed to
261			move onto C<self>.
262
263			When not overriding, normal blocked_move (blocked_link) processing will
264			happen.
265
266	pippijn	1.1
267			=head2 GLOBAL EVENTS
268
269			Global events have no relation to specific objects.
270
271	root	1.3	=head3 cleanup ()
272
273			Called when the server is cleaning up, just before it calls exit.
274
275	root	1.24	=head3 clock ()
276	pippijn	1.1
277			Is invoked on every server tick, usually every 0.12 seconds.
278
279	root	1.24	=head3 resource_update ()
280
281			Is invoked after each time the server reloads its resources, which is
282			usually one of the earliest things it does when starting up.
283
284	root	1.3
285	pippijn	1.1	=head2 PLAYER EVENTS
286
287			Player events always have a player object as first argument.
288
289			=head3 birth (player)
290
291			Invoked as very first thing after creating a player.
292
293			=head3 quit (player)
294
295			Invoked wheneever a player quits, before actually removing him/her.
296
297			=head3 kick (player params -- )
298
299	root	1.14	Invoked when the given player is being kicked, before the kick is
300			executed.
301	pippijn	1.1
302	root	1.14	=head3 load (player -- )
303	pippijn	1.1
304			Invoked whenever a player has been loaded from disk, but before
305			actual login.
306
307	root	1.14	=head3 save (player -- )
308	pippijn	1.1
309	root	1.14	Invoked just before a player gets serialised.
310	pippijn	1.1
311	root	1.14	=head3 save_done (player -- )
312	root	1.13
313	root	1.14	Invoked just after a player was serialised.
314	root	1.13
315			=head3 connect (player -- )
316
317			Invoked just after the player object was connected to a client.
318
319			=head3 disconnect (player -- )
320
321			Invoked just before the player gets disconnected from the client.
322
323	pippijn	1.1	=head3 login (player)
324
325			Invoked whenever a player logs in.
326
327	root	1.21	=head3 logout (player cleanly -- )
328	pippijn	1.1
329			Invoked whenever a player logs out, gets disconnected etc.
330
331			=head3 death (player)
332
333			Invoked whenever a player dies, before the death actually gets processed.
334
335	root	1.4	=head3 map_change (player newmap x y -- )
336	pippijn	1.1
337	root	1.4	Invoked before a player moves from one map to another, can override the movement.
338	pippijn	1.1
339	root	1.22	=head3 region_change (player newregion oldregion -- )
340
341			Invoked when a player entered a new region. Cannot be overriden.
342
343	root	1.7	=head3 command (player command args -- time)
344
345			Execute a user command send by the client. Programmable plug-ins usually
346			handle this event internally.
347
348	pippijn	1.1	=head3 extcmd (player string)
349
350	root	1.7	Invoked whenever a client issues the C<extcmd> protocol command.
351			Programmable plug-ins usually handle this event internally.
352	pippijn	1.1
353			=head3 move (player direction -- )
354
355	root	1.18	Called whenever the player is supposed to move or attack. The handler
356			must handle the cases of speed_left or weapon_sp_left being negative,
357			fire being on, is responsible for decreaseing the speed_left value
358			on successful moves etc. etc.. When overriden, must return a boolean
359			indicating wether a move could be effected.
360
361	pippijn	1.1	=head3 pray_altar (player altar skill -- )
362
363			Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
364
365			=head3 tell (player name message -- )
366
367			Invoked whenever the player uses the B<tell> or B<reply> command, before
368			it gets processed.
369
370	pippijn	1.16	=head3 told (player player message -- )
371
372			Invoked right before a message is being told to a player using B<tell> or
373			B<reply>.
374
375	pippijn	1.1	=head3 say (player message --)
376
377			=head3 chat (player message --)
378
379			=head3 shout (player message --)
380
381			Invoked whenever the player uses the B<say>, B<chat> or B<shout> command,
382			before it gets processed.
383
384	root	1.35	=head3 build (player builder map x y --)
385	root	1.34
386	root	1.35	Players tries to build using C<builder> at (map+x+y). Is invoked after the
387			usual sanity checks, so the coordinates are valid.
388	root	1.34
389	pippijn	1.1
390			=head2 MAP EVENTS
391
392			These events are generally dependent on a map and thus all have a map
393			as first argument.
394
395			=head3 instantiate (map)
396
397			Original B<map> has been loaded (e.g. on first use, or after a map
398			reset).
399
400			=head3 swapin (map)
401
402			Invoked when a previously swapped-out temporary B<map> has been loaded again.
403
404			=head3 swapout (map)
405
406			Invoked after a B<map> has been swapped out to disk.
407
408			=head3 reset (map)
409
410			Invoked when a B<map> gets reset.
411
412			=head3 clean (map)
413
414			Invoked when a temporary B<map> gets deleted on-disk.
415
416	root	1.4	=head3 enter (map player x y -- )
417	pippijn	1.1
418	root	1.4	Invoked whenever a player tries to enter the B<map>, while he/she is still
419	root	1.5	on the old map. Overriding means the player won't be able to enter, and,
420			if newmap/x/y are given, will be redirected to that map instead.
421	pippijn	1.1
422	root	1.4	=head3 leave (map player -- )
423	pippijn	1.1
424	root	1.4	Invoked whenever a player tries to leave the B<map>. Overriding means the
425			player won't be able to leave.
426	pippijn	1.1
427	root	1.31	=head3 trigger (map connection state what? who? -- )
428	pippijn	1.1
429			Invoked whenever something activates a B<connection> on the B<map>. If B<state>
430			is true the connection was 'state' and if false it is 'released'.
431	root	1.5
432	root	1.8
433			=head2 CLIENT EVENTS
434
435			These events are very similar to player events, but they are might be
436			handled asynchronously as soon as the command reaches the server, even when
437			the player hasn't logged in yet (meaning there is no player yet).
438
439	root	1.9	=head3 connect (client -- )
440
441			Called as soon as a new connection to the server is established. Should
442			not be overriden.
443
444	root	1.17	=head3 setup (client string -- )
445
446			Client sent the setup command to negotiate parameters. Handling is
447			mandatory and done by F<login.ext>.
448
449	root	1.9	=head3 addme (client -- )
450
451	root	1.17	The client sent an addme, thus ending the initial handshaking. Handling is mandatory
452			and done by F<login.ext>.
453	root	1.9
454	root	1.10	=head3 reply (client replystring -- )
455
456			Called when the client submits a reply in the ST_CUSTOM state. Usually
457			handled internally by language plugins.
458
459	root	1.9	=head3 exticmd (client string -- )
460	root	1.8
461			Like C<extcmd>, but can be called before a player has logged in.
462
463			Programmable plug-ins usually handle this event internally.
464