--- deliantra/server/doc/events.pod 2006/08/28 08:34:28 1.1 +++ deliantra/server/doc/events.pod 2006/08/29 07:54:36 1.8 @@ -9,7 +9,7 @@ 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 called but cannot change wether the event gets +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 @@ -20,192 +20,240 @@ will be ignored (presumably your plug-in took care of it). -=head2 GLOBAL EVENTS +=head2 OBJECT EVENTS -Global events have no relation to specific objects. +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 CLOCK ( ) +=head3 instantiate (object init-args...) -Is invoked on every server tick, usually every 0.12 seconds. +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 +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. -=head2 PLAYER EVENTS +=head3 reattach (object) -Player events always have a player object as first argument. +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 REATTACH (player) +=head3 clone (object destination) -Called 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. +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. -=head3 BIRTH (player) +=head3 destroy (object) -Called as very first thing after creating a player. +Invoked when the crossfire 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 QUIT (player) +=head3 tick (object) -Called wheneever a player quits, before actually removing him/her. +Invoked whenever the object "ticks", i.e. has positive B. Only +during ticks should an objetc process any movement or other events. -=head3 LOAD (player) +=head3 kill (object hitter -- ) -Called whenever a player has been loaded from disk, but before -actual login. +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. -=head3 SAVE (player) +=head3 apply (object who -- applytype) -Called just before a player gets saved. +Invoked whenever the object is being applied in some way. The applytype is one of: -=head3 LOGIN (player) +=over 4 -Called whenever a player logs in. +=item B<0> player or monster can't apply objects of that type -=head3 LOGOUT (player) +=item B<1> has been applied, or there was an error applying the object -Called whenever a player logs out, gets disconnected etc. +=item B<2> objects of that type can't be applied if not in inventory -=head3 DEATH (player) +=back -Called whenever a player dies, before the death actually gets processed. +=head3 throw (object thrower) -=head3 MAP_CHANGE (player oldmap newmap) +Invoked when an B is thrown by B. -Called whenever a player moves from one map to another. +=head3 stop (object -- ) -=head3 EXTCMD (player string) +Invoked when a thrown B (arrow, other stuff) hits something and is +thus being "stopped". -Called whenever a client issues the C protocol command. It's -argument is passed without any changes. +=head3 can_apply (who object -- reason) -=head3 PRAY_ALTAR (player altar skill -- ) +=head3 can_be_applied (object who -- reason) -Called whenever the B prays over an B, using the given B. +Check wether the B can be applied/readied/etc. by the +object B and return reason otherwise. Reason is a bitset composed of +C-flags. -=head3 TELL (player -- ) +=head3 be_ready (object who -- success) -Called whenever the player uses the B command, before it gets processed. +=head3 ready (who object -- success) -=head3 SAY (player --) +Invoked whenever an B is being applied by object B. See +I for an alternative if you just want to check wether something +can apply an object. -Called whenever the player uses the B command, before it gets processed. +=head3 be_unready (object who -- deleted) -=head3 SHOUT (player --) +=head3 unready (who object -- deleted) -Called whenever the player uses the B command, before it gets processed. +Unwield/unapply/unready the given spell/weapon/skill/etc. B, +currently applied by B. 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. +=head3 use_skill (skill who part direction strignarg -- ) -=head2 OBJECT EVENTS +Invoked whenever a skill is used by somebody or something. -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 cast_spell (spell casting_object owner direction stringarg -- ) -=head3 INSTANTIATE (object init-args...) +Invoked whenever a given spell is cast by B (used by +B). -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 -dynamically. The arguments are as specified in the C attribute of -the object or archetype. +=head3 drop (object who -- ) -This is useful to initialise any per-object state you might need. +Invoked whenever an item gets dropped by somebody, e.g. as a result of a +drop command. -=head3 REATTACH (object) +=head3 drop_on (floor object who -- ) -Called 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. +Invoked whenever some B is being dropped on the B object. -=head3 CLONE (object destination) +=head3 say (object player message) -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. +Invoked whenever the I can hear a B being said by +B in its vicinity. -=head3 TICK (object) +=head3 move (monster enemy -- ) -Called whenever the object "ticks", i.e. has positive B. Only -during ticks should an objetc process any movement or other events. +Invoked whenever the B tries to move, just after B and +other parameters have been determined, but before movement is actually +executed. -=head3 KILL (object hitter -- ) +=head3 attack (object hitter -- damage) -Called 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. +Object gets attacked by somebody - when overriden, should return the +damage that has been dealt. -=head3 APPLY (object who -- applytype) +=head3 attacks (weapon hitter victim) -Called whenever the object is being applied in some way. The applytype is one of: +Invoked whenever an object is used as a B by B to attack +B. -=over 4 +=head3 inscribe_note (book pl message skill -- ) -=item B<0> player or monster can't apply objects of that type +Used whenever a book gets inscribed with a message. -=item B<1> has been applied, or there was an error applying the object +=head3 trigger (object who -- ) -=item B<2> objects of that type can't be applied if not in inventory +Invoked whenever a lever-like B has been activated/triggered in some +(manual) way. -=cut +=head3 move_trigger (object victim originator -- ) -=head3 USE_SKILL (skill who part direction strignarg -- ) +Invoked whenever a trap-like B has been activated, usually by +moving onto it. This includes not just traps, but also buttons, holes, +signs and similar stuff. -Called whenever a skill is used by somebody or something. +=head3 close (container -- ) -=head3 CAST_SPELL (spell casting_object owner direction stringarg -- ) +Invoked whenever a container gets closed (this event is not yet reliable!). -Called whenever a given spell is cast by B (used by -B). -=head3 DROP (object who -- ) +=head2 GLOBAL EVENTS -Called whenever an item gets dropped by somebody, e.g. as a result of a -drop command. +Global events have no relation to specific objects. -=head3 DROP_ON (floor object who -- ) +=head3 clock ( ) -Called whenever some B is being dropped on the B object. +Is invoked on every server tick, usually every 0.12 seconds. -=head3 LISTEN +=head2 PLAYER EVENTS -Called whenever the object can hear something beign said in its -vicinity. Not yet implemented. +Player events always have a player object as first argument. -=head3 MOVE (monster enemy -- ) +=head3 reattach (player) -Called whenever the B tries to move, just after B and -other parameters have been determined, but before movement is actually -executed. +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. -=head3 ATTACK (object hitter -- damage) +=head3 birth (player) -Object gets attacked by somebody - when overriden, should return the -damage that has been dealt. +Invoked as very first thing after creating a player. -=head3 ATTACKS (weapon hitter victim) +=head3 quit (player) -Called whenever an object is used as a B by B to attack -B. +Invoked wheneever a player quits, before actually removing him/her. -=head3 INSCRIBE_NOTE (book pl message skill -- ) +=head3 kick (player params -- ) -Used whenever a book gets inscribed with a message. +Invoked when the given plaer is being kicked, before the kick is executed. -=head3 TRIGGER (object who -- ) +=head3 load (player) -Called whenever a lever-like B has been activated/triggered in some -(manual) way. +Invoked whenever a player has been loaded from disk, but before +actual login. -=head3 MOVE_TRIGGER (object victim originator -- ) +=head3 save (player) -Called whenever a trap-like B has been activated, usually by -moving onto it. This includes not just traps, but also buttons, holes, -signs and similar stuff. +Invoked just before a player gets saved. + +=head3 login (player) + +Invoked whenever a player logs in. -=head3 CLOSE (container -- ) +=head3 logout (player) -Called whenever a container gets closed (this event is not yet reliable!). +Invoked whenever a player logs out, gets disconnected etc. + +=head3 death (player) + +Invoked whenever a player dies, before the death actually gets processed. + +=head3 map_change (player oldmap newmap) + +Invoked whenever a player moves from one map to another. + +=head3 extcmd (player string) + +Invoked whenever a client issues the C protocol command. It's +argument is passed without any changes. + +=head3 move (player direction -- ) + +=head3 pray_altar (player altar skill -- ) + +Invoked whenever the B prays over an B, using the given B. + +=head3 tell (player name message -- ) + +Invoked whenever the player uses the B or B command, before +it gets processed. + +=head3 say (player message --) + +=head3 chat (player message --) + +=head3 shout (player message --) + +Invoked whenever the player uses the B, B or B command, +before it gets processed. =head2 MAP EVENTS @@ -213,42 +261,49 @@ These events are generally dependent on a map and thus all have a map as first argument. -=head3 REATTACH (map) +=head3 instantiate (map) + +Original B has been loaded (e.g. on first use, or after a map +reset). + +=head3 reattach (map) -Called whenever attachments/plug-ins need to get reattached to the +Invoked whenever attachments/plug-ins need to get reattached to the B. This usually happens when the map was loaded from disk, or when the server was reloaded. -=head3 LOAD (map) +=head3 destroy (map) -Original B has been loaded (e.g. on first use, or after a map -reset). This event might get renamed to instantiate in the future. +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) +=head3 swapin (map) -Called when a previously swapped-out temporary B has been loaded again. +Invoked when a previously swapped-out temporary B has been loaded again. -=head3 SWAPOUT (map) +=head3 swapout (map) -Called after a B has been swapped out to disk. +Invoked after a B has been swapped out to disk. -=head3 RESET (map) +=head3 reset (map) -Called when a B gets reset. +Invoked when a B gets reset. -=head3 CLEAN (map) +=head3 clean (map) -Called when a temporary B gets deleted on-disk. +Invoked when a temporary B gets deleted on-disk. -=head3 ENTER (map player) +=head3 enter (map player) -Called whenever a player enters the B. This event is likely unreliable. +Invoked whenever a player enters the B. This event is likely unreliable. -=head3 LEAVE (map player) +=head3 leave (map player) -Called whenever a player leaves the B. This event is likely unreliable. +Invoked whenever a player leaves the B. This event is likely unreliable. -=head3 UPGRADE (map) +=head3 upgrade (map) -(TEMPORARY EVENT) gets called whenever a old-style map has been upgraded. +(TEMPORARY EVENT) gets invoked whenever a old-style map has been upgraded.