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.19 by root, Tue May 22 10:50:00 2007 UTC vs.
Revision 1.33 by root, Tue Nov 3 23:44:21 2009 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
… …
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
… …
215Invoked whenever a container gets closed. When overriden, the container 249Invoked whenever a container gets closed. When overriden, the container
216will not get closed, but you must tell op about the reason. This event 250will 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 251is not crash-safe, i.e. containers might be closed due to a server crash
218without this event being invoked. 252without this event being invoked.
219 253
254=head3 blocked_move (self who -- do_blocked)
255
256Invoked when an C<who> tries to move to the same space as C<self>,
257C<self>'s C<move_block> causes blocked movement for C<who> and nothing
258else explicitly allows movement to this space.
259
260Should return true when C<who> is blocked, i.e., should not be allowed to
261move onto C<self>.
262
263When not overriding, normal blocked_move (blocked_link) processing will
264happen.
265
220 266
221=head2 GLOBAL EVENTS 267=head2 GLOBAL EVENTS
222 268
223Global events have no relation to specific objects. 269Global events have no relation to specific objects.
224 270
225=head3 cleanup () 271=head3 cleanup ()
226 272
227Called when the server is cleaning up, just before it calls exit. 273Called when the server is cleaning up, just before it calls exit.
228 274
229=head3 clock ( ) 275=head3 clock ()
230 276
231Is invoked on every server tick, usually every 0.12 seconds. 277Is invoked on every server tick, usually every 0.12 seconds.
278
279=head3 resource_update ()
280
281Is invoked after each time the server reloads its resources, which is
282usually one of the earliest things it does when starting up.
232 283
233 284
234=head2 PLAYER EVENTS 285=head2 PLAYER EVENTS
235 286
236Player events always have a player object as first argument. 287Player events always have a player object as first argument.
… …
271 322
272=head3 login (player) 323=head3 login (player)
273 324
274Invoked whenever a player logs in. 325Invoked whenever a player logs in.
275 326
276=head3 logout (player) 327=head3 logout (player cleanly -- )
277 328
278Invoked whenever a player logs out, gets disconnected etc. 329Invoked whenever a player logs out, gets disconnected etc.
279 330
280=head3 death (player) 331=head3 death (player)
281 332
282Invoked whenever a player dies, before the death actually gets processed. 333Invoked whenever a player dies, before the death actually gets processed.
283 334
284=head3 map_change (player newmap x y -- ) 335=head3 map_change (player newmap x y -- )
285 336
286Invoked before a player moves from one map to another, can override the movement. 337Invoked before a player moves from one map to another, can override the movement.
338
339=head3 region_change (player newregion oldregion -- )
340
341Invoked when a player entered a new region. Cannot be overriden.
287 342
288=head3 command (player command args -- time) 343=head3 command (player command args -- time)
289 344
290Execute a user command send by the client. Programmable plug-ins usually 345Execute a user command send by the client. Programmable plug-ins usually
291handle this event internally. 346handle this event internally.
… …
362=head3 leave (map player -- ) 417=head3 leave (map player -- )
363 418
364Invoked whenever a player tries to leave the B<map>. Overriding means the 419Invoked whenever a player tries to leave the B<map>. Overriding means the
365player won't be able to leave. 420player won't be able to leave.
366 421
367=head3 trigger (map connection state -- ) 422=head3 trigger (map connection state what? who? -- )
368 423
369Invoked whenever something activates a B<connection> on the B<map>. If B<state> 424Invoked whenever something activates a B<connection> on the B<map>. If B<state>
370is true the connection was 'state' and if false it is 'released'. 425is true the connection was 'state' and if false it is 'released'.
371 426
372 427

Diff Legend

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