--- deliantra/server/pod/events.pod	2006/09/17 18:19:19	1.5
+++ deliantra/server/pod/events.pod	2009/11/03 23:44:21	1.33
@@ -1,4 +1,28 @@
-=head1 CROSSFIRE+ PLUG-IN EVENTS
+=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
@@ -6,30 +30,34 @@
 
 =head2 NOTATION
 
-the event description below uses a variant of the forth stack 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 is
+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.
 
-If it is specified (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).
+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 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.
+=head2 ATTACHABLE EVENTS
+
+No time to document this, screw me.
 
 =head3 instantiate (object init-args...)
 
-An archetype was instantiated into an object. This event occurs when
-a map is loaded for the first time, or when the object was created
+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.
 
@@ -44,29 +72,59 @@
 
 =head3 clone (object destination)
 
-An object with _attached extension_ 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.
+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)
+=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.
 
-=head3 tick (object)
+
+=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 is dead and about to get removed. Overriding
-processing will skip removal, but to do this successfully you have to
-objetc from dieing, otherwise the event gets invoked again and again.
+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)
 
@@ -82,6 +140,11 @@
 
 =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>.
@@ -116,11 +179,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>).
@@ -153,7 +216,7 @@
 =head3 skill_attack (attacker victim message skill -- success)
 
 Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill
-cna be C<undef>). B<message> is the message that describes the attack when
+can be C<undef>). B<message> is the message that describes the attack when
 damage is done.
 
 =head3 weapon_attack (weapon hitter victim)
@@ -176,9 +239,29 @@
 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.
+
+=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
@@ -189,20 +272,19 @@
 
 Called when the server is cleaning up, just before it calls exit.
 
-=head3 clock ( )
+=head3 clock ()
 
 Is invoked on every server tick, usually every 0.12 seconds.
 
+=head3 resource_update ()
 
-=head2 PLAYER EVENTS
+Is invoked after each time the server reloads its resources, which is
+usually one of the earliest things it does when starting up.
 
-Player events always have a player object as first argument.
 
-=head3 reattach (player)
+=head2 PLAYER EVENTS
 
-Invoked whenever attachments/plug-ins need to get reattached to the player
-object. This usually happens when the player gets loaded from disk, or
-when the server is reloaded.
+Player events always have a player object as first argument.
 
 =head3 birth (player)
 
@@ -214,22 +296,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 saved.
+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)
+=head3 logout (player cleanly -- )
 
 Invoked whenever a player logs out, gets disconnected etc.
 
@@ -241,13 +336,28 @@
 
 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. 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 -- )
 
+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>.
@@ -257,6 +367,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 --)
@@ -277,19 +392,6 @@
 Original B<map> has been loaded (e.g. on first use, or after a map
 reset).
 
-=head3 reattach (map)
-
-Invoked whenever attachments/plug-ins need to get reattached to the
-B<map>. This usually happens when the map was loaded from disk, or when the
-server was reloaded.
-
-=head3 destroy (map)
-
-Invoked when the map object gets destroyed, and only when the map 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.
-
 =head3 swapin (map)
 
 Invoked when a previously swapped-out temporary B<map> has been loaded again.
@@ -317,8 +419,41 @@
 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)
+=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.
+