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 infect (victim disease_type disease -- )

Invoked whenever an object is diseased. The disease object is already
inserted in object (the template disease object is C<disease_type>),
but no messages have been generated. If overriden, no messages will be
generated.

=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 after a player has been loaded from disk, but before
actual activation/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 sent by the client - this is invoked for I<all>
command,s so should not normally be hooked.

=head3 unknown_command (player command args -- time)

Execute a user command sent by the client that isn't known to the
server. 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 checkok --)

Players tries to build using C<builder> at (map+x+y). Is invoked after
the usual map sanity checks, so the coordinates are valid. The boolean
C<checkok> is true only if the build code thinks it is "ok" to build at
that space, and normally you should only build when it is true.


=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 and the
socket has been configured.

=head3 version (client string -- )

Called as soon as the version command from the client is received
(normally the very first command sent).

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

=head3 client_destroy (client -- )

Invoked when the client gets destroyed.


Revision:	1.41
Committed:	Mon Oct 1 01:43:39 2012 UTC (11 years, 7 months ago) by root
Branch:	MAIN
CVS Tags:	rel-3_1, HEAD
Changes since 1.40:	+7 -0 lines
Log Message:	nekosan 4ever
#	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	root	1.41	=head3 infect (victim disease_type disease -- )
232
233			Invoked whenever an object is diseased. The disease object is already
234			inserted in object (the template disease object is C<disease_type>),
235			but no messages have been generated. If overriden, no messages will be
236			generated.
237
238	pippijn	1.1	=head3 trigger (object who -- )
239
240			Invoked whenever a lever-like B<object> has been activated/triggered in some
241			(manual) way.
242
243			=head3 move_trigger (object victim originator -- )
244
245			Invoked whenever a trap-like B<object> has been activated, usually by
246			moving onto it. This includes not just traps, but also buttons, holes,
247			signs and similar stuff.
248
249	root	1.15	=head3 open (container who -- )
250
251			Invoked whenever a container gets opened. When overriden, the container will not
252			get opened, but you must tell op about the reason.
253
254	pippijn	1.1	=head3 close (container who -- )
255
256	root	1.15	Invoked whenever a container gets closed. When overriden, the container
257			will not get closed, but you must tell op about the reason. This event
258			is not crash-safe, i.e. containers might be closed due to a server crash
259			without this event being invoked.
260	pippijn	1.1
261	root	1.32	=head3 blocked_move (self who -- do_blocked)
262
263			Invoked when an C<who> tries to move to the same space as C<self>,
264			C<self>'s C<move_block> causes blocked movement for C<who> and nothing
265			else explicitly allows movement to this space.
266
267			Should return true when C<who> is blocked, i.e., should not be allowed to
268			move onto C<self>.
269
270			When not overriding, normal blocked_move (blocked_link) processing will
271			happen.
272
273	pippijn	1.1
274			=head2 GLOBAL EVENTS
275
276			Global events have no relation to specific objects.
277
278	root	1.3	=head3 cleanup ()
279
280			Called when the server is cleaning up, just before it calls exit.
281
282	root	1.24	=head3 clock ()
283	pippijn	1.1
284			Is invoked on every server tick, usually every 0.12 seconds.
285
286	root	1.24	=head3 resource_update ()
287
288			Is invoked after each time the server reloads its resources, which is
289			usually one of the earliest things it does when starting up.
290
291	root	1.3
292	pippijn	1.1	=head2 PLAYER EVENTS
293
294			Player events always have a player object as first argument.
295
296			=head3 birth (player)
297
298			Invoked as very first thing after creating a player.
299
300			=head3 quit (player)
301
302			Invoked wheneever a player quits, before actually removing him/her.
303
304			=head3 kick (player params -- )
305
306	root	1.14	Invoked when the given player is being kicked, before the kick is
307			executed.
308	pippijn	1.1
309	root	1.14	=head3 load (player -- )
310	pippijn	1.1
311	root	1.37	Invoked whenever after a player has been loaded from disk, but before
312			actual activation/login.
313	pippijn	1.1
314	root	1.14	=head3 save (player -- )
315	pippijn	1.1
316	root	1.14	Invoked just before a player gets serialised.
317	pippijn	1.1
318	root	1.14	=head3 save_done (player -- )
319	root	1.13
320	root	1.14	Invoked just after a player was serialised.
321	root	1.13
322			=head3 connect (player -- )
323
324			Invoked just after the player object was connected to a client.
325
326			=head3 disconnect (player -- )
327
328			Invoked just before the player gets disconnected from the client.
329
330	pippijn	1.1	=head3 login (player)
331
332			Invoked whenever a player logs in.
333
334	root	1.21	=head3 logout (player cleanly -- )
335	pippijn	1.1
336			Invoked whenever a player logs out, gets disconnected etc.
337
338			=head3 death (player)
339
340			Invoked whenever a player dies, before the death actually gets processed.
341
342	root	1.4	=head3 map_change (player newmap x y -- )
343	pippijn	1.1
344	root	1.4	Invoked before a player moves from one map to another, can override the movement.
345	pippijn	1.1
346	root	1.22	=head3 region_change (player newregion oldregion -- )
347
348			Invoked when a player entered a new region. Cannot be overriden.
349
350	root	1.7	=head3 command (player command args -- time)
351
352	root	1.36	Execute a user command sent by the client - this is invoked for I<all>
353			command,s so should not normally be hooked.
354
355			=head3 unknown_command (player command args -- time)
356
357			Execute a user command sent by the client that isn't known to the
358			server. Programmable plug-ins usually handle this event internally.
359	root	1.7
360	pippijn	1.1	=head3 extcmd (player string)
361
362	root	1.7	Invoked whenever a client issues the C<extcmd> protocol command.
363			Programmable plug-ins usually handle this event internally.
364	pippijn	1.1
365			=head3 move (player direction -- )
366
367	root	1.18	Called whenever the player is supposed to move or attack. The handler
368			must handle the cases of speed_left or weapon_sp_left being negative,
369			fire being on, is responsible for decreaseing the speed_left value
370			on successful moves etc. etc.. When overriden, must return a boolean
371			indicating wether a move could be effected.
372
373	pippijn	1.1	=head3 pray_altar (player altar skill -- )
374
375			Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
376
377			=head3 tell (player name message -- )
378
379			Invoked whenever the player uses the B<tell> or B<reply> command, before
380			it gets processed.
381
382	pippijn	1.16	=head3 told (player player message -- )
383
384			Invoked right before a message is being told to a player using B<tell> or
385			B<reply>.
386
387	pippijn	1.1	=head3 say (player message --)
388
389			=head3 chat (player message --)
390
391			=head3 shout (player message --)
392
393			Invoked whenever the player uses the B<say>, B<chat> or B<shout> command,
394			before it gets processed.
395
396	root	1.40	=head3 build (player builder map x y checkok --)
397	root	1.34
398	root	1.40	Players tries to build using C<builder> at (map+x+y). Is invoked after
399			the usual map sanity checks, so the coordinates are valid. The boolean
400			C<checkok> is true only if the build code thinks it is "ok" to build at
401			that space, and normally you should only build when it is true.
402	root	1.34
403	pippijn	1.1
404			=head2 MAP EVENTS
405
406			These events are generally dependent on a map and thus all have a map
407			as first argument.
408
409			=head3 instantiate (map)
410
411			Original B<map> has been loaded (e.g. on first use, or after a map
412			reset).
413
414			=head3 swapin (map)
415
416			Invoked when a previously swapped-out temporary B<map> has been loaded again.
417
418			=head3 swapout (map)
419
420			Invoked after a B<map> has been swapped out to disk.
421
422			=head3 reset (map)
423
424			Invoked when a B<map> gets reset.
425
426			=head3 clean (map)
427
428			Invoked when a temporary B<map> gets deleted on-disk.
429
430	root	1.4	=head3 enter (map player x y -- )
431	pippijn	1.1
432	root	1.4	Invoked whenever a player tries to enter the B<map>, while he/she is still
433	root	1.5	on the old map. Overriding means the player won't be able to enter, and,
434			if newmap/x/y are given, will be redirected to that map instead.
435	pippijn	1.1
436	root	1.4	=head3 leave (map player -- )
437	pippijn	1.1
438	root	1.4	Invoked whenever a player tries to leave the B<map>. Overriding means the
439			player won't be able to leave.
440	pippijn	1.1
441	root	1.31	=head3 trigger (map connection state what? who? -- )
442	pippijn	1.1
443			Invoked whenever something activates a B<connection> on the B<map>. If B<state>
444			is true the connection was 'state' and if false it is 'released'.
445	root	1.5
446	root	1.8
447			=head2 CLIENT EVENTS
448
449			These events are very similar to player events, but they are might be
450			handled asynchronously as soon as the command reaches the server, even when
451			the player hasn't logged in yet (meaning there is no player yet).
452
453	root	1.9	=head3 connect (client -- )
454
455	root	1.39	Called as soon as a new connection to the server is established and the
456			socket has been configured.
457	root	1.9
458	root	1.38	=head3 version (client string -- )
459
460			Called as soon as the version command from the client is received
461			(normally the very first command sent).
462
463	root	1.17	=head3 setup (client string -- )
464
465			Client sent the setup command to negotiate parameters. Handling is
466			mandatory and done by F<login.ext>.
467
468	root	1.9	=head3 addme (client -- )
469
470	root	1.17	The client sent an addme, thus ending the initial handshaking. Handling is mandatory
471			and done by F<login.ext>.
472	root	1.9
473	root	1.10	=head3 reply (client replystring -- )
474
475			Called when the client submits a reply in the ST_CUSTOM state. Usually
476			handled internally by language plugins.
477
478	root	1.9	=head3 exticmd (client string -- )
479	root	1.8
480			Like C<extcmd>, but can be called before a player has logged in.
481
482			Programmable plug-ins usually handle this event internally.
483
484	root	1.36	=head3 client_destroy (client -- )
485
486			Invoked when the client gets destroyed.
487
488