An "entity" in 0 A.D.'s terminology is the internal representation of a game object. It could be a unit, structure, tree, or even a decorative actor like a clump of grass. A map contains a number of these entities which describe the world as the players perceive it. Entities are also created during the game when a player trains a new unit or constructs a building, they are similarly destroyed when a unit or structure is destroyed. For an entity to be visible in the game, it must have a visual actor associated with it.
Entities can be viewed in-game or for testing purposes, using Atlas' actor viewer in entity mode.
For more information on how entities fit into the game's architecture, see SimulationArchitecture.
Many but not all entities are defined by entity templates, located in simulation\templates\ (see mod layout). An entity template is an XML data file which defines how the entity behaves, how it appears, its internal state, and how other entities may interact with it. This data is associated with simulation components (see this page for component examples).
Entity templates use inheritance, which allows different types of units to inherit common attributes from a parent. For example, a Roman Veles inherits from a common "ranged infantry javelinist" template, which inherits from a common "ranged infantry" template, and so on. This inheritance helps prevent duplication of the same data in numerous places.
Certain decorative actors like grass clumps have no entity template associated with them, as they don't interact with the game world. However the engine still constructs an entity for them with only minimal properties. See our map data format for more information.
Currently there is no special editor for entity templates (as there is for actors), so it's best to use a decent text editor like Notepad++ on Windows. Existing entity templates can be used as examples, along with the entity documentation.
There are also special entities which are not in the same category as units and structures. Players are considered to be entities in the game, as are formations. There is a so-called "system entity" which is created at the start of a game, it's associated with certain global components like player manager and territory manager, which are not part of a single game entity or player.
Entity XML format
The following is an example of an entity template XML file:
<?xml version="1.0" encoding="utf-8"?> <Entity parent="template_unit"> <Cost> <BuildTime>15</BuildTime> </Cost> <Health> <RegenRate>0.2</RegenRate> </Health> <Identity> <GenericName>Support</GenericName> <Classes datatype="tokens">Support Organic</Classes> </Identity> <Loot> <xp>10</xp> <food>1</food> <wood>1</wood> <stone>1</stone> <metal>1</metal> </Loot> <Minimap> <Type>support</Type> </Minimap> <Sound> <SoundGroups> <trained>interface/alarm/alarm_create_worker.xml</trained> </SoundGroups> </Sound> <UnitAI> <DefaultStance>passive</DefaultStance> </UnitAI> </Entity>
It can be seen that this template inherits from "template_unit" (and all of its parents, too).
Entity templates must comply with the schema or they won't validate, causing an error when trying to use the entity in-game or Atlas. Each component adds to the schema those elements which it allows to be specified in the template, as documented here. An element may be required or optional, it may have attributes or not; and its data may be restricted in type, limited to a set of predefined choices, or it may allow arbitrary text.
Typical reasons for a template not validating include:
- leaving out required elements
- adding elements that don't exist in the schema
- using an incorrect data type, like a decimal or negative number in a field that requires a positive integer
Inheritance must be kept in mind here, not every template will explicitly reference every property for a given component. For example a unit might only alter the melee crush value of its parent's Attack, not the whole Attack element.