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.
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 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 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).
No time to document this, screw me.
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 attach attribute of
the object or archetype.
This is useful to initialise any per-object state you might need.
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.
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 destination object as you see fit.
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.
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.
A basic item has been created (e.g. for shops, monsters drops etc.) that needs bonus values applied. The 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.
Invoked before the object is removed from its environment.
Called after the object was inserted into a container or map.
Invoked whenever the object "ticks", i.e. has positive speed_left. Only during ticks should an objetc process any movement or other events.
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 the object is being applied in some way. The applytype is one of:
Invoked when an object is thrown by thrower.
Invoked when a thrown object (arrow, other stuff) hits something and is thus being "stopped".
Check wether the object can be applied/readied/etc. by the
object who and return reason otherwise. Reason is a bitset composed of
CAN_APPLY_*-flags.
Invoked whenever an object is being applied by object who. See can_apply for an alternative if you just want to check wether something can apply an object.
Unwield/unapply/unready the given spell/weapon/skill/etc. object, currently applied by who. If your override, make sure you give 'who' (if it is a player) an indication of whats wrong. Must return true if the object was freed.
Invoked whenever a skill is used by somebody or something.
Invoked whenever a given spell is cast by casting_object (used by owner).
Invoked whenever an item gets dropped by somebody, e.g. as a result of a drop command.
Invoked whenever some object is being dropped on the floor object.
Invoked whenever the object can hear a message being said by player in its vicinity.
Invoked whenever the monster tries to move, just after enemy and other parameters have been determined, but before movement is actually executed.
Object gets attacked by somebody - when overriden, should return the damage that has been dealt.
Invoked whenever an attacker attacks victim using a skill (skill
cna be undef). message is the message that describes the attack when
damage is done.
Invoked whenever an object is used as a weapon by hitter to attack victim.
Used whenever a book gets inscribed with a message.
Invoked whenever a lever-like object has been activated/triggered in some (manual) way.
Invoked whenever a trap-like object has been activated, usually by moving onto it. This includes not just traps, but also buttons, holes, signs and similar stuff.
Invoked whenever a container gets opened. When overriden, the container will not get opened, but you must tell op about the reason.
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.
Global events have no relation to specific objects.
Called when the server is cleaning up, just before it calls exit.
Is invoked on every server tick, usually every 0.12 seconds.
Player events always have a player object as first argument.
Invoked as very first thing after creating a player.
Invoked wheneever a player quits, before actually removing him/her.
Invoked when the given player is being kicked, before the kick is executed.
Invoked whenever a player has been loaded from disk, but before actual login.
Invoked just before a player gets serialised.
Invoked just after a player was serialised.
Invoked just after the player object was connected to a client.
Invoked just before the player gets disconnected from the client.
Invoked whenever a player logs in.
Invoked whenever a player logs out, gets disconnected etc.
Invoked whenever a player dies, before the death actually gets processed.
Invoked before a player moves from one map to another, can override the movement.
Invoked when a player entered a new region. Cannot be overriden.
Execute a user command send by the client. Programmable plug-ins usually handle this event internally.
Invoked whenever a client issues the extcmd protocol command.
Programmable plug-ins usually handle this event internally.
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.
Invoked whenever the player prays over an altar, using the given skill.
Invoked whenever the player uses the tell or reply command, before it gets processed.
Invoked right before a message is being told to a player using tell or reply.
Invoked whenever the player uses the say, chat or shout command, before it gets processed.
These events are generally dependent on a map and thus all have a map as first argument.
Original map has been loaded (e.g. on first use, or after a map reset).
Invoked when a previously swapped-out temporary map has been loaded again.
Invoked after a map has been swapped out to disk.
Invoked when a map gets reset.
Invoked when a temporary map gets deleted on-disk.
Invoked whenever a player tries to enter the 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 tries to leave the map. Overriding means the player won't be able to leave.
Invoked whenever something activates a connection on the map. If state is true the connection was 'state' and if false it is 'released'.
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).
Called as soon as a new connection to the server is established. Should not be overriden.
Client sent the setup command to negotiate parameters. Handling is mandatory and done by login.ext.
The client sent an addme, thus ending the initial handshaking. Handling is mandatory and done by login.ext.
Called when the client submits a reply in the ST_CUSTOM state. Usually handled internally by language plugins.
Like extcmd, but can be called before a player has logged in.
Programmable plug-ins usually handle this event internally.