ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/deliantra/server/doc/events.pod
Revision: 1.1
Committed: Mon Aug 28 08:34:28 2006 UTC (17 years, 9 months ago) by root
Branch: MAIN
Log Message:
first take of event documentation

File Contents

# User Rev Content
1 root 1.1 =head1 CROSSFIRE PLUG-IN EVENTS
2    
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 called 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     =head2 GLOBAL EVENTS
24    
25     Global events have no relation to specific objects.
26    
27     =head3 CLOCK ( )
28    
29     Is invoked on every server tick, usually every 0.12 seconds.
30    
31    
32     =head2 PLAYER EVENTS
33    
34     Player events always have a player object as first argument.
35    
36     =head3 REATTACH (player)
37    
38     Called whenever attachments/plug-ins need to get reattached to the player
39     object. This usually happens when the player gets loaded from disk, or
40     when the server is reloaded.
41    
42     =head3 BIRTH (player)
43    
44     Called as very first thing after creating a player.
45    
46     =head3 QUIT (player)
47    
48     Called wheneever a player quits, before actually removing him/her.
49    
50     =head3 LOAD (player)
51    
52     Called whenever a player has been loaded from disk, but before
53     actual login.
54    
55     =head3 SAVE (player)
56    
57     Called just before a player gets saved.
58    
59     =head3 LOGIN (player)
60    
61     Called whenever a player logs in.
62    
63     =head3 LOGOUT (player)
64    
65     Called whenever a player logs out, gets disconnected etc.
66    
67     =head3 DEATH (player)
68    
69     Called whenever a player dies, before the death actually gets processed.
70    
71     =head3 MAP_CHANGE (player oldmap newmap)
72    
73     Called whenever a player moves from one map to another.
74    
75     =head3 EXTCMD (player string)
76    
77     Called whenever a client issues the C<extcmd> protocol command. It's
78     argument is passed without any changes.
79    
80     =head3 PRAY_ALTAR (player altar skill -- )
81    
82     Called whenever the B<player> prays over an B<altar>, using the given B<skill>.
83    
84     =head3 TELL (player -- )
85    
86     Called whenever the player uses the B<tell> command, before it gets processed.
87    
88     =head3 SAY (player --)
89    
90     Called whenever the player uses the B<say> command, before it gets processed.
91    
92     =head3 SHOUT (player --)
93    
94     Called whenever the player uses the B<shout> command, before it gets processed.
95    
96    
97     =head2 OBJECT EVENTS
98    
99     Object events always relate to a specific object, which is always the
100     first argument. Not all events get generated for every object, some are
101     specific to an object type.
102    
103     =head3 INSTANTIATE (object init-args...)
104    
105     An archetype was instantiated into an object. This event occurs when
106     a map is loaded for the first time, or when the object was created
107     dynamically. The arguments are as specified in the C<attach> attribute of
108     the object or archetype.
109    
110     This is useful to initialise any per-object state you might need.
111    
112     =head3 REATTACH (object)
113    
114     Called whenever attachments/plug-ins need to get reattached to the
115     object. This usually happens when it was loaded from disk, or when the
116     server was reloaded. This event will only be generated if the object has
117     attachments.
118    
119     =head3 CLONE (object destination)
120    
121     An object with _attached extension_ is cloned, that is, a copy was
122     made. The copy automatically has all attachments the original object
123     had. The perl variables get copied in a shallow way (references are shared
124     between instances). If this is not the behaviour you need, you have to
125     adjust the B<destination> object as you see fit.
126    
127     =head3 TICK (object)
128    
129     Called whenever the object "ticks", i.e. has positive B<speed_left>. Only
130     during ticks should an objetc process any movement or other events.
131    
132     =head3 KILL (object hitter -- )
133    
134     Called whenever an object is dead and about to get removed. Overriding
135     processing will skip removal, but to do this successfully you have to
136     objetc from dieing, otherwise the event gets invoked again and again.
137    
138     =head3 APPLY (object who -- applytype)
139    
140     Called whenever the object is being applied in some way. The applytype is one of:
141    
142     =over 4
143    
144     =item B<0> player or monster can't apply objects of that type
145    
146     =item B<1> has been applied, or there was an error applying the object
147    
148     =item B<2> objects of that type can't be applied if not in inventory
149    
150     =cut
151    
152     =head3 USE_SKILL (skill who part direction strignarg -- )
153    
154     Called whenever a skill is used by somebody or something.
155    
156     =head3 CAST_SPELL (spell casting_object owner direction stringarg -- )
157    
158     Called whenever a given spell is cast by B<casting_oject> (used by
159     B<owner>).
160    
161     =head3 DROP (object who -- )
162    
163     Called whenever an item gets dropped by somebody, e.g. as a result of a
164     drop command.
165    
166     =head3 DROP_ON (floor object who -- )
167    
168     Called whenever some B<object> is being dropped on the B<floor> object.
169    
170     =head3 LISTEN
171    
172     Called whenever the object can hear something beign said in its
173     vicinity. Not yet implemented.
174    
175     =head3 MOVE (monster enemy -- )
176    
177     Called whenever the B<monster> tries to move, just after B<enemy> and
178     other parameters have been determined, but before movement is actually
179     executed.
180    
181     =head3 ATTACK (object hitter -- damage)
182    
183     Object gets attacked by somebody - when overriden, should return the
184     damage that has been dealt.
185    
186     =head3 ATTACKS (weapon hitter victim)
187    
188     Called whenever an object is used as a B<weapon> by B<hitter> to attack
189     B<victim>.
190    
191     =head3 INSCRIBE_NOTE (book pl message skill -- )
192    
193     Used whenever a book gets inscribed with a message.
194    
195     =head3 TRIGGER (object who -- )
196    
197     Called whenever a lever-like B<object> has been activated/triggered in some
198     (manual) way.
199    
200     =head3 MOVE_TRIGGER (object victim originator -- )
201    
202     Called whenever a trap-like B<object> has been activated, usually by
203     moving onto it. This includes not just traps, but also buttons, holes,
204     signs and similar stuff.
205    
206     =head3 CLOSE (container -- )
207    
208     Called whenever a container gets closed (this event is not yet reliable!).
209    
210    
211     =head2 MAP EVENTS
212    
213     These events are generally dependent on a map and thus all have a map
214     as first argument.
215    
216     =head3 REATTACH (map)
217    
218     Called whenever attachments/plug-ins need to get reattached to the
219     B<map>. This usually happens when the map was loaded from disk, or when the
220     server was reloaded.
221    
222     =head3 LOAD (map)
223    
224     Original B<map> has been loaded (e.g. on first use, or after a map
225     reset). This event might get renamed to instantiate in the future.
226    
227     =head3 SWAPIN (map)
228    
229     Called when a previously swapped-out temporary B<map> has been loaded again.
230    
231     =head3 SWAPOUT (map)
232    
233     Called after a B<map> has been swapped out to disk.
234    
235     =head3 RESET (map)
236    
237     Called when a B<map> gets reset.
238    
239     =head3 CLEAN (map)
240    
241     Called when a temporary B<map> gets deleted on-disk.
242    
243     =head3 ENTER (map player)
244    
245     Called whenever a player enters the B<map>. This event is likely unreliable.
246    
247     =head3 LEAVE (map player)
248    
249     Called whenever a player leaves the B<map>. This event is likely unreliable.
250    
251     =head3 UPGRADE (map)
252    
253     (TEMPORARY EVENT) gets called whenever a old-style map has been upgraded.
254