ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/deliantra/server/pod/events.pod
(Generate patch)

Comparing deliantra/server/pod/events.pod (file contents):
Revision 1.15 by root, Sat Feb 10 01:52:28 2007 UTC vs.
Revision 1.32 by root, Wed Oct 21 00:44:39 2009 UTC

1=head1 CROSSFIRE+ PLUG-IN EVENTS 1=head1 DELIANTRA PLUG-IN EVENTS
2 2
3This document briefly describes each plug-in event. It is also used to 3This document briefly describes each plug-in event. It is also used to
4generate the event-list itself, so is always complete. Be careful wehn 4generate the event-list itself, so is always complete. Be careful wehn
5changing it, though. 5changing it, though.
6 6
7=head2 NOTATION 7=head2 NOTATION
8 8
9the event description below uses a variant of the forth stack notation - 9The event description below uses a variant of the forth stack notation -
10an opening parenthesis followed by the type of each parameter, optionally 10an opening parenthesis followed by the type of each parameter, optionally
11followed by two dashes and the returning parameters. If the latter is 11followed by two dashes and the returning parameters. If the latter part is
12missing, the event will be invoked but cannot change wether the event gets 12missing, the event will be invoked but cannot change wether the event gets
13processed. 13processed.
14 14
15If it is specified (even if no return values are supported), a plug-in 15Return values are given by overriding (in Perl by calling C<cf::override>)
16can override (e.g. using C<cf::override> in Perl) event processing, 16with the return values, which will both stop further event processing and
17basically short-circuiting it. For example, if you override from within a 17tell the caller that it wants to override normal processing.
18player BIRTH event, nothing much will happen with respect to the built-in 18
19Even if no return values are supported, a plug-in can override (e.g. using
20C<cf::override> in Perl) event processing, basically short-circuiting
21it. For example, if you override from within a player BIRTH event,
22nothing much will happen with respect to the built-in processing, but if
19processing, but if you override from within a player TELL event, the tell 23you override from within a player TELL event, the tell will be ignored
20will be ignored (presumably your plug-in took care of it). 24(presumably your plug-in took care of it).
21 25
22 26
23=head2 ATTACHABLE EVENTS 27=head2 ATTACHABLE EVENTS
24 28
25No time to document this, screw me. 29No time to document this, screw me.
… …
50instances). If this is not the behaviour you need, you have to adjust the 54instances). If this is not the behaviour you need, you have to adjust the
51B<destination> object as you see fit. 55B<destination> object as you see fit.
52 56
53=head3 destroy (object -- ) 57=head3 destroy (object -- )
54 58
55Invoked when the crossfire object gets destroyed, and only when the object 59Invoked when the deliantra object gets destroyed, and only when the object
56has a handler for this event. This event can occur many times, as its 60has a handler for this event. This event can occur many times, as its
57called when the in-memory object is destroyed, not when the object itself 61called when the in-memory object is destroyed, not when the object itself
58dies. 62dies.
59 63
60 64
… …
62 66
63Object events always relate to a specific object, which is always the 67Object events always relate to a specific object, which is always the
64first argument. Not all events get generated for every object, some are 68first argument. Not all events get generated for every object, some are
65specific to an object type. 69specific to an object type.
66 70
67=head3 add_bonus (item creator difficulty max_magic flags) 71=head3 add_bonus (item creator difficulty max_magic flags -- )
68 72
69A basic item has been created (e.g. for shops, monsters drops etc.) 73A basic item has been created (e.g. for shops, monsters drops etc.)
70that needs bonus values applied. The B<creator> object is a template 74that needs bonus values applied. The B<creator> object is a template
71object that can be used to inherit stuff (and can be NULL). Flags is a 75object that can be used to inherit stuff (and can be NULL). Flags is a
72combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP 76combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP
… …
91Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only 95Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
92during ticks should an objetc process any movement or other events. 96during ticks should an objetc process any movement or other events.
93 97
94=head3 kill (object hitter -- ) 98=head3 kill (object hitter -- )
95 99
96Invoked whenever an object is dead and about to get removed. Overriding 100Invoked whenever an object was killed (hp < 0 caused by an attack) and is
97processing will skip removal, but to do this successfully you have to 101about to get removed. Overriding processing will skip removal, but to do
98objetc from dieing, otherwise the event gets invoked again and again. 102this successfully you have to keep the object from dieing, otherwise the
103event gets invoked again and again.
99 104
100=head3 apply (object who -- applytype) 105=head3 apply (object who -- applytype)
101 106
102Invoked whenever the object is being applied in some way. The applytype is one of: 107Invoked whenever the object is being applied in some way. The applytype is one of:
103 108
… …
108=item B<1> has been applied, or there was an error applying the object 113=item B<1> has been applied, or there was an error applying the object
109 114
110=item B<2> objects of that type can't be applied if not in inventory 115=item B<2> objects of that type can't be applied if not in inventory
111 116
112=back 117=back
118
119=head3 reset (object)
120
121Invoked whenever the object is initialised on a map after it was
122loaded. This can be used to emulate shop-floor behaviour for example.
113 123
114=head3 throw (object thrower) 124=head3 throw (object thrower)
115 125
116Invoked when an B<object> is thrown by B<thrower>. 126Invoked when an B<object> is thrown by B<thrower>.
117 127
… …
143Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>, 153Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
144currently applied by B<who>. If your override, make sure you give 'who' 154currently applied by B<who>. If your override, make sure you give 'who'
145(if it is a player) an indication of whats wrong. Must return true if the 155(if it is a player) an indication of whats wrong. Must return true if the
146object was freed. 156object was freed.
147 157
148=head3 use_skill (skill who part direction strignarg -- ) 158=head3 use_skill (skill who part direction stringarg -- )
149 159
150Invoked whenever a skill is used by somebody or something. 160Invoked whenever a skill is used by somebody or something.
151 161
152=head3 cast_spell (spell casting_object owner direction stringarg -- ) 162=head3 cast_spell (spell owner casting_object direction stringarg -- )
153 163
154Invoked whenever a given spell is cast by B<casting_object> (used by 164Invoked whenever a given spell is cast by B<casting_object> (used by
155B<owner>). 165B<owner>).
156 166
157=head3 drop (object who -- ) 167=head3 drop (object who -- )
… …
180damage that has been dealt. 190damage that has been dealt.
181 191
182=head3 skill_attack (attacker victim message skill -- success) 192=head3 skill_attack (attacker victim message skill -- success)
183 193
184Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill 194Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill
185cna be C<undef>). B<message> is the message that describes the attack when 195can be C<undef>). B<message> is the message that describes the attack when
186damage is done. 196damage is done.
187 197
188=head3 weapon_attack (weapon hitter victim) 198=head3 weapon_attack (weapon hitter victim)
189 199
190Invoked whenever an object is used as a B<weapon> by B<hitter> to attack 200Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
… …
215Invoked whenever a container gets closed. When overriden, the container 225Invoked whenever a container gets closed. When overriden, the container
216will not get closed, but you must tell op about the reason. This event 226will not get closed, but you must tell op about the reason. This event
217is not crash-safe, i.e. containers might be closed due to a server crash 227is not crash-safe, i.e. containers might be closed due to a server crash
218without this event being invoked. 228without this event being invoked.
219 229
230=head3 blocked_move (self who -- do_blocked)
231
232Invoked when an C<who> tries to move to the same space as C<self>,
233C<self>'s C<move_block> causes blocked movement for C<who> and nothing
234else explicitly allows movement to this space.
235
236Should return true when C<who> is blocked, i.e., should not be allowed to
237move onto C<self>.
238
239When not overriding, normal blocked_move (blocked_link) processing will
240happen.
241
220 242
221=head2 GLOBAL EVENTS 243=head2 GLOBAL EVENTS
222 244
223Global events have no relation to specific objects. 245Global events have no relation to specific objects.
224 246
225=head3 cleanup () 247=head3 cleanup ()
226 248
227Called when the server is cleaning up, just before it calls exit. 249Called when the server is cleaning up, just before it calls exit.
228 250
229=head3 clock ( ) 251=head3 clock ()
230 252
231Is invoked on every server tick, usually every 0.12 seconds. 253Is invoked on every server tick, usually every 0.12 seconds.
254
255=head3 resource_update ()
256
257Is invoked after each time the server reloads its resources, which is
258usually one of the earliest things it does when starting up.
232 259
233 260
234=head2 PLAYER EVENTS 261=head2 PLAYER EVENTS
235 262
236Player events always have a player object as first argument. 263Player events always have a player object as first argument.
… …
271 298
272=head3 login (player) 299=head3 login (player)
273 300
274Invoked whenever a player logs in. 301Invoked whenever a player logs in.
275 302
276=head3 logout (player) 303=head3 logout (player cleanly -- )
277 304
278Invoked whenever a player logs out, gets disconnected etc. 305Invoked whenever a player logs out, gets disconnected etc.
279 306
280=head3 death (player) 307=head3 death (player)
281 308
282Invoked whenever a player dies, before the death actually gets processed. 309Invoked whenever a player dies, before the death actually gets processed.
283 310
284=head3 map_change (player newmap x y -- ) 311=head3 map_change (player newmap x y -- )
285 312
286Invoked before a player moves from one map to another, can override the movement. 313Invoked before a player moves from one map to another, can override the movement.
314
315=head3 region_change (player newregion oldregion -- )
316
317Invoked when a player entered a new region. Cannot be overriden.
287 318
288=head3 command (player command args -- time) 319=head3 command (player command args -- time)
289 320
290Execute a user command send by the client. Programmable plug-ins usually 321Execute a user command send by the client. Programmable plug-ins usually
291handle this event internally. 322handle this event internally.
… …
295Invoked whenever a client issues the C<extcmd> protocol command. 326Invoked whenever a client issues the C<extcmd> protocol command.
296Programmable plug-ins usually handle this event internally. 327Programmable plug-ins usually handle this event internally.
297 328
298=head3 move (player direction -- ) 329=head3 move (player direction -- )
299 330
331Called whenever the player is supposed to move or attack. The handler
332must handle the cases of speed_left or weapon_sp_left being negative,
333fire being on, is responsible for decreaseing the speed_left value
334on successful moves etc. etc.. When overriden, must return a boolean
335indicating wether a move could be effected.
336
300=head3 pray_altar (player altar skill -- ) 337=head3 pray_altar (player altar skill -- )
301 338
302Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>. 339Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
303 340
304=head3 tell (player name message -- ) 341=head3 tell (player name message -- )
305 342
306Invoked whenever the player uses the B<tell> or B<reply> command, before 343Invoked whenever the player uses the B<tell> or B<reply> command, before
307it gets processed. 344it gets processed.
345
346=head3 told (player player message -- )
347
348Invoked right before a message is being told to a player using B<tell> or
349B<reply>.
308 350
309=head3 say (player message --) 351=head3 say (player message --)
310 352
311=head3 chat (player message --) 353=head3 chat (player message --)
312 354
… …
351=head3 leave (map player -- ) 393=head3 leave (map player -- )
352 394
353Invoked whenever a player tries to leave the B<map>. Overriding means the 395Invoked whenever a player tries to leave the B<map>. Overriding means the
354player won't be able to leave. 396player won't be able to leave.
355 397
356=head3 trigger (map connection state -- ) 398=head3 trigger (map connection state what? who? -- )
357 399
358Invoked whenever something activates a B<connection> on the B<map>. If B<state> 400Invoked whenever something activates a B<connection> on the B<map>. If B<state>
359is true the connection was 'state' and if false it is 'released'. 401is true the connection was 'state' and if false it is 'released'.
360 402
361 403
… …
368=head3 connect (client -- ) 410=head3 connect (client -- )
369 411
370Called as soon as a new connection to the server is established. Should 412Called as soon as a new connection to the server is established. Should
371not be overriden. 413not be overriden.
372 414
415=head3 setup (client string -- )
416
417Client sent the setup command to negotiate parameters. Handling is
418mandatory and done by F<login.ext>.
419
373=head3 addme (client -- ) 420=head3 addme (client -- )
374 421
375The client sent an addme, thus ending the initial handshaking. If overriden, the server 422The client sent an addme, thus ending the initial handshaking. Handling is mandatory
376will not send any response. 423and done by F<login.ext>.
377 424
378=head3 reply (client replystring -- ) 425=head3 reply (client replystring -- )
379 426
380Called when the client submits a reply in the ST_CUSTOM state. Usually 427Called when the client submits a reply in the ST_CUSTOM state. Usually
381handled internally by language plugins. 428handled internally by language plugins.

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines