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.

=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 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

=head3 FORCE - type 114 - Forces

Note: 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 is not removed.
It is decreased each tick by 1.

=back
Revision:	1.2
Committed:	Mon Dec 18 12:01:20 2006 UTC (17 years, 5 months ago) by elmex
Branch:	MAIN
Changes since 1.1:	+127 -17 lines
Log Message:	further documentation about some default fields of objects and this weird force object.
#	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.1	=back
150
151			=head2 Description of type specific attributes
152
153			The beginning of the headers of the following subsection
154			are the server internal names for the objects types, see include/define.h.
155			The numeric values are maybe not 100% accurate, as the code is a changing
156			target, please consult include/define.h in doubt :-)
157
158			=head3 WEAPON - type 15 - Weapons
159
160			This type is for general hack and slash weapons like swords, maces
161			and daggers and and ....
162
163			=over 4
164
165			=item weapontype <type id>
166
167			decides what attackmessages are generated, see include/define.h
168
169			=item attacktype <bitmask>
170
171			bitfield which decides the attacktype of the damage, see include/attackinc.h
172
173	elmex	1.2	=item dam <number>
174	elmex	1.1
175			amount of damage being done with the attacktype
176
177			=item item_power <level>
178
179			the itempower of this weapon.
180
181			=item name
182
183			the name of the weapon.
184
185			=item level (internal)
186
187			The improvement state of the weapon.
188			If this field is greater than 0 the 'name' field starts with the
189			characters name who improved this weapon.
190
191			=item last_eat (internal)
192
193			seems to be the amount of improvements of a weapon,
194			the formular for equipping a weapon seems to be (server/apply.C:check_weapon_power):
195
196			((who->level / 5) + 5) >= op->last_eat
197
198			=item last_sp
199
200			the weapon speed (see magic description)
201
202	elmex	1.2	=item food <number>
203	elmex	1.1
204			addition to food regeneration of the player
205
206	elmex	1.2	=item hp <number>
207	elmex	1.1
208			addition to health regeneration
209
210	elmex	1.2	=item sp <number>
211	elmex	1.1
212			addition to mana regeneration
213
214	elmex	1.2	=item grace <number>
215	elmex	1.1
216			addititon to grace regeneration
217
218	elmex	1.2	=item gen_sp_armour <number>
219	elmex	1.1
220	elmex	1.2	the players gen_sp_armour field (which is per default 10) is added the <number> amount.
221	elmex	1.1	gen_sp_armour seems to be a factor with which gen_sp in do_some_living()
222	elmex	1.2	is multiplied: gen_sp *= 10/<number>
223	elmex	1.1	meaning: values > 10 of gen_sp_armour limits the amout of regenerated
224			spellpoints.
225
226			generally this field on weapons is in ranges of 1-30 and decides the slowdown of the
227			sp regeneration.
228
229			=item body_<body slot/part>
230
231			the part of the body you need to use this weapon, possible values should be
232			looked up in common/item.C at body_locations.
233
234	elmex	1.2	=item resist_<resistnacy> <number>
235	elmex	1.1
236			this is the factor with which the difference of the players resistancy and 100%
237			is multiplied, something like this:
238
239	elmex	1.2	additional_resistancy = (100 - current_resistanct) * (<number>/100)
240	elmex	1.1
241	elmex	1.2	if <number> is negative it is added to the total vulnerabilities,
242	elmex	1.1	and later the total resistance is decided by:
243
244			'total resistance = total protections - total vulnerabilities'
245
246			see also common/living.C:fix_player
247
248			=item patch_(attuned\|repelled\|denied)
249
250			this field modifies the pathes the player is attuned to, see include/spells.h PATH_*
251			for the pathes.
252
253	elmex	1.2	=item luck <number>
254	elmex	1.1
255			this luck is added to the players luck
256
257			=item move_type
258
259			if the weapon has a move_type set the player inherits it's move_type
260
261	elmex	1.2	=item exp <number>
262	elmex	1.1
263	elmex	1.2	the added_speed and bonus_speed of the player is raised by <number>/3.
264			if <number> < 0 then the added_speed is decreased by <number>
265	elmex	1.1
266			=item weight
267
268			the weight of the weapon
269
270			=item magic
271
272			the magic field affects the amounts of the following fields:
273
274			- wc : the players wc is adjusted by: player->wc -= (wc + magic)
275
276			- ac : the players ac is lowered by (ac + magic) if (player->ac + magic) > 0
277
278			- dam: the players dam is adjusted by: player->dam += (dam + magic)
279
280			- weapon speed (last_sp): weapon_speed is calculated by: (last_sp * 2 - magic) / 2
281			(minium is 0)
282
283	elmex	1.2	=item ac <number>
284	elmex	1.1
285			the amount of ac points the player's ac is decreased
286
287	elmex	1.2	=item wc <number>
288	elmex	1.1
289			the amount of wc points the player's ac is decreased
290
291			=back
292
293			=head4 Player inherits following flags from weapons:
294
295			FLAG_LIFESAVE, FLAG_REFL_SPELL, FLAG_REFL_MISSILE, FLAG_STEALTH,
296			FLAG_XRAYS, FLAG_BLIND, FLAG_SEE_IN_DARK, FLAG_UNDEAD
297	elmex	1.2
298			=head3 FORCE - type 114 - Forces
299
300			Note: Forces only take effect on the player if they have set FLAG_APPLIED.
301
302			Whether the duration field is processed or not a tick is controlled via the
303			speed and speed_left field. Look above at the generic description of these
304			fields.
305
306			=over 4
307
308			=item duration
309
310			While this field is greater than 0 the force is not removed.
311			It is decreased each tick by 1.
312
313			=back