Entity component documentation

In 0 A.D., entities (units and buildings and other world objects) consist of a collection of components, each of which determines part of the entity's behaviour. Entity template XML files specify the list of components that are loaded for each entity type, plus initialisation data for the components.

This page lists the components that can be added to entities and the XML syntax for their initialisation data.

Available components:

Display RELAX NG grammar fragments

Armour

Controls the damage resistance of the unit.

Example

<Armour>
  <Hack>10.0</Hack>
  <Pierce>0.0</Pierce>
  <Crush>5.0</Crush>
</Armour>

Hack

Hack damage protection.

Value type: non-negative decimal (e.g. 0.0 or 2.5).

Pierce

Pierce damage protection.

Value type: non-negative decimal (e.g. 0.0 or 2.5).

Crush

Crush damage protection.

Value type: non-negative decimal (e.g. 0.0 or 2.5).

RELAX NG Grammar

<element name="Armour">
  <interleave>
    <element name="Hack">
      <ref name="nonNegativeDecimal"/>
    </element>
    <element name="Pierce">
      <ref name="nonNegativeDecimal"/>
    </element>
    <element name="Crush">
      <ref name="nonNegativeDecimal"/>
    </element>
  </interleave>
</element>

Attack

Controls the attack abilities and strengths of the unit.

Example

<Attack>
  <Hack>10.0</Hack>
  <Pierce>0.0</Pierce>
  <Crush>5.0</Crush>
  <MaxRange>10.0</MaxRange>
  <MinRange>0.0</MinRange>
  <PrepareTime>800</PrepareTime>
  <RepeatTime>1600</RepeatTime>
  <ProjectileSpeed>50.0</ProjectileSpeed>
</Attack>

Hack

Hack damage strength.

Value type: non-negative decimal (e.g. 0.0 or 2.5).

Pierce

Pierce damage strength.

Value type: non-negative decimal (e.g. 0.0 or 2.5).

Crush

Crush damage strength.

Value type: non-negative decimal (e.g. 0.0 or 2.5).

MaxRange

Maximum attack range (in metres).

Value type: non-negative decimal (e.g. 0.0 or 2.5).

MinRange

Minimum attack range (in metres).

Value type: non-negative decimal (e.g. 0.0 or 2.5).

PrepareTime

Optional.

Time from the start of the attack command until the attack actually occurs (in milliseconds). This value relative to RepeatTime should closely match the "event" point in the actor's attack animation.

Value type: non-negative integer (e.g. 0 or 5).

RepeatTime

Optional.

Time between attacks (in milliseconds). The attack animation will be stretched to match this time.

Value type: positive integer (e.g. 1 or 5).

ProjectileSpeed

Optional.

Speed of projectiles (in metres per second). If unspecified, then it is a melee attack instead.

Value type: non-negative decimal (e.g. 0.0 or 2.5).

RELAX NG Grammar

<element name="Attack">
  <interleave>
    <element name="Hack">
      <ref name="nonNegativeDecimal"/>
    </element>
    <element name="Pierce">
      <ref name="nonNegativeDecimal"/>
    </element>
    <element name="Crush">
      <ref name="nonNegativeDecimal"/>
    </element>
    <element name="MaxRange">
      <ref name="nonNegativeDecimal"/>
    </element>
    <element name="MinRange">
      <ref name="nonNegativeDecimal"/>
    </element>
    <optional>
      <element name="PrepareTime">
        <data type="nonNegativeInteger"/>
      </element>
    </optional>
    <optional>
      <element name="RepeatTime">
        <data type="positiveInteger"/>
      </element>
    </optional>
    <optional>
      <element name="ProjectileSpeed">
        <ref name="nonNegativeDecimal"/>
      </element>
    </optional>
  </interleave>
</element>

Builder

Allows the unit to construct and repair buildings.

Example

<Builder>
  <Rate>1.0</Rate>
  <Entities>
    structures/{civ}_barracks
    structures/{civ}_civil_centre
    structures/celt_sb1
  </Entities>
</Builder>

Rate

Construction speed multiplier (1.0 is normal speed, higher values are faster).

Value type: positive decimal (e.g. 1.0 or 2.5).

Entities

Space-separated list of entity template names that this unit can build. The special string "{civ}" will be automatically replaced by the unit's four-character civ code.

Value type: text.

RELAX NG Grammar

<element name="Builder">
  <interleave>
    <element name="Rate">
      <ref name="positiveDecimal"/>
    </element>
    <element name="Entities">
      <text/>
    </element>
  </interleave>
</element>

Cost

Specifies the construction/training costs of this entity.

Example

<Cost>
  <Population>1</Population>
  <PopulationBonus>15</PopulationBonus>
  <BuildTime>20.0</BuildTime>
  <Resources>
    <food>50</food>
    <wood>0</wood>
    <stone>0</stone>
    <metal>25</metal>
  </Resources>
</Cost>

Population

Optional.

Population cost.

Value type: non-negative integer (e.g. 0 or 5).

PopulationBonus

Optional.

Population cap increase while this entity exists.

Value type: non-negative integer (e.g. 0 or 5).

BuildTime

Optional.

Time taken to construct/train this unit (in seconds).

Value type: positive decimal (e.g. 1.0 or 2.5).

Resources

Resource costs to construct/train this unit.

food

Value type: non-negative integer (e.g. 0 or 5).

wood

Value type: non-negative integer (e.g. 0 or 5).

stone

Value type: non-negative integer (e.g. 0 or 5).

metal

Value type: non-negative integer (e.g. 0 or 5).

RELAX NG Grammar

<element name="Cost">
  <interleave>
    <optional>
      <element name="Population">
        <data type="nonNegativeInteger"/>
      </element>
    </optional>
    <optional>
      <element name="PopulationBonus">
        <data type="nonNegativeInteger"/>
      </element>
    </optional>
    <optional>
      <element name="BuildTime">
        <ref name="positiveDecimal"/>
      </element>
    </optional>
    <element name="Resources">
      <interleave>
        <element name="food">
          <data type="nonNegativeInteger"/>
        </element>
        <element name="wood">
          <data type="nonNegativeInteger"/>
        </element>
        <element name="stone">
          <data type="nonNegativeInteger"/>
        </element>
        <element name="metal">
          <data type="nonNegativeInteger"/>
        </element>
      </interleave>
    </element>
  </interleave>
</element>

Footprint

Approximation of the entity's shape, for collision detection and outline rendering. Shapes are flat horizontal squares or circles, extended vertically to a given height.

Examples

<Footprint>
  <Square width="3.0" height="3.0"/>
  <Height>0.0</Height>
</Footprint>

<Footprint>
  <Circle radius="0.5"/>
  <Height>0.0</Height>
</Footprint>

Square

Set the footprint to a square of the given size.

width

Size of the footprint along the left/right direction (in metres).

Value type: positive decimal (e.g. 1.0 or 2.5).

depth

Size of the footprint along the front/back direction (in metres).

Value type: positive decimal (e.g. 1.0 or 2.5).

Circle

Set the footprint to a circle of the given size.

radius

Radius of the footprint (in metres).

Value type: positive decimal (e.g. 1.0 or 2.5).

Height

Vertical extent of the footprint (in metres).

Value type: non-negative decimal (e.g. 0.0 or 2.5).

RELAX NG Grammar

<element name="Footprint">
  <interleave>
    <choice>
      <element name="Square">
        <attribute name="width">
          <ref name="positiveDecimal"/>
        </attribute>
        <attribute name="depth">
          <ref name="positiveDecimal"/>
        </attribute>
      </element>
      <element name="Circle">
        <attribute name="radius">
          <ref name="positiveDecimal"/>
        </attribute>
      </element>
    </choice>
    <element name="Height">
      <ref name="nonNegativeDecimal"/>
    </element>
  </interleave>
</element>

Health

Deals with hitpoints and death.

Example

<Health>
  <Max>100</Max>
  <RegenRate>1.0</RegenRate>
  <DeathType>corpse</DeathType>
</Health>

Max

Maximum hitpoints.

Value type: positive integer (e.g. 1 or 5).

Initial

Optional.

Initial hitpoints. Default if unspecified is equal to Max.

Value type: positive integer (e.g. 1 or 5).

RegenRate

Optional.

Hitpoint regeneration rate per second. Not yet implemented.

Value type: positive decimal (e.g. 1.0 or 2.5).

DeathType

Graphical behaviour when the unit dies.

Value is one of:

vanish
Disappear instantly.
corpse
Turn into a corpse.

RELAX NG Grammar

<element name="Health">
  <interleave>
    <element name="Max">
      <data type="positiveInteger"/>
    </element>
    <optional>
      <element name="Initial">
        <data type="positiveInteger"/>
      </element>
    </optional>
    <optional>
      <element name="RegenRate">
        <ref name="positiveDecimal"/>
      </element>
    </optional>
    <element name="DeathType">
      <choice>
        <value>vanish</value>
        <value>corpse</value>
      </choice>
    </element>
  </interleave>
</element>

Identity

Specifies various names and values associated with the unit type, typically for GUI display to users.

Example

<Identity>
  <Civ>hele</Civ>
  <GenericName>Infantry Spearman</GenericName>
  <SpecificName>Hoplite</SpecificName>
  <IconCell>3</IconCell>
  <IconSheet>PortraitSheet</IconSheet>
</Identity>

Civ

Civilisation that this unit is primarily associated with.

Value is one of:

gaia
Gaia (world objects).
cart
Carthaginians.
celt
Celts.
hele
Hellenes.
iber
Iberians.
pers
Persians.
rome
Romans.

GenericName

Generic English-language name for this class of unit.

Value type: text.

SpecificName

Optional.

Specific native-language name for this unit type.

Value type: text.

IconCell

Value type: non-negative integer (e.g. 0 or 5).

IconSheet

Value type: text.

RELAX NG Grammar

<element name="Identity">
  <interleave>
    <element name="Civ">
      <choice>
        <value>gaia</value>
        <value>cart</value>
        <value>celt</value>
        <value>hele</value>
        <value>iber</value>
        <value>pers</value>
        <value>rome</value>
      </choice>
    </element>
    <element name="GenericName">
      <text/>
    </element>
    <optional>
      <element name="SpecificName">
        <text/>
      </element>
    </optional>
    <element name="IconCell">
      <data type="nonNegativeInteger"/>
    </element>
    <element name="IconSheet">
      <text/>
    </element>
  </interleave>
</element>

Obstruction

Causes this entity's footprint to obstruct the motion of other units.

Example

<Obstruction/>

Inactive

Optional.

If this element is present, this entity will be ignored in collision tests by other units but can still perform its own collision tests.

RELAX NG Grammar

<element name="Obstruction">
  <interleave>
    <optional>
      <element name="Inactive">
        <empty/>
      </element>
    </optional>
  </interleave>
</element>

Ownership

Allows this entity to be owned by players.

Example

<Ownership/>

RELAX NG Grammar

<element name="Ownership">
  <interleave>
    <empty/>
  </interleave>
</element>

Position

Allows this entity to exist at a location (and orientation) in the world, and defines some details of the positioning.

Example

<Position>
  <Anchor>upright</Anchor>
  <Altitude>0.0</Altitude>
  <Floating>false</Floating>
</Position>

Anchor

Automatic rotation to follow the slope of terrain.

Value is one of:

upright
Always stand straight up.
pitch
Rotate backwards and forwards to follow the terrain.
pitch-roll
Rotate in all direction to follow the terrain.

Altitude

Height above terrain in metres.

Value type: decimal (e.g. -10.0 or 0.0 or 2.5).

Floating

Whether the entity floats on water.

Value type: boolean (true or false).

RELAX NG Grammar

<element name="Position">
  <interleave>
    <element name="Anchor">
      <choice>
        <value>upright</value>
        <value>pitch</value>
        <value>pitch-roll</value>
      </choice>
    </element>
    <element name="Altitude">
      <data type="decimal"/>
    </element>
    <element name="Floating">
      <data type="boolean"/>
    </element>
  </interleave>
</element>

ResourceGatherer

Lets the unit gather resources from entities that have the ResourceSupply component.

Example

<ResourceGatherer>
  <BaseSpeed>1.0</BaseSpeed>
  <Rates>
    <food.fish>1</food.fish>
    <metal>3</metal>
    <stone>3</stone>
    <wood>2</wood>
  </Rates>
</ResourceGatherer>

BaseSpeed

Base resource-gathering rate (in resource units per second).

Value type: positive decimal (e.g. 1.0 or 2.5).

Rates

Per-resource-type gather rate multipliers. If a resource type is not specified then it cannot be gathered by this unit.

food

Optional.

Food gather rate (may be overridden by "food.*" subtypes).

Value type: positive decimal (e.g. 1.0 or 2.5).

wood

Optional.

Wood gather rate.

Value type: positive decimal (e.g. 1.0 or 2.5).

stone

Optional.

Stone gather rate.

Value type: positive decimal (e.g. 1.0 or 2.5).

metal

Optional.

Metal gather rate.

Value type: positive decimal (e.g. 1.0 or 2.5).

food.fish

Optional.

Fish gather rate (overrides "food").

Value type: positive decimal (e.g. 1.0 or 2.5).

food.fruit

Optional.

Fruit gather rate (overrides "food").

Value type: positive decimal (e.g. 1.0 or 2.5).

food.grain

Optional.

Grain gather rate (overrides "food").

Value type: positive decimal (e.g. 1.0 or 2.5).

food.meat

Optional.

Meat gather rate (overrides "food").

Value type: positive decimal (e.g. 1.0 or 2.5).

food.milk

Optional.

Milk gather rate (overrides "food").

Value type: positive decimal (e.g. 1.0 or 2.5).

RELAX NG Grammar

<element name="ResourceGatherer">
  <interleave>
    <element name="BaseSpeed">
      <ref name="positiveDecimal"/>
    </element>
    <element name="Rates">
      <interleave>
        <optional>
          <element name="food">
            <ref name="positiveDecimal"/>
          </element>
        </optional>
        <optional>
          <element name="wood">
            <ref name="positiveDecimal"/>
          </element>
        </optional>
        <optional>
          <element name="stone">
            <ref name="positiveDecimal"/>
          </element>
        </optional>
        <optional>
          <element name="metal">
            <ref name="positiveDecimal"/>
          </element>
        </optional>
        <optional>
          <element name="food.fish">
            <ref name="positiveDecimal"/>
          </element>
        </optional>
        <optional>
          <element name="food.fruit">
            <ref name="positiveDecimal"/>
          </element>
        </optional>
        <optional>
          <element name="food.grain">
            <ref name="positiveDecimal"/>
          </element>
        </optional>
        <optional>
          <element name="food.meat">
            <ref name="positiveDecimal"/>
          </element>
        </optional>
        <optional>
          <element name="food.milk">
            <ref name="positiveDecimal"/>
          </element>
        </optional>
      </interleave>
    </element>
  </interleave>
</element>

ResourceSupply

Provides a supply of one particular type of resource.

Example

<ResourceSupply>
  <Amount>1000</Amount>
  <Type>food.meat</Type>
</ResourceSupply>

Amount

Amount of resources available from this entity.

Value type: non-negative integer (e.g. 0 or 5).

Type

Type of resources.

Value is one of:

wood
stone
metal
food.fish
food.fruit
food.grain
food.meat
food.milk

RELAX NG Grammar

<element name="ResourceSupply">
  <interleave>
    <element name="Amount">
      <data type="nonNegativeInteger"/>
    </element>
    <element name="Type">
      <choice>
        <value>wood</value>
        <value>stone</value>
        <value>metal</value>
        <value>food.fish</value>
        <value>food.fruit</value>
        <value>food.grain</value>
        <value>food.meat</value>
        <value>food.milk</value>
      </choice>
    </element>
  </interleave>
</element>

Selectable

Allows this entity to be selected by the player.

Example

<Selectable/>

RELAX NG Grammar

<element name="Selectable">
  <interleave>
    <empty/>
  </interleave>
</element>

Sound

Lists the sound groups associated with this unit.

Example

<Sound>
  <SoundGroups>
    <walk>actor/human/movement/walk.xml</walk>
    <run>actor/human/movement/walk.xml</run>
    <attack>attack/weapon/sword.xml</attack>
    <death>actor/human/death/death.xml</death>
  </SoundGroups>
</Sound>

SoundGroups

RELAX NG Grammar

<element name="Sound">
  <interleave>
    <element name="SoundGroups">
      <zeroOrMore>
        <element>
          <anyName/>
          <text/>
        </element>
      </zeroOrMore>
    </element>
  </interleave>
</element>

TrainingQueue

Allows the building to train new units.

Example

<TrainingQueue>
  <Entities>
    units/{civ}_support_female_citizen
    units/{civ}_support_trader
    units/celt_infantry_spearman_b
  </Entities>
</TrainingQueue>

Entities

Space-separated list of entity template names that this building can train. The special string "{civ}" will be automatically replaced by the building's four-character civ code.

Value type: text.

RELAX NG Grammar

<element name="TrainingQueue">
  <interleave>
    <element name="Entities">
      <text/>
    </element>
  </interleave>
</element>

UnitAI

Controls the unit's movement, attacks, etc, in response to commands from the player.

Example

<UnitAI/>

RELAX NG Grammar

<element name="UnitAI">
  <interleave>
    <empty/>
  </interleave>
</element>

UnitMotion

Provides the unit with the ability to move around the world by itself.

Example

<UnitMotion>
  <WalkSpeed>7.0</WalkSpeed>
</UnitMotion>

WalkSpeed

Basic movement speed (in metres per second).

Value type: positive decimal (e.g. 1.0 or 2.5).

RELAX NG Grammar

<element name="UnitMotion">
  <interleave>
    <element name="WalkSpeed">
      <ref name="positiveDecimal"/>
    </element>
  </interleave>
</element>

VisualActor

Display the unit using the engine's actor system.

Examples

<VisualActor>
  <Actor>units/hellenes/infantry_spearman_b.xml</Actor>
</VisualActor>

<VisualActor>
  <Actor>structures/hellenes/barracks.xml</Actor>
  <FoundationActor>structures/fndn_4x4.xml</FoundationActor>
</VisualActor>

Actor

Filename of the actor to be used for this unit.

Value type: text.

FoundationActor

Optional.

Filename of the actor to be used the foundation while this unit is being constructed.

Value type: text.

Foundation

Optional.

Used internally; if present the unit will be rendered as a foundation.

RELAX NG Grammar

<element name="VisualActor">
  <interleave>
    <element name="Actor">
      <text/>
    </element>
    <optional>
      <element name="FoundationActor">
        <text/>
      </element>
    </optional>
    <optional>
      <element name="Foundation">
        <empty/>
      </element>
    </optional>
  </interleave>
</element>