server/pod/objects.pod

=head1 CROSSFIRE+ OBJECT AND INTERNALS DOCUMENTATION

Here is all information about the object types Crossfire+
supports at the moment. This is not a complete documentation (yet)
and browsing the source is still recommended to learn about
the objects that aren't documented here.

This documentation is in a sketchy state. It's mostly
used to collect notes about the internal behaviour of the
objects.

=head2 About archetypes and objects

Field denotes an attribute of an archetype.
This is an example of an archetype:

   Object button_trigger
   name button
   type 30
   face button_sma.111
   anim
   button_sma.111
   button_sma.112
   mina
   is_animated 0
   exp 30
   no_pick 1
   walk_on 1
   walk_off 1
   editable 48
   visibility 50
   weight 1
   end

This archetype has the name 'button_trigger' and the objects that
inherit from this archetype have the name 'button'.

The next field 'type' decides the main behaviour of this archetype.
For a comprehensive list of types see include/define.h. For this case
you might find a line like:

   #define TRIGGER_BUTTON           30

The server internally works with objects that 'inherit' attributes from
an archetype. They have a similar set of attributes.

The following documentation will also document the meaning of code internal
attributes of objects. These attributes are marked as '(internal)' and can't
or shouldn't be set by an archetype. If the internal names differs the
external name (for the archetypes) for the attribute is written behind it.

=head2 Description of generic archetype and object attributes

These are the fields that most of the objects have and/or their
default behaviour.

=over 4

=item name <string>

The name of the object.

=item name_pl <string>

The name of a collection of these objects (the plural of the name).

=item face <facename>

The graphical appearance of this object.

=item invisible <number>

If the <number> is greater than 0 the object is invisible.
For players this field reflects the duration of the invisibility
and is decreased every tick by 1.

For non-player objects this field is not changed by server ticks.

=item speed <numeric>

If this field is greater than MIN_ACTIVE_SPEED (~0.0001) the object is placed
on the active object list and will be processed each tick (see also speed_left!).

If the speed field drops below the MIN_ACTIVE_SPEED the object is removed
from the active object list and it won't experience any processing per tick.

=item speed_left <number>

If this field is greater than 0 and the object is on the
active list (mostly means it's speed is also greater than 0):

   - speed_left is decreased by 1
   - and this object is processed and experiences a server tick.

If the object is on the active list and speed_left is lower or
equal to 0 the absolute value of the speed field is added to speed_left
on the end of the tick.

=item no_drop (0|1)

Sets the flag FLAG_NO_DROP. See the Flags section below.

=item applied (0|1)

Sets the flag FLAG_APPLIED. See the Flags section below.

=item is_used_up (0|1)

Sets the flag FLAG_IS_USED_UP. See Flags section below.

=item editable (more than deprecated)

This field had a special meaning for crossedit, which used parts
of the server code for editing. Wherever you see this attribute being
set in an archetype ignore it and/or remove it. No code interprets this
field anymore.

=back

=head3 Flags

Here are the effects of the flags described.

=over 4

=item FLAG_NO_DROP

An object can't be picked up and dropped.

=item FLAG_APPLIED

This flag mostly states whether this object has been 'applied' by the player.
For objects that are applied by the code or have this flag set in the archetype
it mostly means 'this object is active'.

For example the player adjustments of the hp/sp/grace fields and inheritance
of flags from objects in his inventory is toggled by this flag.

=item FLAG_IS_USED_UP

This flag controls whether an object is 'used up'. If it is set the 'food' field
of the object is decreased by 1 each tick, and if it is lower or equal 0 after tha
it is removed.

If also the flag FLAG_APPLIED is set, the 'duration' field controls whether
this object is removed or not, see the Force type below for the meaning
of the duration field in this context.

If FLAG_APPLIED is not set the object is destroyed.

=back

=head2 Description of type specific attributes

The beginning of the headers of the following subsection
are the server internal names for the objects types, see include/define.h.
The numeric values are maybe not 100% accurate, as the code is a changing
target, please consult include/define.h in doubt :-)

=head3 FORCE - type 114 - Forces

Forces are a very 'thin' type. They don't have much behaviour other than
disappearing after a time and/or affecting the player if they are in his inventory.

Forces only take effect on the player if they have set FLAG_APPLIED.

Whether the duration field is processed or not a tick is controlled via the
speed and speed_left field. Look above at the generic description of these
fields.

=over 4

=item duration

While this field is greater than 0 the force/object is not destroyed.
It is decreased each tick by 1.

If it reaches 0 the force/object is destroyed.

This field can have this meaning for B<any> object if that object has
FLAG_IS_USED_UP and FLAG_APPLIED set. See the description of FLAG_IS_USED_UP
what happens then.

=back

=head3 WEAPON - type 15 - Weapons

This type is for general hack and slash weapons like swords, maces
and daggers and and ....

=over 4

=item weapontype <type id>

decides what attackmessages are generated, see include/define.h

=item attacktype <bitmask>

bitfield which decides the attacktype of the damage, see include/attackinc.h

=item dam <number>

amount of damage being done with the attacktype

=item item_power <level>

the itempower of this weapon.

=item name

the name of the weapon.

=item level (internal)

The improvement state of the weapon.
If this field is greater than 0 the 'name' field starts with the
characters name who improved this weapon.

=item last_eat (internal)

seems to be the amount of improvements of a weapon,
the formular for equipping a weapon seems to be (server/apply.C:check_weapon_power):

  ((who->level / 5) + 5) >= op->last_eat

=item last_sp

the weapon speed (see magic description)

=item food <number>

addition to food regeneration of the player

=item hp <number>

addition to health regeneration

=item sp <number>

addition to mana regeneration

=item grace <number>

addititon to grace regeneration

=item gen_sp_armour <number>

the players gen_sp_armour field (which is per default 10) is added the <number> amount.
gen_sp_armour seems to be a factor with which gen_sp in do_some_living()
is multiplied:  gen_sp *= 10/<number>
meaning: values > 10 of gen_sp_armour limits the amout of regenerated
spellpoints.

generally this field on weapons is in ranges of 1-30 and decides the slowdown of the
sp regeneration.

=item body_<body slot/part>

the part of the body you need to use this weapon, possible values should be
looked up in common/item.C at body_locations.

=item resist_<resistnacy> <number>

this is the factor with which the difference of the players resistancy and 100%
is multiplied, something like this:

   additional_resistancy = (100 - current_resistanct) * (<number>/100)

if <number> is negative it is added to the total vulnerabilities,
and later the total resistance is decided by:

  'total resistance = total protections - total vulnerabilities'

see also common/living.C:fix_player

=item patch_(attuned|repelled|denied)

this field modifies the pathes the player is attuned to, see include/spells.h PATH_*
for the pathes.

=item luck <number>

this luck is added to the players luck

=item move_type

if the weapon has a move_type set the player inherits it's move_type

=item exp <number>

the added_speed and bonus_speed of the player is raised by <number>/3.
if <number> < 0 then the added_speed is decreased by <number>

=item weight

the weight of the weapon

=item magic

the magic field affects the amounts of the following fields:

  - wc : the players wc is adjusted by: player->wc -= (wc + magic)

  - ac : the players ac is lowered by (ac + magic) if (player->ac + magic) > 0

  - dam: the players dam is adjusted by: player->dam += (dam + magic)

  - weapon speed (last_sp): weapon_speed is calculated by: (last_sp * 2 - magic) / 2
                            (minium is 0)

=item ac <number>

the amount of ac points the player's ac is decreased

=item wc <number>

the amount of wc points the player's ac is decreased

=back

=head4 Player inherits following flags from weapons:

   FLAG_LIFESAVE, FLAG_REFL_SPELL, FLAG_REFL_MISSILE, FLAG_STEALTH,
   FLAG_XRAYS, FLAG_BLIND, FLAG_SEE_IN_DARK, FLAG_UNDEAD
Revision:	1.3
Committed:	Mon Dec 18 12:11:08 2006 UTC (17 years, 5 months ago) by elmex
Branch:	MAIN
Changes since 1.2:	+28 -17 lines
Log Message:	further development on the force documentation.
#	User	Rev	Content
1	elmex	1.1	=head1 CROSSFIRE+ OBJECT AND INTERNALS DOCUMENTATION
2
3			Here is all information about the object types Crossfire+
4			supports at the moment. This is not a complete documentation (yet)
5			and browsing the source is still recommended to learn about
6			the objects that aren't documented here.
7
8			This documentation is in a sketchy state. It's mostly
9			used to collect notes about the internal behaviour of the
10			objects.
11
12			=head2 About archetypes and objects
13
14			Field denotes an attribute of an archetype.
15			This is an example of an archetype:
16
17			Object button_trigger
18			name button
19			type 30
20			face button_sma.111
21			anim
22			button_sma.111
23			button_sma.112
24			mina
25			is_animated 0
26			exp 30
27			no_pick 1
28			walk_on 1
29			walk_off 1
30			editable 48
31			visibility 50
32			weight 1
33			end
34
35			This archetype has the name 'button_trigger' and the objects that
36			inherit from this archetype have the name 'button'.
37
38			The next field 'type' decides the main behaviour of this archetype.
39			For a comprehensive list of types see include/define.h. For this case
40			you might find a line like:
41
42			#define TRIGGER_BUTTON 30
43
44			The server internally works with objects that 'inherit' attributes from
45			an archetype. They have a similar set of attributes.
46
47			The following documentation will also document the meaning of code internal
48			attributes of objects. These attributes are marked as '(internal)' and can't
49			or shouldn't be set by an archetype. If the internal names differs the
50			external name (for the archetypes) for the attribute is written behind it.
51
52			=head2 Description of generic archetype and object attributes
53
54	elmex	1.2	These are the fields that most of the objects have and/or their
55			default behaviour.
56
57			=over 4
58
59			=item name <string>
60
61			The name of the object.
62
63			=item name_pl <string>
64
65			The name of a collection of these objects (the plural of the name).
66
67			=item face <facename>
68
69			The graphical appearance of this object.
70
71			=item invisible <number>
72
73			If the <number> is greater than 0 the object is invisible.
74			For players this field reflects the duration of the invisibility
75			and is decreased every tick by 1.
76
77			For non-player objects this field is not changed by server ticks.
78
79			=item speed <numeric>
80
81			If this field is greater than MIN_ACTIVE_SPEED (~0.0001) the object is placed
82			on the active object list and will be processed each tick (see also speed_left!).
83
84			If the speed field drops below the MIN_ACTIVE_SPEED the object is removed
85			from the active object list and it won't experience any processing per tick.
86
87			=item speed_left <number>
88
89			If this field is greater than 0 and the object is on the
90			active list (mostly means it's speed is also greater than 0):
91
92			- speed_left is decreased by 1
93			- and this object is processed and experiences a server tick.
94
95			If the object is on the active list and speed_left is lower or
96			equal to 0 the absolute value of the speed field is added to speed_left
97			on the end of the tick.
98
99			=item no_drop (0\|1)
100
101			Sets the flag FLAG_NO_DROP. See the Flags section below.
102
103			=item applied (0\|1)
104
105			Sets the flag FLAG_APPLIED. See the Flags section below.
106
107			=item is_used_up (0\|1)
108
109			Sets the flag FLAG_IS_USED_UP. See Flags section below.
110
111			=item editable (more than deprecated)
112
113			This field had a special meaning for crossedit, which used parts
114			of the server code for editing. Wherever you see this attribute being
115			set in an archetype ignore it and/or remove it. No code interprets this
116			field anymore.
117
118			=back
119
120			=head3 Flags
121
122			Here are the effects of the flags described.
123
124	elmex	1.1	=over 4
125
126	elmex	1.2	=item FLAG_NO_DROP
127
128			An object can't be picked up and dropped.
129
130			=item FLAG_APPLIED
131
132			This flag mostly states whether this object has been 'applied' by the player.
133			For objects that are applied by the code or have this flag set in the archetype
134			it mostly means 'this object is active'.
135
136			For example the player adjustments of the hp/sp/grace fields and inheritance
137			of flags from objects in his inventory is toggled by this flag.
138
139			=item FLAG_IS_USED_UP
140
141			This flag controls whether an object is 'used up'. If it is set the 'food' field
142			of the object is decreased by 1 each tick, and if it is lower or equal 0 after tha
143			it is removed.
144
145			If also the flag FLAG_APPLIED is set, the 'duration' field controls whether
146			this object is removed or not, see the Force type below for the meaning
147			of the duration field in this context.
148
149	elmex	1.3	If FLAG_APPLIED is not set the object is destroyed.
150
151	elmex	1.1	=back
152
153			=head2 Description of type specific attributes
154
155			The beginning of the headers of the following subsection
156			are the server internal names for the objects types, see include/define.h.
157			The numeric values are maybe not 100% accurate, as the code is a changing
158			target, please consult include/define.h in doubt :-)
159
160	elmex	1.3	=head3 FORCE - type 114 - Forces
161
162			Forces are a very 'thin' type. They don't have much behaviour other than
163			disappearing after a time and/or affecting the player if they are in his inventory.
164
165			Forces only take effect on the player if they have set FLAG_APPLIED.
166
167			Whether the duration field is processed or not a tick is controlled via the
168			speed and speed_left field. Look above at the generic description of these
169			fields.
170
171			=over 4
172
173			=item duration
174
175			While this field is greater than 0 the force/object is not destroyed.
176			It is decreased each tick by 1.
177
178			If it reaches 0 the force/object is destroyed.
179
180			This field can have this meaning for B<any> object if that object has
181			FLAG_IS_USED_UP and FLAG_APPLIED set. See the description of FLAG_IS_USED_UP
182			what happens then.
183
184			=back
185
186	elmex	1.1	=head3 WEAPON - type 15 - Weapons
187
188			This type is for general hack and slash weapons like swords, maces
189			and daggers and and ....
190
191			=over 4
192
193			=item weapontype <type id>
194
195			decides what attackmessages are generated, see include/define.h
196
197			=item attacktype <bitmask>
198
199			bitfield which decides the attacktype of the damage, see include/attackinc.h
200
201	elmex	1.2	=item dam <number>
202	elmex	1.1
203			amount of damage being done with the attacktype
204
205			=item item_power <level>
206
207			the itempower of this weapon.
208
209			=item name
210
211			the name of the weapon.
212
213			=item level (internal)
214
215			The improvement state of the weapon.
216			If this field is greater than 0 the 'name' field starts with the
217			characters name who improved this weapon.
218
219			=item last_eat (internal)
220
221			seems to be the amount of improvements of a weapon,
222			the formular for equipping a weapon seems to be (server/apply.C:check_weapon_power):
223
224			((who->level / 5) + 5) >= op->last_eat
225
226			=item last_sp
227
228			the weapon speed (see magic description)
229
230	elmex	1.2	=item food <number>
231	elmex	1.1
232			addition to food regeneration of the player
233
234	elmex	1.2	=item hp <number>
235	elmex	1.1
236			addition to health regeneration
237
238	elmex	1.2	=item sp <number>
239	elmex	1.1
240			addition to mana regeneration
241
242	elmex	1.2	=item grace <number>
243	elmex	1.1
244			addititon to grace regeneration
245
246	elmex	1.2	=item gen_sp_armour <number>
247	elmex	1.1
248	elmex	1.2	the players gen_sp_armour field (which is per default 10) is added the <number> amount.
249	elmex	1.1	gen_sp_armour seems to be a factor with which gen_sp in do_some_living()
250	elmex	1.2	is multiplied: gen_sp *= 10/<number>
251	elmex	1.1	meaning: values > 10 of gen_sp_armour limits the amout of regenerated
252			spellpoints.
253
254			generally this field on weapons is in ranges of 1-30 and decides the slowdown of the
255			sp regeneration.
256
257			=item body_<body slot/part>
258
259			the part of the body you need to use this weapon, possible values should be
260			looked up in common/item.C at body_locations.
261
262	elmex	1.2	=item resist_<resistnacy> <number>
263	elmex	1.1
264			this is the factor with which the difference of the players resistancy and 100%
265			is multiplied, something like this:
266
267	elmex	1.2	additional_resistancy = (100 - current_resistanct) * (<number>/100)
268	elmex	1.1
269	elmex	1.2	if <number> is negative it is added to the total vulnerabilities,
270	elmex	1.1	and later the total resistance is decided by:
271
272			'total resistance = total protections - total vulnerabilities'
273
274			see also common/living.C:fix_player
275
276			=item patch_(attuned\|repelled\|denied)
277
278			this field modifies the pathes the player is attuned to, see include/spells.h PATH_*
279			for the pathes.
280
281	elmex	1.2	=item luck <number>
282	elmex	1.1
283			this luck is added to the players luck
284
285			=item move_type
286
287			if the weapon has a move_type set the player inherits it's move_type
288
289	elmex	1.2	=item exp <number>
290	elmex	1.1
291	elmex	1.2	the added_speed and bonus_speed of the player is raised by <number>/3.
292			if <number> < 0 then the added_speed is decreased by <number>
293	elmex	1.1
294			=item weight
295
296			the weight of the weapon
297
298			=item magic
299
300			the magic field affects the amounts of the following fields:
301
302			- wc : the players wc is adjusted by: player->wc -= (wc + magic)
303
304			- ac : the players ac is lowered by (ac + magic) if (player->ac + magic) > 0
305
306			- dam: the players dam is adjusted by: player->dam += (dam + magic)
307
308			- weapon speed (last_sp): weapon_speed is calculated by: (last_sp * 2 - magic) / 2
309			(minium is 0)
310
311	elmex	1.2	=item ac <number>
312	elmex	1.1
313			the amount of ac points the player's ac is decreased
314
315	elmex	1.2	=item wc <number>
316	elmex	1.1
317			the amount of wc points the player's ac is decreased
318
319			=back
320
321			=head4 Player inherits following flags from weapons:
322
323			FLAG_LIFESAVE, FLAG_REFL_SPELL, FLAG_REFL_MISSILE, FLAG_STEALTH,
324			FLAG_XRAYS, FLAG_BLIND, FLAG_SEE_IN_DARK, FLAG_UNDEAD