This file describes the unit directories and especially the contents of the
index.unit files.

WARNING this is ALWAYS work in progress. When you read this file, many things
might have changed already - keeping this file up to date is a very low priority
to the coders.
Have a look in the uniteditor ("bounit") for further information on the fields.
However the definite information are in the code only.

------------------
The unit directory
------------------
All units in boson are derived from the "Unit" class and therefore they all
share one common directory - facilities as well as mobile units.
All files which belong to a unit of this species belong to its directory in
themes/species/*/units/unit_dir - unit_dir is the unique directory of the unit.
It doesn't matter how you name this directory - however a prefix like mob_ and
fix_ might be useful when working on the units. But this depends on you.

Currently a unit must have at least 2 overview bitmaps (overview-big.png and
overview-small.png) which are shown when the unit is selected (big) and as a
button in the construction facility (small).
The big overview must have a size of 100x100
The small overview must have a size of 50x50
Optionally, units may have overview pixmap for manual (overview-manual.png, size
is 320x240).
A unit has a model file. Currently we are using .3ds files (3D Studio Max file
format). This file is simply called "unit.3ds". If we support another file
format in the future only the suffix will change.
The textures of this unit model are a little bit special. They are not in the
unit directory - not even in the species directory. You can find them in
themes/textures/ for *all* species and *all* units.
We do this to be able to share the textures between all units/models. If you use
textures that are already used by other units boson will use less memory (on
runtime!) and might run faster (texture memory is limited).

Effects can be found in themes/effects/

Additionally all units have index.unit file in their directories. This file
describes the unit - if you are familar with KConfig syntax you'll know how to
edit them.


-------------------
index.unit: general
-------------------
The rest of this file is about the index.unit.
It has first a common group shared by all units:
"[Boson Unit]" (without the quotation marks). This group can contain the
following entries:

The entries marked with * are mandatory.
-------------------------------------------------------------------------------
[Boson Unit]
IsFacility=boolean
        True if this is a facility, false if this is a mobile unit.
        Default is false.
* Name=Text
        The Name of the unit. Should be short, no more than 2 or 3
        words. One if possible.
        Default is "Unknown".
* Id=Number
        A unique (!) ID for this unit. Must be > 0.
        No default!
Description=Text
        A (short) free text describing this unit. Is displayed (for example) in
        the commandframe when producing a unit of this type.
UnitWidth=Number
        The width of the unit in cells.
        You can use floating point numbers - e.g. 1.5 will make
        the unit occupy 1.5 cells.
        Please don't use values like 1.3333 (might cause rounding
        trouble) or 1.23876381687 (nonsense value).
        Default is 1.0
UnitHeight=Number
        The height of the unit in cells.
        You can use floating point numbers - e.g. 1.5 will make
        the unit occupy 1.5 cells.
        Please don't use values like 1.3333 (might cause rounding
        trouble) or 1.23876381687 (nonsense value).
        Default is 1.0
UnitDepth=Number
        The height in z-direction of the unit in cells.
        You can use floating point numbers - e.g. 1.5 will make
        the unit occupy 1.5 cells.
        Please don't use values like 1.3333 (might cause rounding
        trouble) or 1.23876381687 (nonsense value).
        Default is 1.0
Health=Number
        Health. More health = can take more hits ; live longer.
        Must be > 0 (not = 0 !). Default is 100.
Shields=Number
        Absorb hits. Reload themselves.
        Must be >= 0. Default is 0.
Armor=Number
        More armor = hits cause less damage.
        Must be >= 0. Default is 0.
MineralCost=Number
        How much mineral do you have to pay if you build this?
        Must be >= 0. Default is 100.
OilCost=Number
        How much oil do you have to pay if you build this?
        Must be >= 0. Default is 0.
SightRange=Number
        The sight range of this unit.
        the sight range is how far (in cells!) this unit can see.
        Must be >= 0. Default is 5 (currently).
PowerConsumed=Number
        How much power (electricity) this unit requires for being operational.
        When the unit is out of power, certain tasks are not working anymore
        (for example reloading the weapon) or are much slower (productions).
        Note that this field is possible for both, facilities and mobile units.
        For mobile units this can be explained by having some "invisible small
        men walking around and delivering batteries" ;-)
        Must be >= 0. Default is 0.
TerrainType=Number
        The default terrain type of the unit. One of 1 (Land),
        2 (Water), 4 (Air - Plane) or 8 (Air - Helicopter).
        You must decide for one - even if the unit is some kind
        of mixture. If so you will probably use Land (1).
        The default is 1 (=Land Unit)

        See also the unit editor, which may contain more up to date information!
ProductionTime=Number
        The number of seconds needed to produce this unit
        Must be >= 0. Default is (currently) 5.
Producer=Number
        Specifies which kind of factory is able to produce this
        unit. Possible values are: 0=war factory (heavy land
        units, all types of vehicles), 1=shipyard (all ships),
        2=airport (all aircrafts), 3=barracks (soldiers,
        human units), 10=command bunker (all facilities).
        Please note that there is currently only a single factory
        for every Producer type, but we might add more one day
        (e.g. a mobile factory). The possible productions of those
        factories will also depend on the Producer type.
        The default is the factory producing units of the current TerrainType.
SupportMiniMap=bool
        If true then this player has a minimap when he has a unit
        of this type. The minimap disappears when all units of the
        player which have SupportMiniMap=true are gone.
        The minimap is only displayed, if the player has sufficient power (or if
        the unit does not consume any power).
        Default is false.
Requirements=List
        List is comma separated list of unit IDs. Player must have
        built all those units before he can build this unit.
        Default is an empty list.
ExplodingDamage=Number
        How much damage is applied to nearby units when this unit explodes (is
        destroyed)
        Default is 0
ExplodingDamageRange=Number
        In how big radius nearby units will be damaged when this unit explodes.
        Default is 0
ExplodingFragmentCount=Number
        How many fragments of of the unit are created when it explodes.
        Fragments damage units nearby.
        Must be >= 0. Default is 0.
ExplodingFragmentDamage=Number
        How much damage the fragments cause.
        Default is 10.
ExplodingFragmentRange=Number
        Default is 0.5.
RemoveWreckageImmediately=Bool
        If True, the wreckage of this unit is removed immediately from the map
        (i.e. is hidden), otherwise it remains on the map for a short while.
        Default is false.
HitPoint=Vector
        Defines "hitpoint" of this unit. Hitpoint is used for shooting, all
        units will shoot at this point when attacking this unit. It should be
        point on the unit's surface.
        Vector consists of 3 floating-point numbers, separated by commas, e.g.
        1.2,0.6,-0.3 and is relative to the center of the unit.
        Default is 0,0,0 (center of the unit).
DestroyedEffects=List
        Comma separated list of effects which will be created when this
        unit is destroyed. You can create e.g. smoke and explosion with this.
        Default is an empty list.
ConstructedEffects=List
        Comma separated list of effects which will be created when this
        unit is constructed. You can create e.g. light smoke for factory
        chimneys with it.
        Default is an empty list.
Weapons=Number
        How many weapons this unit has.
        See below for more information about weapons.
        Default is 0.
-------------------------------------------------------------------------------



You should provide as many entries as possible although you don't have to.

Also note that all entries support (as of KConfig) the possibility to create
localized versions. You can e.g. use "Name[de]=German Name" or so. Use this
feature where it is useful. I doubt this is useful for something like Id ;-)
(Ahem - "I doubt" means: don't do it under any circumstances!!)

---------------------------------------
index.unit: facilities and mobile units
---------------------------------------
Beside this general group there is one group for facilities only ("[Boson
Facility]") and one for mobile units ("[Boson Mobile Unit]"). Both are not
mandatory.
These groups contain all mobile unit/facility specific stuff (like the
speed for a unit).

-------------------------------------------------------------------------------
[Boson Mobile Unit]
Speed=Number
        Value of the speed of the unit. A unit will move that many
        pixels per advance call. This is a double number so values
        like "0.452463" are possible as well.
        Must be >= 0. Default is 0
CanGoOnLand=boolean
        Whether this unit can go over land.
        This is true by default for TerrainType = Land or
        Aircraft.
CanGoOnWater=boolean
        Whether this unit can go over water.
        This is true by default for TerrainType = Water or
        Aircraft.
AccelerationSpeed=Number
DecelerationSpeed=Number
RotationSpeed=Number
CrushDamage=Number
        Default is 0.
MaxSlope=Number
        Default is 30.
WaterDepth=Number
        Default is 0.25.
TurnRadius=Number
        Default is 5.
PreferredAltitude=Number
        Default is 3.
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
[Boson Facility]
ConstructionSteps=Number
        Time the facility takes to be built. This is more or
        less the number of frames displayed in the 
        construction animation.
        Default is 20
-------------------------------------------------------------------------------



--------------------
index.unit: Textures
--------------------
Another group shared by all units (it is *not* mandatory) is the textures
group. Since .3ds files seem to allow filenames of 8+3 length only we are
mapping those "short names" to "real names" here. If a texture doesn't have an
entry here it will use the "short name".

-------------------------------------------------------------------------------
[Textures]
Textures=List
        List of textures. Only the "short name" that should
        get mapped have to be listed here. All listed files
        need to have an entry in this group (if it isn't
        there it is ignored. no error).
        Defaul is an empty list
texture.jpg=LongName.jpg
        "texture.jpg" is the "short name" of the texture,
        i.e. the name as listed in the model (.3ds) file. It
        must be listed in the "Textures=" entry (see above).
        It must be lowercase! (even if it is uppercase in the
        model file)
        "LongName.jpg" is the filename that gets used instead
        of the "short name". Case sensitve (but doesn't
        matter, since filename in boson should be lowercase
        anyway).
-------------------------------------------------------------------------------


------------------
index.unit: Sounds
------------------
[Sounds]
Sounds are stored in $KDEDIR/share/apps/boson/themes/species/${species}/sounds/
You can add different sounds for different facility actions.
The value for a sound effect is the filename without extension.

OrderAttack=soundfile
        When a facility gets the order to attack someone.
        Default is order_attack.
OrderMove=soundfile
        When the facility gets the order to move.
        Default is order_move.
OrderSelect=soundfile
        When a facility gets selected.
        Default is order_select.
ReportDestroyed=soundfile
        When a facility gets destroyed.
        Default is report_destroyed.
ReportProduced=soundfile
        When a facility finished producing something.
        Default is report_produced.
ReportUnderAttack=soundfile
        When a facility comes under attack.
        Default is report_underattack.
-------------------------------------------------------------------------------





-----------------
index.unit: Model
-----------------
The Model group is also shared by all units and not mandatory, but will
probably be used by most units. In this group you specify e.g. how many frames
the model has and how they should be used. Note that counting starts at 0 here!
so e.g. 5 frames are 0..4 !
The first frame of an animation is specified by "Animation-*-Start" where "*" is the
name of the animation type. See below for possible values here.
Similarly, the last frame of that animation is specified by "Animation-*-End".
You'll also need to specify how fast the frames change - this is done using
"Animation-*-Speed". The current frame is increased by this value every advance
call (every "game tick"), i.e. higher values mean faster animations, lower
values mean slower animations (values between 0 and 1 are allowed!). 0 Disables
the animation completely.

So e.g. to use the first 10 frames when the unit does nothing and to change the
frame every 5 advance calls use this:
Animation-Idle-Start=0
Animation-Idle-End=10
Animation-Idle-Speed=5

-------------------------------------------------------------------------------
[Model]
Animation-Idle-Start=Number
        (see above for general information)
        Default is 0.
Animation-Idle-End=Number
        (see above for general information)
        Default is 0.
Animation-Idle-Speed=Number
        (see above for general information)
        Default is 1.
        The "Idle" action specifies the frames/animation
        of the unit when it does nothing, i.e. is idle.
Animation-Wreckage-Start=Number
        (see above for general information)
        Default is 0.
Animation-Wreckage-End=Number
        (see above for general information)
        Default is 0.
Animation-Wreckage-Speed=Number
        (see above for general information)
        Default is 0.
        The "Wreckage" action specifies the frames/animation
        of the unit when it is destroyed
-------------------------------------------------------------------------------


-------------------
index.unit: Weapons
-------------------
Of course every unit may have weapons. The number of weapons must be set in the main
group if you use them - see above for information about it.
For every weapon, there must be a group with the name "Weapon_x" where x is the number of
the weapon, starting with 0.
E.g. if the unit has 3 weapons, it must have groups "Weapon_0", "Weapon_1" and "Weapon_2".
Note that units may have only one repairing weapon. If you specify multiple
repairing weapons, only first the one is used.
For help on soundfiles look under [Sounds]
-------------------------------------------------------------------------------
[Weapon_x]
Type=String
        String that identifies the shot type. Currently supported are Bullet,
        Rocket, Missile, Mine, Bomb.
        Default is Rocket.
Name=Text
        At the moment this is only for the handbook.
Damage=Number
        The damage this unit makes to other units when firing.
        Can also be negative - the unit repairs then.
        Default is 0.
Range=Number
        Range of this weapon.
        Must be >= 0. Default is 0.
Reload=Number
        The time to reload the weapon. "Time" means number of
        advance calls (default is 1 per 50ms = 20 calls/sec).
        Must be >= 0. Default is 0.
CanShootAtAirUnits=Bool
        Can this unit shoot at aircrafts?
        Default false.
CanShootAtLandUnits=Bool
        Can this unit shoot at ground units? True or False.
        Default false.
Speed=Number
        Speed of the shot of this weapon. If it's 0, the shot will hit the
        target immediately (speed is infinite). Default is 0
DamageRange=Number
        In how big range this weapon's shot can damages other units?
        E.g. if it's 2, all units two or less cells away from the
        explosion will get damaged.
        Must be >= 0. Default is 1.
FullDamageRange=Number
        Specifys the range where all units will be fully damaged.
        Must not be bigger than DamageRange.
        Default is a quarter of DamageRange.
Height=Number
        What's the height of missile of this weapon when it flies. If
        you increase this, your missiles will fly with bigger arc.
        Default is 0.25.
Model=Filename
        Model of this weapon. If weapon's speed is 0, model
        will never be visible, so you won't need it.
        Default is "missile.3ds"
HitEffects=List
        List of ids of the effects created
        when the weapon hits it's target.
        Target point is _not_ a unit, it might be any point.
        Default is empty list.
FlyEffects=List
        Default is empty list.
ShootEffects=List
        List of ids of the effects created
        when the unit is firing the weapon.
        Default is empty list.
SoundShoot=Soundfile
        Sound file which is played when the weapon shoots.
        Default is shoot.
SoundFly=Soundfile
        Sound file which is played during the weapons flies. (for missiles)
        Not yet used.
        Default is missile_fly.
SoundHit=Soundfile
        Sound file which is played when the weapon hits it's target.
        Not yet used.
        Default is hit.
TurretMeshes=List
        List of mesh names (of the unit model) that are considered to be the
        "turret" of this weapon. These meshes are rotated towards the point this
        weapon shoots at.
        This list must contain _ALL_ meshes that are part of the turret,
        otherwise you will experience unusual behaviour. For example if a model
        has a layout like this:
        - Base
          - Turret
            - Gun
            - Gun2
              - SomeNicePartOfGun2
          - SomeOtherMesh
        then the list should contain Turret,Gun,Gun2,SomeNicePartOfGun2.
AmmunitionType=String
        The name of the ammunition this weapon uses.
        This can be any name you like, however it doesn't make any sense to use
        fantasy names, as the player won't have any ammunition of this type
        then. Use an ammunition that is actually provided by the player.
        Default is "Generic" ammunition.
RequiredAmmunition=Number
        How much of the "AmmunitionType" ammunition is required for one shot of
        this weapon.
        Default is 1.
-------------------------------------------------------------------------------


-------------------
index.unit: Plugins
-------------------
Now lets get to the "misc" stuff. You can define several plugins - look into
pluginproperties.h for a list of all possible plugins (NOT unitplugins.h!)

You simply need to add the group to the file in order to make the unit support
that plugin.
For example if you want to to allow the unit to produce units simply add
"[ProductionPlugin]" as a new group (without the quotation marks). For some
plugins you also need/can provide entries inside that group. For example the
production plugin doesn't make any sense without a list of producable units.
I'll try to document new plugins here - but for a current list look at
pluginproperties.h

-------------------------------------------------------------------------------
[ProductionPlugin]
The production plugin is usually a facility-only plugin. One day we might use
this for mobile factories, too. Note: this has never been tested, but I
definitely want to support this!

ProducerList=List
        The List is a comma separated list of Producer IDs.
        The facility will be able to produce all units with the
        "Producer" entry that is listed here.
        Default is an empty List.
-------------------------------------------------------------------------------
[RepairPlugin]
(not yet supported)
-------------------------------------------------------------------------------
[HarvesterPlugin]
For mineral/oil miners. Well - doesn't make any sense for facilities :-)

CanMineMinerals=boolean
        Whether this unit can mine minerals.
        Default is false.
CanMineOil=boolean
        Whether this unit can mine oil.
        Default is false.
MaxResources=number
        The maximal amount of resourced that can be mined until
        the unit needs to return to a refinery.
        Must be > 0. Default is 100.
MiningSpeed=number
        How fast this unit mines. This is per advance call.
        Default is 10
UnloadingSpeed=number
        How fast this unit gives resources to refinery. This is per advance call.
        Default is 10
-------------------------------------------------------------------------------
[RefinePlugin]
CanRefineOil=Boolean
        True if this is an oilrefinery.
        Default is false
CanRefineMinerals=Boolean
        True if this is a mineralrefinery.
        Default is false
-------------------------------------------------------------------------------


/*
 * vim:et
 */
