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.8 by root, Tue Dec 19 04:58:05 2006 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 OBJECT EVENTS 27=head2 ATTACHABLE EVENTS
24 28
25Object events always relate to a specific object, which is always the 29No time to document this, screw me.
26first argument. Not all events get generated for every object, some are
27specific to an object type.
28 30
29=head3 instantiate (object init-args...) 31=head3 instantiate (object init-args...)
30 32
31An archetype was instantiated into an object. This event occurs when 33An object was instantiated.
32a map is loaded for the first time, or when the object was created 34
35For objects, this event occurs when a map is loaded for the first time
36when it was instantiated from an archetype, or when the object was created
33dynamically. The arguments are as specified in the C<attach> attribute of 37dynamically. The arguments are as specified in the C<attach> attribute of
34the object or archetype. 38the object or archetype.
35 39
36This is useful to initialise any per-object state you might need. 40This is useful to initialise any per-object state you might need.
37 41
… …
42server was reloaded. This event will only be generated if the object has 46server was reloaded. This event will only be generated if the object has
43attachments. 47attachments.
44 48
45=head3 clone (object destination) 49=head3 clone (object destination)
46 50
47An object with _attached extension_ is cloned, that is, a copy was 51An object with _attached plugin_ is cloned, that is, a copy was made. The
48made. The copy automatically has all attachments the original object 52copy automatically has all attachments the original object had. The perl
49had. The perl variables get copied in a shallow way (references are shared 53variables get copied in a shallow way (references are shared between
50between instances). If this is not the behaviour you need, you have to 54instances). If this is not the behaviour you need, you have to adjust the
51adjust the B<destination> object as you see fit. 55B<destination> object as you see fit.
52 56
57=head3 destroy (object -- )
58
59Invoked when the deliantra object gets destroyed, and only when the object
60has a handler for this event. This event can occur many times, as its
61called when the in-memory object is destroyed, not when the object itself
62dies.
63
64
65=head2 OBJECT EVENTS
66
67Object events always relate to a specific object, which is always the
68first argument. Not all events get generated for every object, some are
69specific to an object type.
70
53=head3 add_bonus (item creator difficulty max_magic flags) 71=head3 add_bonus (item creator difficulty max_magic flags -- )
54 72
55A 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.)
56that needs bonus values applied. The B<creator> object is a template 74that needs bonus values applied. The B<creator> object is a template
57object 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
58combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP 76combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP
… …
62treasure generation continues as it would without this hook. 80treasure generation continues as it would without this hook.
63 81
64In general, if flags != 0 or creator != 0 you should just return and leave 82In general, if flags != 0 or creator != 0 you should just return and leave
65item generation to the standard code. 83item generation to the standard code.
66 84
67=head3 destroy (object) 85=head3 remove (object -- )
68 86
69Invoked when the crossfire object gets destroyed, and only when the object 87Invoked before the object is removed from its environment.
70has a handler for this event. This event can occur many times, as its
71called when the in-memory object is destroyed, not when the object itself
72dies.
73 88
89=head3 insert (object -- )
90
91Called after the object was inserted into a container or map.
92
74=head3 tick (object) 93=head3 tick (object -- )
75 94
76Invoked 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
77during ticks should an objetc process any movement or other events. 96during ticks should an objetc process any movement or other events.
78 97
79=head3 kill (object hitter -- ) 98=head3 kill (object hitter -- )
80 99
81Invoked 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
82processing will skip removal, but to do this successfully you have to 101about to get removed. Overriding processing will skip removal, but to do
83objetc 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.
84 104
85=head3 apply (object who -- applytype) 105=head3 apply (object who -- applytype)
86 106
87Invoked 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:
88 108
… …
93=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
94 114
95=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
96 116
97=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.
98 123
99=head3 throw (object thrower) 124=head3 throw (object thrower)
100 125
101Invoked when an B<object> is thrown by B<thrower>. 126Invoked when an B<object> is thrown by B<thrower>.
102 127
… …
128Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>, 153Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
129currently 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'
130(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
131object was freed. 156object was freed.
132 157
133=head3 use_skill (skill who part direction strignarg -- ) 158=head3 use_skill (skill who part direction stringarg -- )
134 159
135Invoked whenever a skill is used by somebody or something. 160Invoked whenever a skill is used by somebody or something.
136 161
137=head3 cast_spell (spell casting_object owner direction stringarg -- ) 162=head3 cast_spell (spell owner casting_object direction stringarg -- )
138 163
139Invoked 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
140B<owner>). 165B<owner>).
141 166
142=head3 drop (object who -- ) 167=head3 drop (object who -- )
… …
165damage that has been dealt. 190damage that has been dealt.
166 191
167=head3 skill_attack (attacker victim message skill -- success) 192=head3 skill_attack (attacker victim message skill -- success)
168 193
169Invoked 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
170cna 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
171damage is done. 196damage is done.
172 197
173=head3 weapon_attack (weapon hitter victim) 198=head3 weapon_attack (weapon hitter victim)
174 199
175Invoked 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
… …
188 213
189Invoked whenever a trap-like B<object> has been activated, usually by 214Invoked whenever a trap-like B<object> has been activated, usually by
190moving onto it. This includes not just traps, but also buttons, holes, 215moving onto it. This includes not just traps, but also buttons, holes,
191signs and similar stuff. 216signs and similar stuff.
192 217
218=head3 open (container who -- )
219
220Invoked whenever a container gets opened. When overriden, the container will not
221get opened, but you must tell op about the reason.
222
193=head3 close (container who -- ) 223=head3 close (container who -- )
194 224
195Invoked whenever a container gets closed (this event is not yet reliable!). 225Invoked whenever a container gets closed. When overriden, the container
226will not get closed, but you must tell op about the reason. This event
227is not crash-safe, i.e. containers might be closed due to a server crash
228without this event being invoked.
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.
196 241
197 242
198=head2 GLOBAL EVENTS 243=head2 GLOBAL EVENTS
199 244
200Global events have no relation to specific objects. 245Global events have no relation to specific objects.
201 246
202=head3 cleanup () 247=head3 cleanup ()
203 248
204Called when the server is cleaning up, just before it calls exit. 249Called when the server is cleaning up, just before it calls exit.
205 250
206=head3 clock ( ) 251=head3 clock ()
207 252
208Is invoked on every server tick, usually every 0.12 seconds. 253Is invoked on every server tick, usually every 0.12 seconds.
209 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.
259
210 260
211=head2 PLAYER EVENTS 261=head2 PLAYER EVENTS
212 262
213Player events always have a player object as first argument. 263Player events always have a player object as first argument.
214 264
215=head3 reattach (player)
216
217Invoked whenever attachments/plug-ins need to get reattached to the player
218object. This usually happens when the player gets loaded from disk, or
219when the server is reloaded.
220
221=head3 birth (player) 265=head3 birth (player)
222 266
223Invoked as very first thing after creating a player. 267Invoked as very first thing after creating a player.
224 268
225=head3 quit (player) 269=head3 quit (player)
226 270
227Invoked wheneever a player quits, before actually removing him/her. 271Invoked wheneever a player quits, before actually removing him/her.
228 272
229=head3 kick (player params -- ) 273=head3 kick (player params -- )
230 274
231Invoked when the given plaer is being kicked, before the kick is executed. 275Invoked when the given player is being kicked, before the kick is
276executed.
232 277
233=head3 load (player) 278=head3 load (player -- )
234 279
235Invoked whenever a player has been loaded from disk, but before 280Invoked whenever a player has been loaded from disk, but before
236actual login. 281actual login.
237 282
238=head3 save (player) 283=head3 save (player -- )
239 284
240Invoked just before a player gets saved. 285Invoked just before a player gets serialised.
286
287=head3 save_done (player -- )
288
289Invoked just after a player was serialised.
290
291=head3 connect (player -- )
292
293Invoked just after the player object was connected to a client.
294
295=head3 disconnect (player -- )
296
297Invoked just before the player gets disconnected from the client.
241 298
242=head3 login (player) 299=head3 login (player)
243 300
244Invoked whenever a player logs in. 301Invoked whenever a player logs in.
245 302
246=head3 logout (player) 303=head3 logout (player cleanly -- )
247 304
248Invoked whenever a player logs out, gets disconnected etc. 305Invoked whenever a player logs out, gets disconnected etc.
249 306
250=head3 death (player) 307=head3 death (player)
251 308
252Invoked whenever a player dies, before the death actually gets processed. 309Invoked whenever a player dies, before the death actually gets processed.
253 310
254=head3 map_change (player newmap x y -- ) 311=head3 map_change (player newmap x y -- )
255 312
256Invoked 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.
257 318
258=head3 command (player command args -- time) 319=head3 command (player command args -- time)
259 320
260Execute a user command send by the client. Programmable plug-ins usually 321Execute a user command send by the client. Programmable plug-ins usually
261handle this event internally. 322handle this event internally.
… …
265Invoked whenever a client issues the C<extcmd> protocol command. 326Invoked whenever a client issues the C<extcmd> protocol command.
266Programmable plug-ins usually handle this event internally. 327Programmable plug-ins usually handle this event internally.
267 328
268=head3 move (player direction -- ) 329=head3 move (player direction -- )
269 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
270=head3 pray_altar (player altar skill -- ) 337=head3 pray_altar (player altar skill -- )
271 338
272Invoked 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>.
273 340
274=head3 tell (player name message -- ) 341=head3 tell (player name message -- )
275 342
276Invoked 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
277it gets processed. 344it gets processed.
278 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>.
350
279=head3 say (player message --) 351=head3 say (player message --)
280 352
281=head3 chat (player message --) 353=head3 chat (player message --)
282 354
283=head3 shout (player message --) 355=head3 shout (player message --)
… …
293 365
294=head3 instantiate (map) 366=head3 instantiate (map)
295 367
296Original B<map> has been loaded (e.g. on first use, or after a map 368Original B<map> has been loaded (e.g. on first use, or after a map
297reset). 369reset).
298
299=head3 reattach (map)
300
301Invoked whenever attachments/plug-ins need to get reattached to the
302B<map>. This usually happens when the map was loaded from disk, or when the
303server was reloaded.
304
305=head3 destroy (map)
306
307Invoked when the map object gets destroyed, and only when the map object
308has a handler for this event. This event can occur many times, as its
309called when the in-memory object is destroyed, not when the object itself
310dies.
311 370
312=head3 swapin (map) 371=head3 swapin (map)
313 372
314Invoked when a previously swapped-out temporary B<map> has been loaded again. 373Invoked when a previously swapped-out temporary B<map> has been loaded again.
315 374
… …
334=head3 leave (map player -- ) 393=head3 leave (map player -- )
335 394
336Invoked 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
337player won't be able to leave. 396player won't be able to leave.
338 397
339=head3 trigger (map connection state) 398=head3 trigger (map connection state what? who? -- )
340 399
341Invoked 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>
342is true the connection was 'state' and if false it is 'released'. 401is true the connection was 'state' and if false it is 'released'.
343 402
344 403
… …
346 405
347These events are very similar to player events, but they are might be 406These events are very similar to player events, but they are might be
348handled asynchronously as soon as the command reaches the server, even when 407handled asynchronously as soon as the command reaches the server, even when
349the player hasn't logged in yet (meaning there is no player yet). 408the player hasn't logged in yet (meaning there is no player yet).
350 409
410=head3 connect (client -- )
411
412Called as soon as a new connection to the server is established. Should
413not be overriden.
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
420=head3 addme (client -- )
421
422The client sent an addme, thus ending the initial handshaking. Handling is mandatory
423and done by F<login.ext>.
424
425=head3 reply (client replystring -- )
426
427Called when the client submits a reply in the ST_CUSTOM state. Usually
428handled internally by language plugins.
429
351=head3 exticmd (client string) 430=head3 exticmd (client string -- )
352 431
353Like C<extcmd>, but can be called before a player has logged in. 432Like C<extcmd>, but can be called before a player has logged in.
354 433
355Programmable plug-ins usually handle this event internally. 434Programmable plug-ins usually handle this event internally.
356 435

Diff Legend

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