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


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