--- deliantra/server/pod/events.pod	2007/12/17 08:27:44	1.24
+++ deliantra/server/pod/events.pod	2010/04/06 23:34:57	1.37
@@ -1,3 +1,27 @@
+=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
@@ -6,18 +30,22 @@
 
 =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 ATTACHABLE EVENTS
@@ -93,9 +121,10 @@
 
 =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)
 
@@ -111,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>.
@@ -182,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)
@@ -217,6 +251,18 @@
 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
 
@@ -255,8 +301,8 @@
 
 =head3 load (player -- )
 
-Invoked whenever a player has been loaded from disk, but before
-actual login.
+Invoked whenever after a player has been loaded from disk, but before
+actual activation/login.
 
 =head3 save (player -- )
 
@@ -296,8 +342,13 @@
 
 =head3 command (player command args -- time)
 
-Execute a user command send by the client. Programmable plug-ins usually
-handle this event internally.
+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)
 
@@ -335,6 +386,11 @@
 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 --)
+
+Players tries to build using C<builder> at (map+x+y). Is invoked after the
+usual sanity checks, so the coordinates are valid.
+
 
 =head2 MAP EVENTS
 
@@ -373,7 +429,7 @@
 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'.
@@ -411,3 +467,8 @@
 
 Programmable plug-ins usually handle this event internally.
 
+=head3 client_destroy (client -- )
+
+Invoked when the client gets destroyed.
+
+