Class: API3.Entity

[No frames]

new Entity(sharedAI, entity)

Represents a single object (entity) in the game.

In 0AD, each object found on the map of a game is an entity, for example trees, people, animals, buildings. The common properties of a set of entities are laid down in a template. In contrast to an entity template, the query functions of this class consider aura and tech modifications.
Parameters:
sharedAI : API3.SharedScript The common data container which holds the raw engine data.
entity : Object The raw entity description as provided by the pyrogenesis engine.
Source:
Method summary
attack(unitId) → {API3.Entity} Have the entity attack another entity.
canGarrisonInside() → {Boolean} Checks whether any (more) entities may be garrisoned in this entity.
construct(template, x, z, angle) → {API3.Entity} Build a structure at a specific position.
currentGatherRate() → {Number} Retrieves the rate of the entity's current gathering activity.
decaying() → {Boolean} Checks whether the entity is auto-loosing hit points.
deleteAllMetadata(player) Discards all user-defined properties.
deleteMetadata(player, key) Removes a user-defined property from this entity.
destroy() → {API3.Entity} Kills or pulls down this entity.
flee(unitToFleeFrom) → {API3.Entity} Move the entity away from another entity.
footprintRadius() → {Number} Returns the radius of a circle surrounding this entity's footprint.
garrison(target, queued) → {API3.Entity} Have the entity hide itself in another entity.
gather(target, queued) → {API3.Entity} Gather resources from another entity.
getMetadata(player, key) → {Object} Reads a user-defined property from the entity.
getResourceType() → {String} Provides the type of resource to be gathered from this entity type.
healthLevel() → {Number} Retrieves the entity's relative health.
hitpoints() → {Number} Retrieves the entity's current hit points (absolute health).
id() → {Number} Retrieves the id of the entity.
isEnemy(player) → {Boolean} Checks whether this entity is inimicious to entities of a certain player.
isFriendly(player) → {Boolean} Checks whether this entity is friendly (non-attacking) to the entities of a certain player.
isHurt() → {Boolean} Checks whether the entity has already lost some hit points.
isIdle() → {Boolean} Checks whether this entity is without task.
isOwn(player) → {Boolean} Checks whether the entity belongs to a certain player.
isUnhuntable() → {Boolean} Returns whether this is an animal that is too difficult to hunt. (Any non domestic currently.)
moveApart(point, dist) Move the entity away from a given position.
needsHeal() → {Boolean} Checks whether the entity should be tasked to heal.
needsRepair() → {Boolean} Checks whether a builder should be tasked to repair the entity.
obstructionRadius() → {Number} Computes the size of a circular "bounding cylinder" around the entity.
owner() → {Number} Retrieves the player who owns the entity.
position() → {Array.<Number>} Retrieves the current location of the entity on the map.
repair(target, queued) → {API3.Entity} Repair a structure or siege device.
research(template) → {API3.Entity} Research a technology.
resourceCarrying() → {Boolean} Checks whether the entity has been loaded with some resource.
resourceSupplyAmount() → {Number} Retrieves the resources available of this entity.
setMetadata(player, key, value) Creates a new player-dependant property at the entity object.
setStance(stance) → {API3.Entity} Changes the default reaction of the entity towards enemy entities.
stopMoving() Commands the entity to stop at its momentary position.
templateName() → {String} Retrieves the name of the entitie's template.
toString() → {String} Provides a quick overview of the entity for listing it up.
train(type, count) → {API3.Entity} Train some entities from this one.
trainingQueue() → {Array.<Object>} Retrieves the raw training queue state of the entity.
unload(id) → {API3.Entity} Ungarrisons a particular entity from this entity.
unloadAll() → {API3.Entity} Ungarrisons all entities currently garrisoned.

Extends

Methods

attack(unitId) → {API3.Entity}

Have the entity attack another entity.

Parameters:
unitId : Number The numeric id of the entity to attack.
Source:
See:
  • API3.Entity.id
Returns:
The entity itself (for command chaining).
Type
API3.Entity

canGarrisonInside() → {Boolean}

Checks whether any (more) entities may be garrisoned in this entity.

Source:
Returns:
true iff the entity's garrison capacity allows for at least one more entity.
Type
Boolean

construct(template, x, z, angle) → {API3.Entity}

Build a structure at a specific position.

Parameters:
template : String The civilization-qualified template name of the desired structure, e.g. "structures/brit_dock"
x : Number Location of the new structure's center point along the x-direction.
z : Number Location of the new structure's center point along the z-direction.
angle : Number Rotation angle of the structure. To comply with the general 45 degree orientation of buildings in normal game plays, this value should usually be set to 0.75*Math.PI.
Source:
To Do:
  • Describe metadata parameter of construct function.
Returns:
The entity itself (for command chaining).
Type
API3.Entity

currentGatherRate() → {Number}

Retrieves the rate of the entity's current gathering activity.

Source:
Returns:
The resource amount accumulated in one second. If the entity is not gathering at the moment, the function returns undefined.
Type
Number

decaying() → {Boolean}

Checks whether the entity is auto-loosing hit points.

When a structure is built outside a player's territory (i.e. the terrain of that structure has no civic centre inside), the structure will continually loose hit points.
Source:
Returns:
true iff the entity is currently loosing hit points due to being out of the player's territory.
Type
Boolean

deleteAllMetadata(player)

Discards all user-defined properties.

Parameters:
player : Number Numeric id of the player whose extra properties will be removed from the entity.
Source:
See:
  • API3.Entity.getMetadata
Returns:
undefined

deleteMetadata(player, key)

Removes a user-defined property from this entity.

Parameters:
player : Number Numeric id of the player whose extra properties will be modified.
key : String Identifier of the user property to be removed.
Source:
See:
  • API3.Entity.getMetadata
Returns:
undefined

destroy() → {API3.Entity}

Kills or pulls down this entity.

Destruction of the entity is always done immediately, regardless of the queue state.
Source:
Returns:
The entity itself (although no further commands are likely to execute on the entity).
Type
API3.Entity

flee(unitToFleeFrom) → {API3.Entity}

Move the entity away from another entity.

The function draws a line between the entity and the repellent entity. It then instructs the entity to move along the line, away from the repellent.
Parameters:
unitToFleeFrom : API3.Entity The unit to evade.
Source:
Returns:
The entity itself (for command chaining).
Type
API3.Entity

footprintRadius() → {Number}

Returns the radius of a circle surrounding this entity's footprint.
Inherited From:
Source:
Returns:
The radius of the smallest circle the entity's footprint will fit in.
Type
Number

garrison(target, queued) → {API3.Entity}

Have the entity hide itself in another entity.

Parameters:
target : API3.Entity The entity to hide inside.
queued : Boolean States whether the command shall be put into the order queue of the entity. Iff not true, the garrison command is executed immediately.
Source:
Returns:
The entity itself (for command chaining)
Type
API3.Entity

gather(target, queued) → {API3.Entity}

Gather resources from another entity.

Parameters:
target : API3.Entity The entity to gather from.
queued : Boolean States whether the command shall be put into the order queue of the entity. Iff not true, the entity will start gathering immediately.
Source:
Returns:
The entity itself (for command chaining)
Type
API3.Entity

getMetadata(player, key) → {Object}

Reads a user-defined property from the entity.

An AI script may add any value to an entity for administrative purposes, just like any regular object property. This metadata should not be shared with other AI scripts.
Parameters:
player : Number Numeric id of the player whose user properties are queried.
key : String Identifier of the user property to fetch.
Source:
See:
  • API3.Entity.setMetadata
Returns:
An object which has been attached to the entity, or undefined if property with the given key and player-id was defined before.
Type
Object

getResourceType() → {String}

Provides the type of resource to be gathered from this entity type.

Inherited From:
Source:
Returns:
The name of the resource type provided by the entity emplate. Currently these are "food", "metal", "stone", "wood"
Type
String

healthLevel() → {Number}

Retrieves the entity's relative health.

Source:
See:
  • API3.prototype.hitpoints
  • API3.prototype.isHurt
Returns:
A float value in the interval [0,...,1], where 0 indicates death and 1 indicates full health.
Type
Number

hitpoints() → {Number}

Retrieves the entity's current hit points (absolute health).

Source:
To Do:
  • understand why we have sometimes rounding problems with maxHitpoints ? making wrongly isHurt=true problem seems to be with hele civs (i.e. spart)
Returns:
The number of hit points which may be removed from the entity before it is dead.
Type
Number

id() → {Number}

Retrieves the id of the entity.

Source:
Returns:
The id used by the pyrogenesis engine to refer to this entity.
Type
Number

isEnemy(player) → {Boolean}

Checks whether this entity is inimicious to entities of a certain player.

Parameters:
player : Number Numeric id of the player to check.
Source:
To Do:
  • Diplomacy is not considered by this function.
Returns:
true if this entity is likely to attack entities of the specified player.
Type
Boolean

isFriendly(player) → {Boolean}

Checks whether this entity is friendly (non-attacking) to the entities of a certain player.

Parameters:
player : Number Numeric id of the player to check.
Source:
To Do:
  • Diplomacy is not considered by this function.
Returns:
true if this entity will not attack entities of the specified player.
Type
Boolean

isHurt() → {Boolean}

Checks whether the entity has already lost some hit points.

Source:
See:
  • API3.Entity.prototype.healthLevel
  • API3.Entity.prototype.hitpoints
  • API3.Entity.prototype.needsHeal
  • API3.Entity.prototype.needsRepair
Returns:
true iff the entity does not have all of its hitpoints.
Type
Boolean

isIdle() → {Boolean}

Checks whether this entity is without task.

Source:
Returns:
Whether the entity is idle; if the entity state is unknown, it returns undefined.
Type
Boolean

isOwn(player) → {Boolean}

Checks whether the entity belongs to a certain player.

Parameters:
player : Number Numeric id of the player to check.
Source:
Returns:
true if this entity belongs to the player with the given id, so he can control it.
Type
Boolean

isUnhuntable() → {Boolean}

Returns whether this is an animal that is too difficult to hunt. (Any non domestic currently.)
Inherited From:
Source:
Returns:
true iff the entity will flee or counter-attack when hunted.
Type
Boolean

moveApart(point, dist)

Move the entity away from a given position.

The function draws a line between the entities current position and the specified point. It then moves the entity to a point on the line which is dist game meters off the target point. When the entity is on the target point, it is moved off in x-direction.
Parameters:
point : Array.<Number> A two-dimensionl array whose elements give the x- and z-position of the repellent point.
dist : Number The desired distance of the entity from the repellent point.
Source:

needsHeal() → {Boolean}

Checks whether the entity should be tasked to heal.

Some entities might be defined as non-healable (e.g. animals), which makes a difference to isHurt.
Source:
See:
  • API3.Entity.prototype.isHurt
  • API3.Entity.prototype.needsRepair
Returns:
true iff it is possible to heal the entity to full hit points (false if the entity is at full health or unhealable).
Type
Boolean

needsRepair() → {Boolean}

Checks whether a builder should be tasked to repair the entity.

The concept of hit points is used for structures and siege devices as well as for live objects, but the hit point restauration is different.
Source:
Returns:
true iff it is possible to restore the entity to full hit points by repairing (false if the entity is at full health or unrepairable).
Type
Boolean

obstructionRadius() → {Number}

Computes the size of a circular "bounding cylinder" around the entity.

Inherited From:
Source:
Returns:
The radius of a circle surrounding this entity's obstruction shape, or undefined if the entity does not obstruct anything.
Type
Number

owner() → {Number}

Retrieves the player who owns the entity.

Source:
Returns:
The numeric id of the player owning the entity.
Type
Number

position() → {Array.<Number>}

Retrieves the current location of the entity on the map.

Source:
Returns:
A two-dimensional array whose elements give the entity position in x- and z-direction. If the entity is garrisoned, the function returns undefined.
Type
Array.<Number>

repair(target, queued) → {API3.Entity}

Repair a structure or siege device.

Parameters:
target : API3.Entity The entity to repair.
queued : Boolean States whether the command shall be put into the order queue of the entity. Iff not true, the entity will start repairing immediately.
Source:
Returns:
The entity itself (for command chaining).
Type
API3.Entity

research(template) → {API3.Entity}

Research a technology.

Parameters:
template : String The name of the technology to research.
Source:
Returns:
The entity itself (for command chaining).
Type
API3.Entity

resourceCarrying() → {Boolean}

Checks whether the entity has been loaded with some resource.

Source:
Returns:
true iff the entity has gathered some resource which has not yet been disposed at a dropsite.
Type
Boolean

resourceSupplyAmount() → {Number}

Retrieves the resources available of this entity.

Source:
Returns:
The amount of resources which can still be gathered from the entity before it is exhausted. If the entity has no resources, the function returns undefined. For entities with unlimited supply, such as farms, it may return infinite.
Type
Number

setMetadata(player, key, value)

Creates a new player-dependant property at the entity object.

An AI script may add any value to an entity for administrative purposes, just like any regular object property. This metadata should not be shared with other AI scripts.
Parameters:
player : Number Numeric id of the player whose user properties are to be defined.
key : String Identifier of the new user property.
value : Object The object to attach to the entity for later reference.
Source:
Returns:
undefined

setStance(stance) → {API3.Entity}

Changes the default reaction of the entity towards enemy entities.

Parameters:
stance : String The identifier of the new entity stance, allowing "violent", "aggressive", "defensive", "passive" "standground".
Source:
To Do:
  • Link to the 0AD game description of the entity behavior at the various stances.
Returns:
The entity itself (for chaining commands).
Type
API3.Entity

stopMoving()

Commands the entity to stop at its momentary position.

Source:
Returns:
undefined.

templateName() → {String}

Retrieves the name of the entitie's template.

Source:
Returns:
The instanciated name of the entitie's template, e.g. "structures/celt_barracks".
Type
String

toString() → {String}

Provides a quick overview of the entity for listing it up.

Source:
Returns:
The id and template name of this entity.
Type
String

train(type, count) → {API3.Entity}

Train some entities from this one.

Parameters:
type : String The civilization-qualified template name of the desired entity, e.g. "units/athen_infantry_archer".
count : Number Number of entities to train in one batch. For fairness against the human player(s), this should always be 1 or a multiple of 5 (the 0AD GUI does not support arbitrary values).
Source:
To Do:
  • Describe the metadata and promotedTypes parameters.
Returns:
The entity itself (for command chaining)
Type
API3.Entity

trainingQueue() → {Array.<Object>}

Retrieves the raw training queue state of the entity.

Source:
Returns:
The current training queue state, like [ { "id": 0, "template": "...", "count": 1, "progress": 0.5, "metadata": ... }, ... ]
Type
Array.<Object>

unload(id) → {API3.Entity}

Ungarrisons a particular entity from this entity.

Parameters:
id : Number The id of the entity to be ungarrisoned.
Source:
See:
  • API3.Entity.garrison
  • API3.Entity.id
Returns:
The entity itself (for chaining commands).
Type
API3.Entity

unloadAll() → {API3.Entity}

Ungarrisons all entities currently garrisoned.

Although any entities of the player will be ungarrisoned, allied player garrisoned within this entity will not be ungarrisoned by this function.
Source:
Returns:
The entity itself (for command chaining).
Type
API3.Entity