ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/deliantra/server/doc/events.pod
(Generate patch)

Comparing deliantra/server/doc/events.pod (file contents):
Revision 1.1 by root, Mon Aug 28 08:34:28 2006 UTC vs.
Revision 1.8 by root, Tue Aug 29 07:54:36 2006 UTC

… …
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 is
12missing, the event will be called 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 15If it is specified (even if no return values are supported), a plug-in
16can override (e.g. using C<cf::override> in Perl) event processing, 16can override (e.g. using C<cf::override> in Perl) event processing,
17basically short-circuiting it. For example, if you override from within a 17basically short-circuiting it. For example, if you override from within a
18player BIRTH event, nothing much will happen with respect to the built-in 18player BIRTH event, nothing much will happen with respect to the built-in
19processing, but if you override from within a player TELL event, the tell 19processing, but if you override from within a player TELL event, the tell
20will be ignored (presumably your plug-in took care of it). 20will be ignored (presumably your plug-in took care of it).
21 21
22 22
23=head2 GLOBAL EVENTS
24
25Global events have no relation to specific objects.
26
27=head3 CLOCK ( )
28
29Is invoked on every server tick, usually every 0.12 seconds.
30
31
32=head2 PLAYER EVENTS
33
34Player events always have a player object as first argument.
35
36=head3 REATTACH (player)
37
38Called whenever attachments/plug-ins need to get reattached to the player
39object. This usually happens when the player gets loaded from disk, or
40when the server is reloaded.
41
42=head3 BIRTH (player)
43
44Called as very first thing after creating a player.
45
46=head3 QUIT (player)
47
48Called wheneever a player quits, before actually removing him/her.
49
50=head3 LOAD (player)
51
52Called whenever a player has been loaded from disk, but before
53actual login.
54
55=head3 SAVE (player)
56
57Called just before a player gets saved.
58
59=head3 LOGIN (player)
60
61Called whenever a player logs in.
62
63=head3 LOGOUT (player)
64
65Called whenever a player logs out, gets disconnected etc.
66
67=head3 DEATH (player)
68
69Called whenever a player dies, before the death actually gets processed.
70
71=head3 MAP_CHANGE (player oldmap newmap)
72
73Called whenever a player moves from one map to another.
74
75=head3 EXTCMD (player string)
76
77Called whenever a client issues the C<extcmd> protocol command. It's
78argument is passed without any changes.
79
80=head3 PRAY_ALTAR (player altar skill -- )
81
82Called whenever the B<player> prays over an B<altar>, using the given B<skill>.
83
84=head3 TELL (player -- )
85
86Called whenever the player uses the B<tell> command, before it gets processed.
87
88=head3 SAY (player --)
89
90Called whenever the player uses the B<say> command, before it gets processed.
91
92=head3 SHOUT (player --)
93
94Called whenever the player uses the B<shout> command, before it gets processed.
95
96
97=head2 OBJECT EVENTS 23=head2 OBJECT EVENTS
98 24
99Object events always relate to a specific object, which is always the 25Object events always relate to a specific object, which is always the
100first argument. Not all events get generated for every object, some are 26first argument. Not all events get generated for every object, some are
101specific to an object type. 27specific to an object type.
102 28
103=head3 INSTANTIATE (object init-args...) 29=head3 instantiate (object init-args...)
104 30
105An archetype was instantiated into an object. This event occurs when 31An archetype was instantiated into an object. This event occurs when
106a map is loaded for the first time, or when the object was created 32a map is loaded for the first time, or when the object was created
107dynamically. The arguments are as specified in the C<attach> attribute of 33dynamically. The arguments are as specified in the C<attach> attribute of
108the object or archetype. 34the object or archetype.
109 35
110This is useful to initialise any per-object state you might need. 36This is useful to initialise any per-object state you might need.
111 37
112=head3 REATTACH (object) 38=head3 reattach (object)
113 39
114Called whenever attachments/plug-ins need to get reattached to the 40Invoked whenever attachments/plug-ins need to get reattached to the
115object. This usually happens when it was loaded from disk, or when the 41object. This usually happens when it was loaded from disk, or when the
116server was reloaded. This event will only be generated if the object has 42server was reloaded. This event will only be generated if the object has
117attachments. 43attachments.
118 44
119=head3 CLONE (object destination) 45=head3 clone (object destination)
120 46
121An object with _attached extension_ is cloned, that is, a copy was 47An object with _attached extension_ is cloned, that is, a copy was
122made. The copy automatically has all attachments the original object 48made. The copy automatically has all attachments the original object
123had. The perl variables get copied in a shallow way (references are shared 49had. The perl variables get copied in a shallow way (references are shared
124between instances). If this is not the behaviour you need, you have to 50between instances). If this is not the behaviour you need, you have to
125adjust the B<destination> object as you see fit. 51adjust the B<destination> object as you see fit.
126 52
53=head3 destroy (object)
54
55Invoked when the crossfire object gets destroyed, and only when the object
56has 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
58dies.
59
127=head3 TICK (object) 60=head3 tick (object)
128 61
129Called whenever the object "ticks", i.e. has positive B<speed_left>. Only 62Invoked whenever the object "ticks", i.e. has positive B<speed_left>. Only
130during ticks should an objetc process any movement or other events. 63during ticks should an objetc process any movement or other events.
131 64
132=head3 KILL (object hitter -- ) 65=head3 kill (object hitter -- )
133 66
134Called whenever an object is dead and about to get removed. Overriding 67Invoked whenever an object is dead and about to get removed. Overriding
135processing will skip removal, but to do this successfully you have to 68processing will skip removal, but to do this successfully you have to
136objetc from dieing, otherwise the event gets invoked again and again. 69objetc from dieing, otherwise the event gets invoked again and again.
137 70
138=head3 APPLY (object who -- applytype) 71=head3 apply (object who -- applytype)
139 72
140Called whenever the object is being applied in some way. The applytype is one of: 73Invoked whenever the object is being applied in some way. The applytype is one of:
141 74
142=over 4 75=over 4
143 76
144=item B<0> player or monster can't apply objects of that type 77=item B<0> player or monster can't apply objects of that type
145 78
146=item B<1> has been applied, or there was an error applying the object 79=item B<1> has been applied, or there was an error applying the object
147 80
148=item B<2> objects of that type can't be applied if not in inventory 81=item B<2> objects of that type can't be applied if not in inventory
149 82
150=cut 83=back
151 84
85=head3 throw (object thrower)
86
87Invoked when an B<object> is thrown by B<thrower>.
88
89=head3 stop (object -- )
90
91Invoked when a thrown B<object> (arrow, other stuff) hits something and is
92thus being "stopped".
93
94=head3 can_apply (who object -- reason)
95
96=head3 can_be_applied (object who -- reason)
97
98Check wether the B<object> can be applied/readied/etc. by the
99object B<who> and return reason otherwise. Reason is a bitset composed of
100C<CAN_APPLY_*>-flags.
101
102=head3 be_ready (object who -- success)
103
104=head3 ready (who object -- success)
105
106Invoked whenever an B<object> is being applied by object B<who>. See
107I<can_apply> for an alternative if you just want to check wether something
108can apply an object.
109
110=head3 be_unready (object who -- deleted)
111
112=head3 unready (who object -- deleted)
113
114Unwield/unapply/unready the given spell/weapon/skill/etc. B<object>,
115currently 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
117object was freed.
118
152=head3 USE_SKILL (skill who part direction strignarg -- ) 119=head3 use_skill (skill who part direction strignarg -- )
153 120
154Called whenever a skill is used by somebody or something. 121Invoked whenever a skill is used by somebody or something.
155 122
156=head3 CAST_SPELL (spell casting_object owner direction stringarg -- ) 123=head3 cast_spell (spell casting_object owner direction stringarg -- )
157 124
158Called whenever a given spell is cast by B<casting_oject> (used by 125Invoked whenever a given spell is cast by B<casting_object> (used by
159B<owner>). 126B<owner>).
160 127
161=head3 DROP (object who -- ) 128=head3 drop (object who -- )
162 129
163Called whenever an item gets dropped by somebody, e.g. as a result of a 130Invoked whenever an item gets dropped by somebody, e.g. as a result of a
164drop command. 131drop command.
165 132
166=head3 DROP_ON (floor object who -- ) 133=head3 drop_on (floor object who -- )
167 134
168Called whenever some B<object> is being dropped on the B<floor> object. 135Invoked whenever some B<object> is being dropped on the B<floor> object.
169 136
170=head3 LISTEN 137=head3 say (object player message)
171 138
172Called whenever the object can hear something beign said in its 139Invoked whenever the I<object> can hear a B<message> being said by
173vicinity. Not yet implemented. 140B<player> in its vicinity.
174 141
175=head3 MOVE (monster enemy -- ) 142=head3 move (monster enemy -- )
176 143
177Called whenever the B<monster> tries to move, just after B<enemy> and 144Invoked whenever the B<monster> tries to move, just after B<enemy> and
178other parameters have been determined, but before movement is actually 145other parameters have been determined, but before movement is actually
179executed. 146executed.
180 147
181=head3 ATTACK (object hitter -- damage) 148=head3 attack (object hitter -- damage)
182 149
183Object gets attacked by somebody - when overriden, should return the 150Object gets attacked by somebody - when overriden, should return the
184damage that has been dealt. 151damage that has been dealt.
185 152
186=head3 ATTACKS (weapon hitter victim) 153=head3 attacks (weapon hitter victim)
187 154
188Called whenever an object is used as a B<weapon> by B<hitter> to attack 155Invoked whenever an object is used as a B<weapon> by B<hitter> to attack
189B<victim>. 156B<victim>.
190 157
191=head3 INSCRIBE_NOTE (book pl message skill -- ) 158=head3 inscribe_note (book pl message skill -- )
192 159
193Used whenever a book gets inscribed with a message. 160Used whenever a book gets inscribed with a message.
194 161
195=head3 TRIGGER (object who -- ) 162=head3 trigger (object who -- )
196 163
197Called whenever a lever-like B<object> has been activated/triggered in some 164Invoked whenever a lever-like B<object> has been activated/triggered in some
198(manual) way. 165(manual) way.
199 166
200=head3 MOVE_TRIGGER (object victim originator -- ) 167=head3 move_trigger (object victim originator -- )
201 168
202Called whenever a trap-like B<object> has been activated, usually by 169Invoked whenever a trap-like B<object> has been activated, usually by
203moving onto it. This includes not just traps, but also buttons, holes, 170moving onto it. This includes not just traps, but also buttons, holes,
204signs and similar stuff. 171signs and similar stuff.
205 172
206=head3 CLOSE (container -- ) 173=head3 close (container -- )
207 174
208Called whenever a container gets closed (this event is not yet reliable!). 175Invoked whenever a container gets closed (this event is not yet reliable!).
176
177
178=head2 GLOBAL EVENTS
179
180Global events have no relation to specific objects.
181
182=head3 clock ( )
183
184Is invoked on every server tick, usually every 0.12 seconds.
185
186=head2 PLAYER EVENTS
187
188Player events always have a player object as first argument.
189
190=head3 reattach (player)
191
192Invoked whenever attachments/plug-ins need to get reattached to the player
193object. This usually happens when the player gets loaded from disk, or
194when the server is reloaded.
195
196=head3 birth (player)
197
198Invoked as very first thing after creating a player.
199
200=head3 quit (player)
201
202Invoked wheneever a player quits, before actually removing him/her.
203
204=head3 kick (player params -- )
205
206Invoked when the given plaer is being kicked, before the kick is executed.
207
208=head3 load (player)
209
210Invoked whenever a player has been loaded from disk, but before
211actual login.
212
213=head3 save (player)
214
215Invoked just before a player gets saved.
216
217=head3 login (player)
218
219Invoked whenever a player logs in.
220
221=head3 logout (player)
222
223Invoked whenever a player logs out, gets disconnected etc.
224
225=head3 death (player)
226
227Invoked whenever a player dies, before the death actually gets processed.
228
229=head3 map_change (player oldmap newmap)
230
231Invoked whenever a player moves from one map to another.
232
233=head3 extcmd (player string)
234
235Invoked whenever a client issues the C<extcmd> protocol command. It's
236argument is passed without any changes.
237
238=head3 move (player direction -- )
239
240=head3 pray_altar (player altar skill -- )
241
242Invoked whenever the B<player> prays over an B<altar>, using the given B<skill>.
243
244=head3 tell (player name message -- )
245
246Invoked whenever the player uses the B<tell> or B<reply> command, before
247it gets processed.
248
249=head3 say (player message --)
250
251=head3 chat (player message --)
252
253=head3 shout (player message --)
254
255Invoked whenever the player uses the B<say>, B<chat> or B<shout> command,
256before it gets processed.
209 257
210 258
211=head2 MAP EVENTS 259=head2 MAP EVENTS
212 260
213These events are generally dependent on a map and thus all have a map 261These events are generally dependent on a map and thus all have a map
214as first argument. 262as first argument.
215 263
216=head3 REATTACH (map) 264=head3 instantiate (map)
217 265
266Original B<map> has been loaded (e.g. on first use, or after a map
267reset).
268
269=head3 reattach (map)
270
218Called whenever attachments/plug-ins need to get reattached to the 271Invoked whenever attachments/plug-ins need to get reattached to the
219B<map>. This usually happens when the map was loaded from disk, or when the 272B<map>. This usually happens when the map was loaded from disk, or when the
220server was reloaded. 273server was reloaded.
221 274
222=head3 LOAD (map) 275=head3 destroy (map)
223 276
224Original B<map> has been loaded (e.g. on first use, or after a map 277Invoked when the map object gets destroyed, and only when the map object
225reset). This event might get renamed to instantiate in the future. 278has a handler for this event. This event can occur many times, as its
279called when the in-memory object is destroyed, not when the object itself
280dies.
226 281
227=head3 SWAPIN (map) 282=head3 swapin (map)
228 283
229Called when a previously swapped-out temporary B<map> has been loaded again. 284Invoked when a previously swapped-out temporary B<map> has been loaded again.
230 285
231=head3 SWAPOUT (map) 286=head3 swapout (map)
232 287
233Called after a B<map> has been swapped out to disk. 288Invoked after a B<map> has been swapped out to disk.
234 289
235=head3 RESET (map) 290=head3 reset (map)
236 291
237Called when a B<map> gets reset. 292Invoked when a B<map> gets reset.
238 293
239=head3 CLEAN (map) 294=head3 clean (map)
240 295
241Called when a temporary B<map> gets deleted on-disk. 296Invoked when a temporary B<map> gets deleted on-disk.
242 297
243=head3 ENTER (map player) 298=head3 enter (map player)
244 299
245Called whenever a player enters the B<map>. This event is likely unreliable. 300Invoked whenever a player enters the B<map>. This event is likely unreliable.
246 301
247=head3 LEAVE (map player) 302=head3 leave (map player)
248 303
249Called whenever a player leaves the B<map>. This event is likely unreliable. 304Invoked whenever a player leaves the B<map>. This event is likely unreliable.
250 305
251=head3 UPGRADE (map) 306=head3 upgrade (map)
252 307
253(TEMPORARY EVENT) gets called whenever a old-style map has been upgraded. 308(TEMPORARY EVENT) gets invoked whenever a old-style map has been upgraded.
254 309

Diff Legend

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