View source for XML/Unit

{{XMLs}}
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.

{{TOC limit|2}}

==XML==
{{XML_definition_header}}
<syntaxhighlight lang="xml">
<?xml version="1.0" standalone="no" ?>
<unit>
	<parameters>
		<size value="2" />
		<height value="2" />
		<!-- Start MG Only -->
		<target-height value="2" />
		<burn-height value="2" />
		<!-- End MG Only -->
		<max-hp value="800" regeneration="2" />
		<max-ep value="100" regeneration="5" />
		<armor value="20" />
		<armor-type value="organic" />
		<sight value="15" />
		<time value="100" />
		<multi-selection value="false" />
		<cellmap value="true" allowEmpty="false">
			<row value="10" />
			<row value="01" />
		</cellmap>
		<levels>
			<level name="level_name" kills="3" />
		</levels>
		<fields>
			<field value="land" />
		</fields>
		<properties>
			<property value="burnable" />
			<!-- Start MG Only -->
			<property value="rotated_climb" />
			<!-- End MG Only -->
		</properties>
		<!-- Start MG Only -->
		<rotationAllowed value="false" />
		<max-unit-count value="10" />
		<damage-particles value="true">
			<particle-file path="damage_particles.xml" />
			<particle-file path="damage2_particles.xml" />
		</damage-particles>
		<count-unit-death-in-stats value="true" />
		<count-unit-production-in-stats value="true" />
		<count-unit-kill-in-stats value="true" />
		<count-kill-for-unit-upgrade value="true" />
		<count-in-victory-conditions value="true"/>
		<!-- End MG Only -->
		<light enabled="true" red="0.1" green="0.1" blue="0.3" />
		<unit-requirements>
			<unit name="unit_name" />
		</unit-requirements>
		<upgrade-requirements>
			<upgrade name="upgrade_name" />
		</upgrade-requirements>
		<resource-requirements>
			<resource name="resource_name" amount="50" />
		</resource-requirements>
		<resources-stored>
			<resource name="resource_name" amount="50" />
		</resources-stored>
		<image path="images/image.bmp" />
		<image-cancel path="images/cancel.bmp" />
		<meeting-point value="true" image-path="images/meeting_point.bmp" />
		<selection-sounds enabled="true">
			<sound path="sound/selection_sound.wav" />
		</selection-sounds>
		<command-sounds enabled="true">
			<sound path="sound/command_sound.wav" />
		</command-sounds>
		<tags>
			<tag value="tag_name"/>
		</tags>
	</parameters>
	<skills>

		<!-- See section: skills -->

	</skills>
	<commands>

		<!-- See section: commands -->

	</commands>
</unit>
</syntaxhighlight>

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

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

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

<math>\text{World Frames} = \text{Time} \times floor\left(\frac{1}{\frac{\text{speed}}{4000} + 1}\right)</math>

===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 <tt>&lt;cellmap value="false" /&gt;</tt>). 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 <tt>allowEmpty</tt> 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 <tt>true</tt> (eg, <tt>&lt;cellmap value="true" allowEmpty="true" /&gt;</tt>).

===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]], [[GAE/Custom_levels|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 <tt>defaults</tt> 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 <tt>land</tt> and <tt>air</tt>. 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 <tt>any_water</tt> (deep or shallow water), <tt>deep_water</tt> (only the deep areas that land units cannot enter), or <tt>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.
*<tt>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%.
*<tt>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, <tt>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 <tt>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 XML|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 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 [[XML/Upgrades|upgrade]] affect only units with that specific tag.

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.

Tags are defined in a the parameter node of the unit xml. and are used by adding exstra tag lines in skills.

===subfaction-restrictions===
{{See|GAE/Subfactions}}
Limits the unit to the listed [[GAE/Subfactions|subfactions]], which must have been declared in the [[Faction XML]], with the exception of <tt>base</tt>, which refers to the faction when there is no subfactions.

===skills===
{{See|XML/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===
{{See|XML/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.

==See also==
*[[XMLs]]
<!-- Place links to skills and commands here, once they are created -->
[[Category:XMLs]]