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.4 by root, Sun Sep 17 14:22:28 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
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
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
71=head3 add_bonus (item creator difficulty max_magic flags -- )
72
73A basic item has been created (e.g. for shops, monsters drops etc.)
74that needs bonus values applied. The B<creator> object is a template
75object that can be used to inherit stuff (and can be NULL). Flags is a
76combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP
77on item or set its value to 0) or GT_MINIMAL (???)
78
79When overriden, built-in bonus generation is skipped, otherwise
80treasure generation continues as it would without this hook.
81
82In general, if flags != 0 or creator != 0 you should just return and leave
83item generation to the standard code.
84
85=head3 remove (object -- )
86
87Invoked before the object is removed from its environment.
88
89=head3 insert (object -- )
90
91Called after the object was inserted into a container or map.
92
60=head3 tick (object) 93=head3 tick (object -- )
61 94
62Invoked 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
63during ticks should an objetc process any movement or other events. 96during ticks should an objetc process any movement or other events.
64 97
65=head3 kill (object hitter -- ) 98=head3 kill (object hitter -- )
66 99
67Invoked 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
68processing will skip removal, but to do this successfully you have to 101about to get removed. Overriding processing will skip removal, but to do
69objetc 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.
70 104
71=head3 apply (object who -- applytype) 105=head3 apply (object who -- applytype)
72 106
73Invoked 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:
74 108
… …
79=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
80 114
81=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
82 116
83=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.
84 123
85=head3 throw (object thrower) 124=head3 throw (object thrower)
86 125
87Invoked when an B<object> is thrown by B<thrower>. 126Invoked when an B<object> is thrown by B<thrower>.
88 127
… …
114Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>, 153Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
115currently 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'
116(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
117object was freed. 156object was freed.
118 157
119=head3 use_skill (skill who part direction strignarg -- ) 158=head3 use_skill (skill who part direction stringarg -- )
120 159
121Invoked whenever a skill is used by somebody or something. 160Invoked whenever a skill is used by somebody or something.
122 161
123=head3 cast_spell (spell casting_object owner direction stringarg -- ) 162=head3 cast_spell (spell owner casting_object direction stringarg -- )
124 163
125Invoked 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
126B<owner>). 165B<owner>).
127 166
128=head3 drop (object who -- ) 167=head3 drop (object who -- )
… …
151damage that has been dealt. 190damage that has been dealt.
152 191
153=head3 skill_attack (attacker victim message skill -- success) 192=head3 skill_attack (attacker victim message skill -- success)
154 193
155Invoked 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
156cna 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
157damage is done. 196damage is done.
158 197
159=head3 weapon_attack (weapon hitter victim) 198=head3 weapon_attack (weapon hitter victim)
160 199
161Invoked 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
… …
174 213
175Invoked whenever a trap-like B<object> has been activated, usually by 214Invoked whenever a trap-like B<object> has been activated, usually by
176moving onto it. This includes not just traps, but also buttons, holes, 215moving onto it. This includes not just traps, but also buttons, holes,
177signs and similar stuff. 216signs and similar stuff.
178 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
179=head3 close (container who -- ) 223=head3 close (container who -- )
180 224
181Invoked 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.
182 241
183 242
184=head2 GLOBAL EVENTS 243=head2 GLOBAL EVENTS
185 244
186Global events have no relation to specific objects. 245Global events have no relation to specific objects.
187 246
188=head3 cleanup () 247=head3 cleanup ()
189 248
190Called when the server is cleaning up, just before it calls exit. 249Called when the server is cleaning up, just before it calls exit.
191 250
192=head3 clock ( ) 251=head3 clock ()
193 252
194Is invoked on every server tick, usually every 0.12 seconds. 253Is invoked on every server tick, usually every 0.12 seconds.
195 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
196 260
197=head2 PLAYER EVENTS 261=head2 PLAYER EVENTS
198 262
199Player events always have a player object as first argument. 263Player events always have a player object as first argument.
200 264
201=head3 reattach (player)
202
203Invoked whenever attachments/plug-ins need to get reattached to the player
204object. This usually happens when the player gets loaded from disk, or
205when the server is reloaded.
206
207=head3 birth (player) 265=head3 birth (player)
208 266
209Invoked as very first thing after creating a player. 267Invoked as very first thing after creating a player.
210 268
211=head3 quit (player) 269=head3 quit (player)
212 270
213Invoked wheneever a player quits, before actually removing him/her. 271Invoked wheneever a player quits, before actually removing him/her.
214 272
215=head3 kick (player params -- ) 273=head3 kick (player params -- )
216 274
217Invoked 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.
218 277
219=head3 load (player) 278=head3 load (player -- )
220 279
221Invoked whenever a player has been loaded from disk, but before 280Invoked whenever a player has been loaded from disk, but before
222actual login. 281actual login.
223 282
224=head3 save (player) 283=head3 save (player -- )
225 284
226Invoked 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.
227 298
228=head3 login (player) 299=head3 login (player)
229 300
230Invoked whenever a player logs in. 301Invoked whenever a player logs in.
231 302
232=head3 logout (player) 303=head3 logout (player cleanly -- )
233 304
234Invoked whenever a player logs out, gets disconnected etc. 305Invoked whenever a player logs out, gets disconnected etc.
235 306
236=head3 death (player) 307=head3 death (player)
237 308
… …
239 310
240=head3 map_change (player newmap x y -- ) 311=head3 map_change (player newmap x y -- )
241 312
242Invoked 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.
243 314
315=head3 region_change (player newregion oldregion -- )
316
317Invoked when a player entered a new region. Cannot be overriden.
318
319=head3 command (player command args -- time)
320
321Execute a user command send by the client. Programmable plug-ins usually
322handle this event internally.
323
244=head3 extcmd (player string) 324=head3 extcmd (player string)
245 325
246Invoked whenever a client issues the C<extcmd> protocol command. It's 326Invoked whenever a client issues the C<extcmd> protocol command.
247argument is passed without any changes. 327Programmable plug-ins usually handle this event internally.
248 328
249=head3 move (player direction -- ) 329=head3 move (player direction -- )
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.
250 336
251=head3 pray_altar (player altar skill -- ) 337=head3 pray_altar (player altar skill -- )
252 338
253Invoked 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>.
254 340
255=head3 tell (player name message -- ) 341=head3 tell (player name message -- )
256 342
257Invoked 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
258it gets processed. 344it gets processed.
259 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
260=head3 say (player message --) 351=head3 say (player message --)
261 352
262=head3 chat (player message --) 353=head3 chat (player message --)
263 354
264=head3 shout (player message --) 355=head3 shout (player message --)
… …
275=head3 instantiate (map) 366=head3 instantiate (map)
276 367
277Original 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
278reset). 369reset).
279 370
280=head3 reattach (map)
281
282Invoked whenever attachments/plug-ins need to get reattached to the
283B<map>. This usually happens when the map was loaded from disk, or when the
284server was reloaded.
285
286=head3 destroy (map)
287
288Invoked when the map object gets destroyed, and only when the map object
289has a handler for this event. This event can occur many times, as its
290called when the in-memory object is destroyed, not when the object itself
291dies.
292
293=head3 swapin (map) 371=head3 swapin (map)
294 372
295Invoked 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.
296 374
297=head3 swapout (map) 375=head3 swapout (map)
… …
307Invoked when a temporary B<map> gets deleted on-disk. 385Invoked when a temporary B<map> gets deleted on-disk.
308 386
309=head3 enter (map player x y -- ) 387=head3 enter (map player x y -- )
310 388
311Invoked whenever a player tries to enter the B<map>, while he/she is still 389Invoked whenever a player tries to enter the B<map>, while he/she is still
312on the old map. Overriding means the player won't be able to enter. 390on the old map. Overriding means the player won't be able to enter, and,
391if newmap/x/y are given, will be redirected to that map instead.
313 392
314=head3 leave (map player -- ) 393=head3 leave (map player -- )
315 394
316Invoked 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
317player won't be able to leave. 396player won't be able to leave.
318 397
319=head3 trigger (map connection state) 398=head3 trigger (map connection state what? who? -- )
320 399
321Invoked 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>
322is true the connection was 'state' and if false it is 'released'. 401is true the connection was 'state' and if false it is 'released'.
402
403
404=head2 CLIENT EVENTS
405
406These events are very similar to player events, but they are might be
407handled asynchronously as soon as the command reaches the server, even when
408the player hasn't logged in yet (meaning there is no player yet).
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
430=head3 exticmd (client string -- )
431
432Like C<extcmd>, but can be called before a player has logged in.
433
434Programmable plug-ins usually handle this event internally.
435

Diff Legend

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