ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/deliantra/server/pod/events.pod
Revision: 1.25
Committed: Wed Apr 30 05:34:24 2008 UTC (16 years, 1 month ago) by root
Branch: MAIN
CVS Tags: rel-2_54, rel-2_55, rel-2_56, rel-2_53
Changes since 1.24: +4 -3 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.23 =head1 DELIANTRA PLUG-IN EVENTS
2 pippijn 1.1
3     This document briefly describes each plug-in event. It is also used to
4     generate the event-list itself, so is always complete. Be careful wehn
5     changing it, though.
6    
7     =head2 NOTATION
8    
9     the event description below uses a variant of the forth stack notation -
10     an opening parenthesis followed by the type of each parameter, optionally
11     followed by two dashes and the returning parameters. If the latter is
12     missing, the event will be invoked but cannot change wether the event gets
13     processed.
14    
15     If it is specified (even if no return values are supported), a plug-in
16     can override (e.g. using C<cf::override> in Perl) event processing,
17     basically short-circuiting it. For example, if you override from within a
18     player BIRTH event, nothing much will happen with respect to the built-in
19     processing, but if you override from within a player TELL event, the tell
20     will be ignored (presumably your plug-in took care of it).
21    
22    
23 root 1.12 =head2 ATTACHABLE EVENTS
24 pippijn 1.1
25 root 1.12 No time to document this, screw me.
26 pippijn 1.1
27     =head3 instantiate (object init-args...)
28    
29 root 1.12 An object was instantiated.
30    
31     For objects, this event occurs when a map is loaded for the first time
32     when it was instantiated from an archetype, or when the object was created
33 pippijn 1.1 dynamically. The arguments are as specified in the C<attach> attribute of
34     the object or archetype.
35    
36     This is useful to initialise any per-object state you might need.
37    
38     =head3 reattach (object)
39    
40     Invoked whenever attachments/plug-ins need to get reattached to the
41     object. This usually happens when it was loaded from disk, or when the
42     server was reloaded. This event will only be generated if the object has
43     attachments.
44    
45     =head3 clone (object destination)
46    
47 root 1.12 An object with _attached plugin_ is cloned, that is, a copy was made. The
48     copy automatically has all attachments the original object had. The perl
49     variables get copied in a shallow way (references are shared between
50     instances). If this is not the behaviour you need, you have to adjust the
51     B<destination> object as you see fit.
52    
53     =head3 destroy (object -- )
54    
55 root 1.23 Invoked when the deliantra object gets destroyed, and only when the object
56 root 1.12 has a handler for this event. This event can occur many times, as its
57     called when the in-memory object is destroyed, not when the object itself
58     dies.
59    
60    
61     =head2 OBJECT EVENTS
62    
63     Object events always relate to a specific object, which is always the
64     first argument. Not all events get generated for every object, some are
65     specific to an object type.
66 pippijn 1.1
67 root 1.20 =head3 add_bonus (item creator difficulty max_magic flags -- )
68 root 1.6
69     A basic item has been created (e.g. for shops, monsters drops etc.)
70     that needs bonus values applied. The B<creator> object is a template
71     object that can be used to inherit stuff (and can be NULL). Flags is a
72     combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP
73     on item or set its value to 0) or GT_MINIMAL (???)
74    
75     When overriden, built-in bonus generation is skipped, otherwise
76     treasure generation continues as it would without this hook.
77    
78     In general, if flags != 0 or creator != 0 you should just return and leave
79     item generation to the standard code.
80    
81 root 1.12 =head3 remove (object -- )
82    
83     Invoked before the object is removed from its environment.
84    
85     =head3 insert (object -- )
86 pippijn 1.1
87 root 1.12 Called after the object was inserted into a container or map.
88 pippijn 1.1
89 root 1.12 =head3 tick (object -- )
90 pippijn 1.1
91     Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
92     during ticks should an objetc process any movement or other events.
93    
94     =head3 kill (object hitter -- )
95    
96 root 1.25 Invoked whenever an object was killed (hp < 0 caused by an attack) and is
97     about to get removed. Overriding processing will skip removal, but to do
98     this successfully you have to keep the object from dieing, otherwise the
99     event gets invoked again and again.
100 pippijn 1.1
101     =head3 apply (object who -- applytype)
102    
103     Invoked whenever the object is being applied in some way. The applytype is one of:
104    
105     =over 4
106    
107     =item B<0> player or monster can't apply objects of that type
108    
109     =item B<1> has been applied, or there was an error applying the object
110    
111     =item B<2> objects of that type can't be applied if not in inventory
112    
113     =back
114    
115     =head3 throw (object thrower)
116    
117     Invoked when an B<object> is thrown by B<thrower>.
118    
119     =head3 stop (object -- )
120    
121     Invoked when a thrown B<object> (arrow, other stuff) hits something and is
122     thus being "stopped".
123    
124     =head3 can_apply (who object -- reason)
125    
126     =head3 can_be_applied (object who -- reason)
127    
128     Check wether the B<object> can be applied/readied/etc. by the
129     object B<who> and return reason otherwise. Reason is a bitset composed of
130     C<CAN_APPLY_*>-flags.
131    
132     =head3 be_ready (object who -- success)
133    
134     =head3 ready (who object -- success)
135    
136     Invoked whenever an B<object> is being applied by object B<who>. See
137     I<can_apply> for an alternative if you just want to check wether something
138     can apply an object.
139    
140     =head3 be_unready (object who -- deleted)
141    
142     =head3 unready (who object -- deleted)
143    
144     Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
145     currently applied by B<who>. If your override, make sure you give 'who'
146     (if it is a player) an indication of whats wrong. Must return true if the
147     object was freed.
148    
149 root 1.19 =head3 use_skill (skill who part direction stringarg -- )
150 pippijn 1.1
151     Invoked whenever a skill is used by somebody or something.
152    
153 root 1.19 =head3 cast_spell (spell owner casting_object direction stringarg -- )
154 pippijn 1.1
155     Invoked whenever a given spell is cast by B<casting_object> (used by
156     B<owner>).
157    
158     =head3 drop (object who -- )
159    
160     Invoked whenever an item gets dropped by somebody, e.g. as a result of a
161     drop command.
162    
163     =head3 drop_on (floor object who -- )
164    
165     Invoked whenever some B<object> is being dropped on the B<floor> object.
166    
167     =head3 say (object player message)
168    
169     Invoked whenever the I<object> can hear a B<message> being said by
170     B<player> in its vicinity.
171    
172     =head3 monster_move (monster enemy -- )
173    
174     Invoked whenever the B<monster> tries to move, just after B<enemy> and
175     other parameters have been determined, but before movement is actually
176     executed.
177    
178     =head3 attack (object hitter -- damage)
179    
180     Object gets attacked by somebody - when overriden, should return the
181     damage that has been dealt.
182    
183     =head3 skill_attack (attacker victim message skill -- success)
184    
185     Invoked whenever an B<attacker> attacks B<victim> using a B<skill> (skill
186     cna be C<undef>). B<message> is the message that describes the attack when
187     damage is done.
188    
189     =head3 weapon_attack (weapon hitter victim)
190    
191     Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
192     B<victim>.
193    
194     =head3 inscribe_note (book pl message skill -- )
195    
196     Used whenever a book gets inscribed with a message.
197    
198     =head3 trigger (object who -- )
199    
200     Invoked whenever a lever-like B<object> has been activated/triggered in some
201     (manual) way.
202    
203     =head3 move_trigger (object victim originator -- )
204    
205     Invoked whenever a trap-like B<object> has been activated, usually by
206     moving onto it. This includes not just traps, but also buttons, holes,
207     signs and similar stuff.
208    
209 root 1.15 =head3 open (container who -- )
210    
211     Invoked whenever a container gets opened. When overriden, the container will not
212     get opened, but you must tell op about the reason.
213    
214 pippijn 1.1 =head3 close (container who -- )
215    
216 root 1.15 Invoked whenever a container gets closed. When overriden, the container
217     will not get closed, but you must tell op about the reason. This event
218     is not crash-safe, i.e. containers might be closed due to a server crash
219     without this event being invoked.
220 pippijn 1.1
221    
222     =head2 GLOBAL EVENTS
223    
224     Global events have no relation to specific objects.
225    
226 root 1.3 =head3 cleanup ()
227    
228     Called when the server is cleaning up, just before it calls exit.
229    
230 root 1.24 =head3 clock ()
231 pippijn 1.1
232     Is invoked on every server tick, usually every 0.12 seconds.
233    
234 root 1.24 =head3 resource_update ()
235    
236     Is invoked after each time the server reloads its resources, which is
237     usually one of the earliest things it does when starting up.
238    
239 root 1.3
240 pippijn 1.1 =head2 PLAYER EVENTS
241    
242     Player events always have a player object as first argument.
243    
244     =head3 birth (player)
245    
246     Invoked as very first thing after creating a player.
247    
248     =head3 quit (player)
249    
250     Invoked wheneever a player quits, before actually removing him/her.
251    
252     =head3 kick (player params -- )
253    
254 root 1.14 Invoked when the given player is being kicked, before the kick is
255     executed.
256 pippijn 1.1
257 root 1.14 =head3 load (player -- )
258 pippijn 1.1
259     Invoked whenever a player has been loaded from disk, but before
260     actual login.
261    
262 root 1.14 =head3 save (player -- )
263 pippijn 1.1
264 root 1.14 Invoked just before a player gets serialised.
265 pippijn 1.1
266 root 1.14 =head3 save_done (player -- )
267 root 1.13
268 root 1.14 Invoked just after a player was serialised.
269 root 1.13
270     =head3 connect (player -- )
271    
272     Invoked just after the player object was connected to a client.
273    
274     =head3 disconnect (player -- )
275    
276     Invoked just before the player gets disconnected from the client.
277    
278 pippijn 1.1 =head3 login (player)
279    
280     Invoked whenever a player logs in.
281    
282 root 1.21 =head3 logout (player cleanly -- )
283 pippijn 1.1
284     Invoked whenever a player logs out, gets disconnected etc.
285    
286     =head3 death (player)
287    
288     Invoked whenever a player dies, before the death actually gets processed.
289    
290 root 1.4 =head3 map_change (player newmap x y -- )
291 pippijn 1.1
292 root 1.4 Invoked before a player moves from one map to another, can override the movement.
293 pippijn 1.1
294 root 1.22 =head3 region_change (player newregion oldregion -- )
295    
296     Invoked when a player entered a new region. Cannot be overriden.
297    
298 root 1.7 =head3 command (player command args -- time)
299    
300     Execute a user command send by the client. Programmable plug-ins usually
301     handle this event internally.
302    
303 pippijn 1.1 =head3 extcmd (player string)
304    
305 root 1.7 Invoked whenever a client issues the C<extcmd> protocol command.
306     Programmable plug-ins usually handle this event internally.
307 pippijn 1.1
308     =head3 move (player direction -- )
309    
310 root 1.18 Called whenever the player is supposed to move or attack. The handler
311     must handle the cases of speed_left or weapon_sp_left being negative,
312     fire being on, is responsible for decreaseing the speed_left value
313     on successful moves etc. etc.. When overriden, must return a boolean
314     indicating wether a move could be effected.
315    
316 pippijn 1.1 =head3 pray_altar (player altar skill -- )
317    
318     Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
319    
320     =head3 tell (player name message -- )
321    
322     Invoked whenever the player uses the B<tell> or B<reply> command, before
323     it gets processed.
324    
325 pippijn 1.16 =head3 told (player player message -- )
326    
327     Invoked right before a message is being told to a player using B<tell> or
328     B<reply>.
329    
330 pippijn 1.1 =head3 say (player message --)
331    
332     =head3 chat (player message --)
333    
334     =head3 shout (player message --)
335    
336     Invoked whenever the player uses the B<say>, B<chat> or B<shout> command,
337     before it gets processed.
338    
339    
340     =head2 MAP EVENTS
341    
342     These events are generally dependent on a map and thus all have a map
343     as first argument.
344    
345     =head3 instantiate (map)
346    
347     Original B<map> has been loaded (e.g. on first use, or after a map
348     reset).
349    
350     =head3 swapin (map)
351    
352     Invoked when a previously swapped-out temporary B<map> has been loaded again.
353    
354     =head3 swapout (map)
355    
356     Invoked after a B<map> has been swapped out to disk.
357    
358     =head3 reset (map)
359    
360     Invoked when a B<map> gets reset.
361    
362     =head3 clean (map)
363    
364     Invoked when a temporary B<map> gets deleted on-disk.
365    
366 root 1.4 =head3 enter (map player x y -- )
367 pippijn 1.1
368 root 1.4 Invoked whenever a player tries to enter the B<map>, while he/she is still
369 root 1.5 on the old map. Overriding means the player won't be able to enter, and,
370     if newmap/x/y are given, will be redirected to that map instead.
371 pippijn 1.1
372 root 1.4 =head3 leave (map player -- )
373 pippijn 1.1
374 root 1.4 Invoked whenever a player tries to leave the B<map>. Overriding means the
375     player won't be able to leave.
376 pippijn 1.1
377 root 1.9 =head3 trigger (map connection state -- )
378 pippijn 1.1
379     Invoked whenever something activates a B<connection> on the B<map>. If B<state>
380     is true the connection was 'state' and if false it is 'released'.
381 root 1.5
382 root 1.8
383     =head2 CLIENT EVENTS
384    
385     These events are very similar to player events, but they are might be
386     handled asynchronously as soon as the command reaches the server, even when
387     the player hasn't logged in yet (meaning there is no player yet).
388    
389 root 1.9 =head3 connect (client -- )
390    
391     Called as soon as a new connection to the server is established. Should
392     not be overriden.
393    
394 root 1.17 =head3 setup (client string -- )
395    
396     Client sent the setup command to negotiate parameters. Handling is
397     mandatory and done by F<login.ext>.
398    
399 root 1.9 =head3 addme (client -- )
400    
401 root 1.17 The client sent an addme, thus ending the initial handshaking. Handling is mandatory
402     and done by F<login.ext>.
403 root 1.9
404 root 1.10 =head3 reply (client replystring -- )
405    
406     Called when the client submits a reply in the ST_CUSTOM state. Usually
407     handled internally by language plugins.
408    
409 root 1.9 =head3 exticmd (client string -- )
410 root 1.8
411     Like C<extcmd>, but can be called before a player has logged in.
412    
413     Programmable plug-ins usually handle this event internally.
414