=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