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.12 by root, Mon Dec 25 11:25:49 2006 UTC vs.
Revision 1.41 by root, Mon Oct 1 01:43:39 2012 UTC

1=head1 CROSSFIRE+ PLUG-IN EVENTS 1=begin comment
2
3 This file is part of Deliantra, the Roguelike Realtime MMORPG.
4
5 Copyright (©) 2005,2006,2007,2008,2009 Marc Alexander Lehmann / Robin Redeker / the Deliantra team
6
7 Deliantra is free software: you can redistribute it and/or modify it under
8 the terms of the Affero GNU General Public License as published by the
9 Free Software Foundation, either version 3 of the License, or (at your
10 option) any later version.
11
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
16
17 You should have received a copy of the Affero GNU General Public License
18 and the GNU General Public License along with this program. If not, see
19 <http://www.gnu.org/licenses/>.
20
21 The authors can be reached via e-mail to <support@deliantra.net>
22
23=end comment
24
25=head1 DELIANTRA PLUG-IN EVENTS
2 26
3This document briefly describes each plug-in event. It is also used to 27This document briefly describes each plug-in event. It is also used to
4generate the event-list itself, so is always complete. Be careful wehn 28generate the event-list itself, so is always complete. Be careful wehn
5changing it, though. 29changing it, though.
6 30
7=head2 NOTATION 31=head2 NOTATION
8 32
9the event description below uses a variant of the forth stack notation - 33The event description below uses a variant of the forth stack notation -
10an opening parenthesis followed by the type of each parameter, optionally 34an opening parenthesis followed by the type of each parameter, optionally
11followed by two dashes and the returning parameters. If the latter is 35followed 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 36missing, the event will be invoked but cannot change wether the event gets
13processed. 37processed.
14 38
15If it is specified (even if no return values are supported), a plug-in 39Return values are given by overriding (in Perl by calling C<cf::override>)
16can override (e.g. using C<cf::override> in Perl) event processing, 40with the return values, which will both stop further event processing and
17basically short-circuiting it. For example, if you override from within a 41tell the caller that it wants to override normal processing.
18player BIRTH event, nothing much will happen with respect to the built-in 42
43Even if no return values are supported, a plug-in can override (e.g. using
44C<cf::override> in Perl) event processing, basically short-circuiting
45it. For example, if you override from within a player BIRTH event,
46nothing 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 47you override from within a player TELL event, the tell will be ignored
20will be ignored (presumably your plug-in took care of it). 48(presumably your plug-in took care of it).
21 49
22 50
23=head2 ATTACHABLE EVENTS 51=head2 ATTACHABLE EVENTS
24 52
25No time to document this, screw me. 53No time to document this, screw me.
… …
50instances). If this is not the behaviour you need, you have to adjust the 78instances). If this is not the behaviour you need, you have to adjust the
51B<destination> object as you see fit. 79B<destination> object as you see fit.
52 80
53=head3 destroy (object -- ) 81=head3 destroy (object -- )
54 82
55Invoked when the crossfire object gets destroyed, and only when the object 83Invoked 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 84has 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 85called when the in-memory object is destroyed, not when the object itself
58dies. 86dies.
59 87
60 88
… …
62 90
63Object events always relate to a specific object, which is always the 91Object events always relate to a specific object, which is always the
64first argument. Not all events get generated for every object, some are 92first argument. Not all events get generated for every object, some are
65specific to an object type. 93specific to an object type.
66 94
67=head3 add_bonus (item creator difficulty max_magic flags) 95=head3 add_bonus (item creator difficulty max_magic flags -- )
68 96
69A basic item has been created (e.g. for shops, monsters drops etc.) 97A basic item has been created (e.g. for shops, monsters drops etc.)
70that needs bonus values applied. The B<creator> object is a template 98that 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 99object that can be used to inherit stuff (and can be NULL). Flags is a
72combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP 100combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP
… …
91Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only 119Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
92during ticks should an objetc process any movement or other events. 120during ticks should an objetc process any movement or other events.
93 121
94=head3 kill (object hitter -- ) 122=head3 kill (object hitter -- )
95 123
96Invoked whenever an object is dead and about to get removed. Overriding 124Invoked 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 125about to get removed. Overriding processing will skip removal, but to do
98objetc from dieing, otherwise the event gets invoked again and again. 126this successfully you have to keep the object from dieing, otherwise the
127event gets invoked again and again.
99 128
100=head3 apply (object who -- applytype) 129=head3 apply (object who -- applytype)
101 130
102Invoked whenever the object is being applied in some way. The applytype is one of: 131Invoked whenever the object is being applied in some way. The applytype is one of:
103 132
… …
108=item B<1> has been applied, or there was an error applying the object 137=item B<1> has been applied, or there was an error applying the object
109 138
110=item B<2> objects of that type can't be applied if not in inventory 139=item B<2> objects of that type can't be applied if not in inventory
111 140
112=back 141=back
142
143=head3 reset (object)
144
145Invoked whenever the object is initialised on a map after it was
146loaded. This can be used to emulate shop-floor behaviour for example.
113 147
114=head3 throw (object thrower) 148=head3 throw (object thrower)
115 149
116Invoked when an B<object> is thrown by B<thrower>. 150Invoked when an B<object> is thrown by B<thrower>.
117 151
… …
143Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>, 177Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
144currently applied by B<who>. If your override, make sure you give 'who' 178currently 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 179(if it is a player) an indication of whats wrong. Must return true if the
146object was freed. 180object was freed.
147 181
148=head3 use_skill (skill who part direction strignarg -- ) 182=head3 use_skill (skill who part direction stringarg -- )
149 183
150Invoked whenever a skill is used by somebody or something. 184Invoked whenever a skill is used by somebody or something.
151 185
152=head3 cast_spell (spell casting_object owner direction stringarg -- ) 186=head3 cast_spell (spell owner casting_object direction stringarg -- )
153 187
154Invoked whenever a given spell is cast by B<casting_object> (used by 188Invoked whenever a given spell is cast by B<casting_object> (used by
155B<owner>). 189B<owner>).
156 190
157=head3 drop (object who -- ) 191=head3 drop (object who -- )
… …
180damage that has been dealt. 214damage that has been dealt.
181 215
182=head3 skill_attack (attacker victim message skill -- success) 216=head3 skill_attack (attacker victim message skill -- success)
183 217
184Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill 218Invoked 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 219can be C<undef>). B<message> is the message that describes the attack when
186damage is done. 220damage is done.
187 221
188=head3 weapon_attack (weapon hitter victim) 222=head3 weapon_attack (weapon hitter victim)
189 223
190Invoked whenever an object is used as a B<weapon> by B<hitter> to attack 224Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
191B<victim>. 225B<victim>.
192 226
193=head3 inscribe_note (book pl message skill -- ) 227=head3 inscribe_note (book pl message skill -- )
194 228
195Used whenever a book gets inscribed with a message. 229Used whenever a book gets inscribed with a message.
230
231=head3 infect (victim disease_type disease -- )
232
233Invoked whenever an object is diseased. The disease object is already
234inserted in object (the template disease object is C<disease_type>),
235but no messages have been generated. If overriden, no messages will be
236generated.
196 237
197=head3 trigger (object who -- ) 238=head3 trigger (object who -- )
198 239
199Invoked whenever a lever-like B<object> has been activated/triggered in some 240Invoked whenever a lever-like B<object> has been activated/triggered in some
200(manual) way. 241(manual) way.
… …
203 244
204Invoked whenever a trap-like B<object> has been activated, usually by 245Invoked whenever a trap-like B<object> has been activated, usually by
205moving onto it. This includes not just traps, but also buttons, holes, 246moving onto it. This includes not just traps, but also buttons, holes,
206signs and similar stuff. 247signs and similar stuff.
207 248
249=head3 open (container who -- )
250
251Invoked whenever a container gets opened. When overriden, the container will not
252get opened, but you must tell op about the reason.
253
208=head3 close (container who -- ) 254=head3 close (container who -- )
209 255
210Invoked whenever a container gets closed (this event is not yet reliable!). 256Invoked whenever a container gets closed. When overriden, the container
257will not get closed, but you must tell op about the reason. This event
258is not crash-safe, i.e. containers might be closed due to a server crash
259without this event being invoked.
260
261=head3 blocked_move (self who -- do_blocked)
262
263Invoked when an C<who> tries to move to the same space as C<self>,
264C<self>'s C<move_block> causes blocked movement for C<who> and nothing
265else explicitly allows movement to this space.
266
267Should return true when C<who> is blocked, i.e., should not be allowed to
268move onto C<self>.
269
270When not overriding, normal blocked_move (blocked_link) processing will
271happen.
211 272
212 273
213=head2 GLOBAL EVENTS 274=head2 GLOBAL EVENTS
214 275
215Global events have no relation to specific objects. 276Global events have no relation to specific objects.
216 277
217=head3 cleanup () 278=head3 cleanup ()
218 279
219Called when the server is cleaning up, just before it calls exit. 280Called when the server is cleaning up, just before it calls exit.
220 281
221=head3 clock ( ) 282=head3 clock ()
222 283
223Is invoked on every server tick, usually every 0.12 seconds. 284Is invoked on every server tick, usually every 0.12 seconds.
224 285
286=head3 resource_update ()
287
288Is invoked after each time the server reloads its resources, which is
289usually one of the earliest things it does when starting up.
290
225 291
226=head2 PLAYER EVENTS 292=head2 PLAYER EVENTS
227 293
228Player events always have a player object as first argument. 294Player events always have a player object as first argument.
229 295
… …
235 301
236Invoked wheneever a player quits, before actually removing him/her. 302Invoked wheneever a player quits, before actually removing him/her.
237 303
238=head3 kick (player params -- ) 304=head3 kick (player params -- )
239 305
240Invoked when the given plaer is being kicked, before the kick is executed. 306Invoked when the given player is being kicked, before the kick is
307executed.
241 308
242=head3 load (player) 309=head3 load (player -- )
243 310
244Invoked whenever a player has been loaded from disk, but before 311Invoked whenever after a player has been loaded from disk, but before
245actual login. 312actual activation/login.
246 313
247=head3 save (player) 314=head3 save (player -- )
248 315
249Invoked just before a player gets saved. 316Invoked just before a player gets serialised.
317
318=head3 save_done (player -- )
319
320Invoked just after a player was serialised.
321
322=head3 connect (player -- )
323
324Invoked just after the player object was connected to a client.
325
326=head3 disconnect (player -- )
327
328Invoked just before the player gets disconnected from the client.
250 329
251=head3 login (player) 330=head3 login (player)
252 331
253Invoked whenever a player logs in. 332Invoked whenever a player logs in.
254 333
255=head3 logout (player) 334=head3 logout (player cleanly -- )
256 335
257Invoked whenever a player logs out, gets disconnected etc. 336Invoked whenever a player logs out, gets disconnected etc.
258 337
259=head3 death (player) 338=head3 death (player)
260 339
… …
262 341
263=head3 map_change (player newmap x y -- ) 342=head3 map_change (player newmap x y -- )
264 343
265Invoked before a player moves from one map to another, can override the movement. 344Invoked before a player moves from one map to another, can override the movement.
266 345
346=head3 region_change (player newregion oldregion -- )
347
348Invoked when a player entered a new region. Cannot be overriden.
349
267=head3 command (player command args -- time) 350=head3 command (player command args -- time)
268 351
269Execute a user command send by the client. Programmable plug-ins usually 352Execute a user command sent by the client - this is invoked for I<all>
270handle this event internally. 353command,s so should not normally be hooked.
354
355=head3 unknown_command (player command args -- time)
356
357Execute a user command sent by the client that isn't known to the
358server. Programmable plug-ins usually handle this event internally.
271 359
272=head3 extcmd (player string) 360=head3 extcmd (player string)
273 361
274Invoked whenever a client issues the C<extcmd> protocol command. 362Invoked whenever a client issues the C<extcmd> protocol command.
275Programmable plug-ins usually handle this event internally. 363Programmable plug-ins usually handle this event internally.
276 364
277=head3 move (player direction -- ) 365=head3 move (player direction -- )
278 366
367Called whenever the player is supposed to move or attack. The handler
368must handle the cases of speed_left or weapon_sp_left being negative,
369fire being on, is responsible for decreaseing the speed_left value
370on successful moves etc. etc.. When overriden, must return a boolean
371indicating wether a move could be effected.
372
279=head3 pray_altar (player altar skill -- ) 373=head3 pray_altar (player altar skill -- )
280 374
281Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>. 375Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
282 376
283=head3 tell (player name message -- ) 377=head3 tell (player name message -- )
284 378
285Invoked whenever the player uses the B<tell> or B<reply> command, before 379Invoked whenever the player uses the B<tell> or B<reply> command, before
286it gets processed. 380it gets processed.
287 381
382=head3 told (player player message -- )
383
384Invoked right before a message is being told to a player using B<tell> or
385B<reply>.
386
288=head3 say (player message --) 387=head3 say (player message --)
289 388
290=head3 chat (player message --) 389=head3 chat (player message --)
291 390
292=head3 shout (player message --) 391=head3 shout (player message --)
293 392
294Invoked whenever the player uses the B<say>, B<chat> or B<shout> command, 393Invoked whenever the player uses the B<say>, B<chat> or B<shout> command,
295before it gets processed. 394before it gets processed.
395
396=head3 build (player builder map x y checkok --)
397
398Players tries to build using C<builder> at (map+x+y). Is invoked after
399the usual map sanity checks, so the coordinates are valid. The boolean
400C<checkok> is true only if the build code thinks it is "ok" to build at
401that space, and normally you should only build when it is true.
296 402
297 403
298=head2 MAP EVENTS 404=head2 MAP EVENTS
299 405
300These events are generally dependent on a map and thus all have a map 406These events are generally dependent on a map and thus all have a map
… …
330=head3 leave (map player -- ) 436=head3 leave (map player -- )
331 437
332Invoked whenever a player tries to leave the B<map>. Overriding means the 438Invoked whenever a player tries to leave the B<map>. Overriding means the
333player won't be able to leave. 439player won't be able to leave.
334 440
335=head3 trigger (map connection state -- ) 441=head3 trigger (map connection state what? who? -- )
336 442
337Invoked whenever something activates a B<connection> on the B<map>. If B<state> 443Invoked whenever something activates a B<connection> on the B<map>. If B<state>
338is true the connection was 'state' and if false it is 'released'. 444is true the connection was 'state' and if false it is 'released'.
339 445
340 446
… …
344handled asynchronously as soon as the command reaches the server, even when 450handled asynchronously as soon as the command reaches the server, even when
345the player hasn't logged in yet (meaning there is no player yet). 451the player hasn't logged in yet (meaning there is no player yet).
346 452
347=head3 connect (client -- ) 453=head3 connect (client -- )
348 454
349Called as soon as a new connection to the server is established. Should 455Called as soon as a new connection to the server is established and the
350not be overriden. 456socket has been configured.
457
458=head3 version (client string -- )
459
460Called as soon as the version command from the client is received
461(normally the very first command sent).
462
463=head3 setup (client string -- )
464
465Client sent the setup command to negotiate parameters. Handling is
466mandatory and done by F<login.ext>.
351 467
352=head3 addme (client -- ) 468=head3 addme (client -- )
353 469
354The client sent an addme, thus ending the initial handshaking. If overriden, the server 470The client sent an addme, thus ending the initial handshaking. Handling is mandatory
355will not send any response. 471and done by F<login.ext>.
356 472
357=head3 reply (client replystring -- ) 473=head3 reply (client replystring -- )
358 474
359Called when the client submits a reply in the ST_CUSTOM state. Usually 475Called when the client submits a reply in the ST_CUSTOM state. Usually
360handled internally by language plugins. 476handled internally by language plugins.
… …
363 479
364Like C<extcmd>, but can be called before a player has logged in. 480Like C<extcmd>, but can be called before a player has logged in.
365 481
366Programmable plug-ins usually handle this event internally. 482Programmable plug-ins usually handle this event internally.
367 483
484=head3 client_destroy (client -- )
485
486Invoked when the client gets destroyed.
487
488

Diff Legend

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