=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
changing it, though.
=head2 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 part is
missing, the event will be invoked but cannot change wether the event gets
processed.
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 ATTACHABLE EVENTS
No time to document this, screw me.
=head3 instantiate (object init-args...)
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.
This is useful to initialise any per-object state you might need.
=head3 reattach (object)
Invoked whenever attachments/plug-ins need to get reattached to the
object. This usually happens when it was loaded from disk, or when the
server was reloaded. This event will only be generated if the object has
attachments.
=head3 clone (object destination)
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 -- )
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.
=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 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)
Invoked whenever the object is being applied in some way. The applytype is one of:
=over 4
=item B<0> player or monster can't apply objects of that type
=item B<1> has been applied, or there was an error applying the object
=item B<2> objects of that type can't be applied if not in inventory
=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