--- deliantra/server/pod/events.pod	2006/09/08 02:45:16	1.1
+++ deliantra/server/pod/events.pod	2006/12/22 06:02:29	1.11
@@ -1,4 +1,4 @@
-=head1 CROSSFIRE PLUG-IN EVENTS
+=head1 CROSSFIRE+ 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
@@ -50,6 +50,20 @@
 between instances). If this is not the behaviour you need, you have to
 adjust the B<destination> object as you see fit.
 
+=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 destroy (object)
 
 Invoked when the crossfire object gets destroyed, and only when the object
@@ -185,10 +199,15 @@
 
 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.
 
+
 =head2 PLAYER EVENTS
 
 Player events always have a player object as first argument.
@@ -232,14 +251,19 @@
 
 Invoked whenever a player dies, before the death actually gets processed.
 
-=head3 map_change (player oldmap newmap)
+=head3 map_change (player newmap x y -- )
+
+Invoked before a player moves from one map to another, can override the movement.
 
-Invoked whenever a player moves from one map to another.
+=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. It's
-argument is passed without any changes.
+Invoked whenever a client issues the C<extcmd> protocol command.
+Programmable plug-ins usually handle this event internally.
 
 =head3 move (player direction -- )
 
@@ -301,19 +325,57 @@
 
 Invoked when a temporary B<map> gets deleted on-disk.
 
-=head3 enter (map player)
-
-Invoked whenever a player enters the B<map>. This event is likely unreliable.
+=head3 enter (map player x y -- )
 
-=head3 leave (map player)
+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.
 
-Invoked whenever a player leaves the B<map>. This event is likely unreliable.
+=head3 leave (map player -- )
 
-=head3 upgrade (map)
+Invoked whenever a player tries to leave the B<map>. Overriding means the
+player won't be able to leave.
 
-(TEMPORARY EVENT) gets invoked whenever a old-style map has been upgraded.
-
-=head3 trigger (map connection state)
+=head3 trigger (map connection state -- )
 
 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 addme (client -- )
+
+The client sent an addme, thus ending the initial handshaking. If overriden, the server
+will not send any response.
+
+=head3 reattach	(client -- )
+
+Invoked whenever attachments/plug-ins need to get reattached to the
+object. This usually happens when server was reloaded. This event will
+only be generated if the object has attachments.
+
+=head3 destroy (client -- )
+
+Called when the runtime wants to destroy the client structure.
+
+=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.
+