--- deliantra/server/pod/events.pod 2007/01/02 11:08:36 1.13 +++ deliantra/server/pod/events.pod 2008/10/06 18:26:35 1.28 @@ -1,4 +1,4 @@ -=head1 CROSSFIRE+ PLUG-IN EVENTS +=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 @@ -52,7 +52,7 @@ =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. @@ -64,7 +64,7 @@ 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) +=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 @@ -93,9 +93,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 +112,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 is thrown by B. @@ -145,11 +151,11 @@ (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 -- ) +=head3 use_skill (skill who part direction stringarg -- ) Invoked whenever a skill is used by somebody or something. -=head3 cast_spell (spell casting_object owner direction stringarg -- ) +=head3 cast_spell (spell owner casting_object direction stringarg -- ) Invoked whenever a given spell is cast by B (used by B). @@ -158,10 +164,16 @@ Invoked whenever an item gets dropped by somebody, e.g. as a result of a drop command. +B If you put the object somewhere else or destroyed the object +you have to override! If you do nothing with the object and override it is +given back to the dropper. =head3 drop_on (floor object who -- ) Invoked whenever some B is being dropped on the B object. +B If you put the object somewhere else or destroyed the object +you have to override! If you do nothing with the object and override it is +given back to the dropper. =head3 say (object player message) @@ -205,9 +217,17 @@ moving onto it. This includes not just traps, but also buttons, holes, signs and similar stuff. +=head3 open (container who -- ) + +Invoked whenever a container gets opened. When overriden, the container will not +get opened, but you must tell op about the reason. + =head3 close (container who -- ) -Invoked whenever a container gets closed (this event is not yet reliable!). +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. =head2 GLOBAL EVENTS @@ -218,10 +238,15 @@ Called when the server is cleaning up, just before it calls exit. -=head3 clock ( ) +=head3 clock () Is invoked on every server tick, usually every 0.12 seconds. +=head3 resource_update () + +Is invoked after each time the server reloads its resources, which is +usually one of the earliest things it does when starting up. + =head2 PLAYER EVENTS @@ -237,20 +262,21 @@ =head3 kick (player params -- ) -Invoked when the given plaer is being kicked, before the kick is executed. +Invoked when the given player is being kicked, before the kick is +executed. -=head3 load (player) +=head3 load (player -- ) Invoked whenever a player has been loaded from disk, but before actual login. -=head3 save (player path -- ) +=head3 save (player -- ) -Invoked just before a player gets saved. +Invoked just before a player gets serialised. -=head3 save_done (player path -- ) +=head3 save_done (player -- ) -Invoked just after a player was saved. +Invoked just after a player was serialised. =head3 connect (player -- ) @@ -264,7 +290,7 @@ Invoked whenever a player logs in. -=head3 logout (player) +=head3 logout (player cleanly -- ) Invoked whenever a player logs out, gets disconnected etc. @@ -276,6 +302,10 @@ Invoked before a player moves from one map to another, can override the movement. +=head3 region_change (player newregion oldregion -- ) + +Invoked when a player entered a new region. Cannot be overriden. + =head3 command (player command args -- time) Execute a user command send by the client. Programmable plug-ins usually @@ -288,6 +318,12 @@ =head3 move (player direction -- ) +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. + =head3 pray_altar (player altar skill -- ) Invoked whenever the B prays over an B, using the given B. @@ -297,6 +333,11 @@ Invoked whenever the player uses the B or B command, before it gets processed. +=head3 told (player player message -- ) + +Invoked right before a message is being told to a player using B or +B. + =head3 say (player message --) =head3 chat (player message --) @@ -361,10 +402,15 @@ Called as soon as a new connection to the server is established. Should not be overriden. +=head3 setup (client string -- ) + +Client sent the setup command to negotiate parameters. Handling is +mandatory and done by F. + =head3 addme (client -- ) -The client sent an addme, thus ending the initial handshaking. If overriden, the server -will not send any response. +The client sent an addme, thus ending the initial handshaking. Handling is mandatory +and done by F. =head3 reply (client replystring -- )