--- deliantra/server/pod/events.pod 2006/09/17 14:22:28 1.4
+++ deliantra/server/pod/events.pod 2010/04/06 23:34:57 1.37
@@ -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
+ .
+
+ The authors can be reached via e-mail to
+
+=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 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)
+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 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 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 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 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 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. 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