--- deliantra/server/pod/events.pod	2006/12/25 11:25:49	1.12
+++ deliantra/server/pod/events.pod	2007/11/10 22:41:59	1.23
@@ -1,4 +1,4 @@
-=head1 CROSSFIRE+ PLUG-IN EVENTS
+=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
@@ -52,7 +52,7 @@
 
 =head3 destroy (object -- )
 
-Invoked when the crossfire object gets destroyed, and only when the 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.
@@ -64,7 +64,7 @@
 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)
+=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
@@ -145,11 +145,11 @@
 (if it is a player) an indication of whats wrong. Must return true if the
 object was freed.
 
-=head3 use_skill (skill who part direction strignarg -- )
+=head3 use_skill (skill who part direction stringarg -- )
 
 Invoked whenever a skill is used by somebody or something.
 
-=head3 cast_spell (spell casting_object owner direction stringarg -- )
+=head3 cast_spell (spell owner casting_object direction stringarg -- )
 
 Invoked whenever a given spell is cast by B<casting_object> (used by
 B<owner>).
@@ -205,9 +205,17 @@
 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 (this event is not yet reliable!).
+Invoked whenever a container gets closed. When overriden, the container
+will not get closed, but you must tell op about the reason. This event
+is not crash-safe, i.e. containers might be closed due to a server crash
+without this event being invoked.
 
 
 =head2 GLOBAL EVENTS
@@ -237,22 +245,35 @@
 
 =head3 kick (player params -- )
 
-Invoked when the given plaer is being kicked, before the kick is executed.
+Invoked when the given player is being kicked, before the kick is
+executed.
 
-=head3 load (player)
+=head3 load (player -- )
 
 Invoked whenever a player has been loaded from disk, but before
 actual login.
 
-=head3 save (player)
+=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.
 
-Invoked just before a player gets saved.
+=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)
+=head3 logout (player cleanly -- )
 
 Invoked whenever a player logs out, gets disconnected etc.
 
@@ -264,6 +285,10 @@
 
 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
@@ -276,6 +301,12 @@
 
 =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>.
@@ -285,6 +316,11 @@
 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 --)
@@ -349,10 +385,15 @@
 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. If overriden, the server
-will not send any response.
+The client sent an addme, thus ending the initial handshaking. Handling is mandatory
+and done by F<login.ext>.
 
 =head3 reply (client replystring -- )