server/doc/events.pod

=head1 CROSSFIRE PLUG-IN EVENTS

This document briefly describes each plug-in event. It is also used to
generate the event-list itself, so is always complete. Be careful wehn
changing it, though.

=head2 NOTATION

the event description below uses a variant of the forth stack notation -
an opening parenthesis followed by the type of each parameter, optionally
followed by two dashes and the returning parameters. If the latter is
missing, the event will be called but cannot change wether the event gets
processed.

If it is specified (even if no return values are supported), a plug-in
can override (e.g. using C<cf::override> in Perl) event processing,
basically short-circuiting it. For example, if you override from within a
player BIRTH event, nothing much will happen with respect to the built-in
processing, but if you override from within a player TELL event, the tell
will be ignored (presumably your plug-in took care of it).


=head2 GLOBAL EVENTS

Global events have no relation to specific objects.

=head3 CLOCK ( )

Is invoked on every server tick, usually every 0.12 seconds.


=head2 PLAYER EVENTS

Player events always have a player object as first argument.

=head3 REATTACH (player)

Called whenever attachments/plug-ins need to get reattached to the player
object. This usually happens when the player gets loaded from disk, or
when the server is reloaded.

=head3 BIRTH (player)

Called as very first thing after creating a player.

=head3 QUIT (player)

Called wheneever a player quits, before actually removing him/her.

=head3 LOAD (player)

Called whenever a player has been loaded from disk, but before
actual login.

=head3 SAVE (player)

Called just before a player gets saved.

=head3 LOGIN (player)

Called whenever a player logs in.

=head3 LOGOUT (player)

Called whenever a player logs out, gets disconnected etc.

=head3 DEATH (player)

Called whenever a player dies, before the death actually gets processed.

=head3 MAP_CHANGE (player oldmap newmap)

Called whenever a player moves from one map to another.

=head3 EXTCMD (player string)

Called whenever a client issues the C<extcmd> protocol command. It's
argument is passed without any changes.

=head3 PRAY_ALTAR (player altar skill -- )

Called whenever the B<player> prays over an B<altar>, using the given B<skill>.

=head3 TELL (player -- )

Called whenever the player uses the B<tell> command, before it gets processed.

=head3 SAY (player --)

Called whenever the player uses the B<say> command, before it gets processed.

=head3 SHOUT (player --)

Called whenever the player uses the B<shout> command, before it gets processed.


=head2 OBJECT EVENTS

Object events always relate to a specific object, which is always the
first argument. Not all events get generated for every object, some are
specific to an object type.

=head3 INSTANTIATE (object init-args...)

An archetype was instantiated into an object. This event occurs when
a map is loaded for the first time, or when the object was created
dynamically. The arguments are as specified in the C<attach> attribute of
the object or archetype.

This is useful to initialise any per-object state you might need.

=head3 REATTACH (object)

Called whenever attachments/plug-ins need to get reattached to the
object. This usually happens when it was loaded from disk, or when the
server was reloaded. This event will only be generated if the object has
attachments.

=head3 CLONE (object destination)

An object with _attached extension_ is cloned, that is, a copy was
made. The copy automatically has all attachments the original object
had. The perl variables get copied in a shallow way (references are shared
between instances). If this is not the behaviour you need, you have to
adjust the B<destination> object as you see fit.

=head3 TICK (object)

Called whenever the object "ticks", i.e. has positive B<speed_left>. Only
during ticks should an objetc process any movement or other events.

=head3 KILL (object hitter -- )

Called whenever an object is dead and about to get removed. Overriding
processing will skip removal, but to do this successfully you have to
objetc from dieing, otherwise the event gets invoked again and again.

=head3 APPLY (object who -- applytype)

Called whenever the object is being applied in some way. The applytype is one of:

=over 4

=item B<0> player or monster can't apply objects of that type

=item B<1> has been applied, or there was an error applying the object

=item B<2> objects of that type can't be applied if not in inventory

=cut

=head3 USE_SKILL (skill who part direction strignarg -- )

Called whenever a skill is used by somebody or something.

=head3 CAST_SPELL (spell casting_object owner direction stringarg -- )

Called whenever a given spell is cast by B<casting_oject> (used by
B<owner>).

=head3 DROP (object who -- )

Called whenever an item gets dropped by somebody, e.g. as a result of a
drop command.

=head3 DROP_ON (floor object who -- )

Called whenever some B<object> is being dropped on the B<floor> object.

=head3 LISTEN

Called whenever the object can hear something beign said in its
vicinity. Not yet implemented.

=head3 MOVE (monster enemy -- )

Called whenever the B<monster> tries to move, just after B<enemy> and
other parameters have been determined, but before movement is actually
executed.

=head3 ATTACK (object hitter -- damage)

Object gets attacked by somebody - when overriden, should return the
damage that has been dealt.

=head3 ATTACKS (weapon hitter victim)

Called whenever an object is used as a B<weapon> by B<hitter> to attack
B<victim>.

=head3 INSCRIBE_NOTE (book pl message skill -- )

Used whenever a book gets inscribed with a message.

=head3 TRIGGER (object who -- )

Called whenever a lever-like B<object> has been activated/triggered in some
(manual) way.

=head3 MOVE_TRIGGER (object victim originator -- )

Called whenever a trap-like B<object> has been activated, usually by
moving onto it. This includes not just traps, but also buttons, holes,
signs and similar stuff.

=head3 CLOSE (container -- )

Called whenever a container gets closed (this event is not yet reliable!).


=head2 MAP EVENTS

These events are generally dependent on a map and thus all have a map
as first argument.

=head3 REATTACH (map)

Called whenever attachments/plug-ins need to get reattached to the
B<map>. This usually happens when the map was loaded from disk, or when the
server was reloaded.

=head3 LOAD (map)

Original B<map> has been loaded (e.g. on first use, or after a map
reset). This event might get renamed to instantiate in the future.

=head3 SWAPIN (map)

Called when a previously swapped-out temporary B<map> has been loaded again.

=head3 SWAPOUT (map)

Called after a B<map> has been swapped out to disk.

=head3 RESET (map)

Called when a B<map> gets reset.

=head3 CLEAN (map)

Called when a temporary B<map> gets deleted on-disk.

=head3 ENTER (map player)

Called whenever a player enters the B<map>. This event is likely unreliable.

=head3 LEAVE (map player)

Called whenever a player leaves the B<map>. This event is likely unreliable.

=head3 UPGRADE (map)

(TEMPORARY EVENT) gets called whenever a old-style map has been upgraded.

Revision:	1.1
Committed:	Mon Aug 28 08:34:28 2006 UTC (17 years, 8 months ago) by root
Branch:	MAIN
Log Message:	first take of event documentation
#	Content
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