XML/Unit

The unit XML is the main body of a mod, defining everything about each unit. Every unit has this XML, which is named the same as their unit folder, and defines their stats and abilities, as well as various other bits of information on the unit.

size
This is the width of the unit in Glest cells. Note that all units take up a perfect square of cells, so size 2 means it's a 2x2 unit.

height
The height of the unit is used for check for collision of projectile attacks, as well as for determining the placement of particles such as flames. Most standard humanoids are 2-3 units tall.

target-height
A height which is used to calculate the target height for projectiles shot by attacking units. Per default this value is the same as the height.

burn-height
A height which is used to calculate the the position of the fire particle system if the unit is burnable. Per default this value is the same as the height.

max-hp
The maximum health of the unit. A produced unit has full health once produced, but a building starts at zero health, and will increase as it is built, with construction ending once it reaches full health. When health reaches zero, the unit dies.

max-ep
The maximum energy of a unit. Skills can have energy requirements, meaning they draw a certain amount of energy each skill cycle.

armor
Damage that is subtracted from the damage, using the following formula:

$$\text{Damage} = \left(\frac{\text{Attack Strength} + \text{Random}}{\text{Distance} + 1} - \text{Armor}\right) \times \text{Damage Multiplier}$$

armor-type
The type of armor, which is declared in the Faction XML and can be set with a multiplier so that different attack types will do damage based on the type of armor the foe has, such as a sword doing less damage on metal armor than bare flesh.

sight
The distance a unit can see, as a radius in glest units. Units cannot attack others outside of their sight, and fog of war/shroud of darkness are removed when they are inside a unit's sight.

time
The time it takes to produce this unit. Varies according to the producer's production speed, but follows the following formula:

$$\text{World Frames} = \text{Time} \times floor\left(\frac{1}{\frac{\text{speed}}{4000} + 1}\right)$$

multi-selection
If true, all units of the same type can be mass selected by double clicking one of them. As well, this must be on for the unit to be selectable by clicking and dragging a selection box (otherwise the selection box ignores that type of unit). This should generally be off for buildings and on for regular units, unless there is any reason you don't want them to be easily mass selected.

cellmap
Cellmaps are generally used only for buildings to define what parts are walkable and what parts are not. If the building takes up the entire square that is defined by its size, then the cellmap should not be used (the value should be false the tag should be immediately closed, such as &lt;cellmap value="false" /&gt;). Otherwise, if using the cellmap, there must be as many row elements as the size, and each of these row's must have a value containing as many characters as the unit's size. So if the unit is size 2, there should be two row tags each with 2 characters. These characters are 1's (cannot be walked on) and 0's (can be walked on). Cellmaps are rotated with the unit.

The allowEmpty attribute is a MegaGlest only attribute which allows a unit with an all zero cellmap to be completely ignored by the AI and immune to attacks, circumventing the AI issues that would occur if not used. Note that even on a size zero unit, the cellmap value must be set to true (eg, &lt;cellmap value="true" allowEmpty="true" /&gt;).

levels
Levels are increases in stats and a name change that occur after the unit reaches a certain number of kills. For Glest and MegaGlest, only the name and level can be changed. When the unit reaches that number of kills, the name is prefixed to the unit and they are given a +50% max HP, +50% max EP, +50% armor, and +20% sight boost, which stacks with each level.

In GAE, customizing the levels can be done by specifying specific boosts as either static modifiers or multipliers. A static modifier increases stats by an absolute amount, and a multiplier multipliers the stats by a number. GAE also has a defaults attribute which, if false, will prevent the default boost from stacking with the specified custom boost.

fields
Fields are the area that units can traverse. In Glest and MegaGlest, this is limited to land and air. Land units can only walk on walkable parts of the land and shallow water, while air units can fly and traverse everywhere. In GAE, the additional fields of any_water (deep or shallow water), deep_water</tt> (only the deep areas that land units cannot enter), or amphibious</tt> (the unit can traverse both land and water (of any depth) but are still limited by unwalkable terrain).

properties
Properties are additional flags which take no parameters, but can define the unit.
 * burnable</tt> - When the unit drops to under 50% HP (only after being attacked for the first time, to prevent the occurance when building), a flame particle effect starts and persists until the unit's HP is back above 50%.
 * wall</tt> - GAE Only, will eventually tell the AI to treat the building like a wall, but currently such a function does not exist, so it just tells the AI not to construct the building.
 * multi-build</tt> - GAE Only, tells the engine you can build multiple of this building at once by dragging and dropping the mouse after selecting a build location. Used mainly for walls.
 * multi-select</tt> - GAE Only, an alternative way of telling the engine that this unit can have multi-selected (see multi-selection above).
 * rotated-climb</tt> - MG Only, this will make units rotate when moving on sloped surfaces so that they are parallel to the surface. Meant for units such as tanks, which look unnatural if they do not slope with the ground. Units such as humanoids would generally not use this, as they would stand upright even on slopes.

rotationAllowed
A MegaGlest only element which toggles whether or not the building can be rotated. In GAE, buildings can always be rotated. Unit particle effects will be rotated with the building.

max-unit-count
An MG only feature which, if specified, will limit the maximum number of that unit to the specified number. If the unit count should not be limited, as is the default for most units, exclude the tag completely.

count-unit-death-in-stats
A MegaGlest only feature which, if set to false, will not count a death of this unit for the endgame stats. The tag is optional and defaults to true.

count-unit-production-in-stats
A MegaGlest only feature which, if set to false, will not count a production of this unit for the endgame stats. The tag is optional and defaults to true.

count-unit-kill-in-stats
A MegaGlest only feature which, if set to false, will not count a kill of this unit for the endgame stats. The tag is optional and defaults to true.

count-kill-for-unit-upgrade
A MegaGlest only feature which, if set to false, will not count a kill of this unit for the number of kills of the killing unit. The tag is optional and defaults to true. If its set to false, count-unit-kill-in-stats</tt> is automatically set to false too.

count-in-victory-conditions
A Megaglest only feature which, if set to false, the unit will not have to be killed for the game to be a victory. Normally, the game ends when all units with a be-built</tt> skill are killed.

light-enabled
If true, when night begins, this unit will emit light in the specified color. Color is done with RGB values from 0-1, which specify how much of the color is each hue.

So a unit with a red value of 0.5, a green value of 0, and a blue value of 0.5 will emit a medium strength magenta light.

unit-requirements
The names of any other units that may be required to produce this unit.

upgrade-requirements
The names of any upgrades that may be required to produce this unit.

resource-requirements
The resource cost to produce this unit.

resources-stored
Using the same syntax as resource-requirements above, resources stored is the number of resources that can be stored in this unit. This expands the total maximum storage as shown at the top of the HUD, and also performs the more valuable function of letting units head to it after harvesting that resource.

image
Path to the unit's icon, which will be displayed on the HUD. In Glest, images can be either BMP or TGA. In MegaGlest and GAE, they can be BMP, TGA, JPG, or PNG.

image-cancel
Path to the cancel icon that will be used by the image, which will be displayed at the bottom of the unit box on the HUD, for canceling their current action (upgrades specify their own cancel icon in the Upgrade XML). In Glest, images can be either BMP or TGA. In MegaGlest and GAE, they can be BMP, TGA, JPG, or PNG.

meeting-point
If true, a meeting point will be used, which is a selectable location that produced units will be sent to. Generally only given to buildings because otherwise the right click "hotkey" is used for move. The path is the icon that can be used to choose the meeting point location. In Glest, images can be either BMP or TGA. In MegaGlest and GAE, they can be BMP, TGA, JPG, or PNG.

selection-sounds
If true, the following list of sounds can be played when the unit is selected, at random. Path links to a relative path to the sound file. Sound files in Glest can be either WAV or OGG.

command-sounds
If true, the following list of sounds can be played when the unit is given a command, at random. Path links to a relative path to the sound file. Sound files in Glest can be either WAV or OGG.

tags
Tags are a GAE only implementation which allows units to be assigned to a "group". You could then use those to perform affects only to units with that specific tag. For example, it's possible to have an upgrade affect only units with that specific tag. As well, effects and emanations can be set to apply only to specific tagged units.

As a result, you could tag all melee units with a tag named "melee", and have an effect that boosts only the attack strength of melee units. Or you could tag a unit as a "building" to have an effect that only affects buildings.

emanations
Emanations are special effects that "emit" from the unit, such as a healing aura which may heal nearby allied units, or an intimidation emanation, which might reduce the stats of nearby enemies.

subfaction-restrictions
Limits the unit to the listed subfactions, which must have been declared in the Faction XML, with the exception of base</tt>, which refers to the faction when there is no subfactions.

skills
Skills define the abilities of a unit, and are generally used with commands to provide actions that the unit can perform, but sometimes mandate automated events too, such as the death skill, which fires every time the unit dies.

commands
Commands are the actions that a unit can be given. Unlike skills, which are called by commands, commands are directly the result of user interaction. For example, an attack command can be called by the player to issue an attack on the foe. All commands require some types of skills, which they use to find information like speed or the model.