1 | =head1 CROSSFIRE PLUG-IN EVENTS |
1 | =head1 CROSSFIRE+ PLUG-IN EVENTS |
2 | |
2 | |
3 | This document briefly describes each plug-in event. It is also used to |
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 |
4 | generate the event-list itself, so is always complete. Be careful wehn |
5 | changing it, though. |
5 | changing it, though. |
6 | |
6 | |
… | |
… | |
48 | made. The copy automatically has all attachments the original object |
48 | made. The copy automatically has all attachments the original object |
49 | had. The perl variables get copied in a shallow way (references are shared |
49 | had. The perl variables get copied in a shallow way (references are shared |
50 | between instances). If this is not the behaviour you need, you have to |
50 | between instances). If this is not the behaviour you need, you have to |
51 | adjust the B<destination> object as you see fit. |
51 | adjust the B<destination> object as you see fit. |
52 | |
52 | |
|
|
53 | =head3 add_bonus (item creator difficulty max_magic flags) |
|
|
54 | |
|
|
55 | A basic item has been created (e.g. for shops, monsters drops etc.) |
|
|
56 | that needs bonus values applied. The B<creator> object is a template |
|
|
57 | object that can be used to inherit stuff (and can be NULL). Flags is a |
|
|
58 | combination of GT_ENVIRONMENT (???) or GT_STARTEQUIP (set FLAG_STARTEQUIP |
|
|
59 | on item or set its value to 0) or GT_MINIMAL (???) |
|
|
60 | |
|
|
61 | When overriden, built-in bonus generation is skipped, otherwise |
|
|
62 | treasure generation continues as it would without this hook. |
|
|
63 | |
|
|
64 | In general, if flags != 0 or creator != 0 you should just return and leave |
|
|
65 | item generation to the standard code. |
|
|
66 | |
53 | =head3 destroy (object) |
67 | =head3 destroy (object) |
54 | |
68 | |
55 | Invoked when the crossfire object gets destroyed, and only when the object |
69 | Invoked when the crossfire object gets destroyed, and only when the object |
56 | has a handler for this event. This event can occur many times, as its |
70 | 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 |
71 | called when the in-memory object is destroyed, not when the object itself |
… | |
… | |
183 | |
197 | |
184 | =head2 GLOBAL EVENTS |
198 | =head2 GLOBAL EVENTS |
185 | |
199 | |
186 | Global events have no relation to specific objects. |
200 | Global events have no relation to specific objects. |
187 | |
201 | |
|
|
202 | =head3 cleanup () |
|
|
203 | |
|
|
204 | Called when the server is cleaning up, just before it calls exit. |
|
|
205 | |
188 | =head3 clock ( ) |
206 | =head3 clock ( ) |
189 | |
207 | |
190 | Is invoked on every server tick, usually every 0.12 seconds. |
208 | Is invoked on every server tick, usually every 0.12 seconds. |
|
|
209 | |
191 | |
210 | |
192 | =head2 PLAYER EVENTS |
211 | =head2 PLAYER EVENTS |
193 | |
212 | |
194 | Player events always have a player object as first argument. |
213 | Player events always have a player object as first argument. |
195 | |
214 | |
… | |
… | |
230 | |
249 | |
231 | =head3 death (player) |
250 | =head3 death (player) |
232 | |
251 | |
233 | Invoked whenever a player dies, before the death actually gets processed. |
252 | Invoked whenever a player dies, before the death actually gets processed. |
234 | |
253 | |
235 | =head3 map_change (player oldmap newmap) |
254 | =head3 map_change (player newmap x y -- ) |
236 | |
255 | |
237 | Invoked whenever a player moves from one map to another. |
256 | Invoked before a player moves from one map to another, can override the movement. |
|
|
257 | |
|
|
258 | =head3 command (player command args -- time) |
|
|
259 | |
|
|
260 | Execute a user command send by the client. Programmable plug-ins usually |
|
|
261 | handle this event internally. |
238 | |
262 | |
239 | =head3 extcmd (player string) |
263 | =head3 extcmd (player string) |
240 | |
264 | |
241 | Invoked whenever a client issues the C<extcmd> protocol command. It's |
265 | Invoked whenever a client issues the C<extcmd> protocol command. |
242 | argument is passed without any changes. |
266 | Programmable plug-ins usually handle this event internally. |
243 | |
267 | |
244 | =head3 move (player direction -- ) |
268 | =head3 move (player direction -- ) |
245 | |
269 | |
246 | =head3 pray_altar (player altar skill -- ) |
270 | =head3 pray_altar (player altar skill -- ) |
247 | |
271 | |
… | |
… | |
299 | |
323 | |
300 | =head3 clean (map) |
324 | =head3 clean (map) |
301 | |
325 | |
302 | Invoked when a temporary B<map> gets deleted on-disk. |
326 | Invoked when a temporary B<map> gets deleted on-disk. |
303 | |
327 | |
304 | =head3 enter (map player) |
328 | =head3 enter (map player x y -- ) |
305 | |
329 | |
306 | Invoked whenever a player enters the B<map>. This event is likely unreliable. |
330 | Invoked whenever a player tries to enter the B<map>, while he/she is still |
|
|
331 | on the old map. Overriding means the player won't be able to enter, and, |
|
|
332 | if newmap/x/y are given, will be redirected to that map instead. |
307 | |
333 | |
308 | =head3 leave (map player) |
334 | =head3 leave (map player -- ) |
309 | |
335 | |
310 | Invoked whenever a player leaves the B<map>. This event is likely unreliable. |
336 | Invoked whenever a player tries to leave the B<map>. Overriding means the |
|
|
337 | player won't be able to leave. |
311 | |
338 | |
312 | =head3 upgrade (map) |
|
|
313 | |
|
|
314 | (TEMPORARY EVENT) gets invoked whenever a old-style map has been upgraded. |
|
|
315 | |
|
|
316 | =head3 trigger (map connection state) |
339 | =head3 trigger (map connection state -- ) |
317 | |
340 | |
318 | Invoked whenever something activates a B<connection> on the B<map>. If B<state> |
341 | Invoked whenever something activates a B<connection> on the B<map>. If B<state> |
319 | is true the connection was 'state' and if false it is 'released'. |
342 | is true the connection was 'state' and if false it is 'released'. |
|
|
343 | |
|
|
344 | |
|
|
345 | =head2 CLIENT EVENTS |
|
|
346 | |
|
|
347 | These events are very similar to player events, but they are might be |
|
|
348 | handled asynchronously as soon as the command reaches the server, even when |
|
|
349 | the player hasn't logged in yet (meaning there is no player yet). |
|
|
350 | |
|
|
351 | =head3 connect (client -- ) |
|
|
352 | |
|
|
353 | Called as soon as a new connection to the server is established. Should |
|
|
354 | not be overriden. |
|
|
355 | |
|
|
356 | =head3 addme (client -- ) |
|
|
357 | |
|
|
358 | The client sent an addme, thus ending the initial handshaking. If overriden, the server |
|
|
359 | will not send any response. |
|
|
360 | |
|
|
361 | =head3 reattach (client -- ) |
|
|
362 | |
|
|
363 | Invoked whenever attachments/plug-ins need to get reattached to the |
|
|
364 | object. This usually happens when server was reloaded. This event will |
|
|
365 | only be generated if the object has attachments. |
|
|
366 | |
|
|
367 | =head3 exticmd (client string -- ) |
|
|
368 | |
|
|
369 | Like C<extcmd>, but can be called before a player has logged in. |
|
|
370 | |
|
|
371 | Programmable plug-ins usually handle this event internally. |
|
|
372 | |