# Game objects

This section describes various **game objects** defined by the script interface,
and which are both accepted by functions and returned by them. Changing the
fields of a **game object** has no effect on the game before it is passed to a
function that does something with the **game object**.

## Research

Describes a research item. The following properties are defined:

* ```power``` Number of power points needed for starting the research.
* ```points``` Number of research points needed to complete the research.
* ```started``` A boolean saying whether or not this research has been started by current player or any of its allies.
* ```done``` A boolean saying whether or not this research has been completed.
* ```name``` A string containing the full name of the research.
* ```id``` A string containing the index name of the research.
* ```type``` The type will always be ```RESEARCH_DATA```.
* ```results``` An array of objects of research upgrades (defined in "research.json").

## Structure

Describes a structure (building). It inherits all the properties of the base object (see below).
In addition, the following properties are defined:

* ```status``` The completeness status of the structure. It will be one of ```BEING_BUILT``` and ```BUILT```.
* ```type``` The type will always be ```STRUCTURE```.
* ```cost``` What it would cost to build this structure. (3.2+ only)
* ```direction``` The direction the structure is facing. (4.5+ only)
* ```stattype``` The stattype defines the type of structure. It will be one of ```HQ```, ```FACTORY```, ```POWER_GEN```,
```RESOURCE_EXTRACTOR```, ```LASSAT```, ```DEFENSE```, ```WALL```, ```RESEARCH_LAB```, ```REPAIR_FACILITY```,
```CYBORG_FACTORY```, ```VTOL_FACTORY```, ```REARM_PAD```, ```SAT_UPLINK```, ```GATE```, ```STRUCT_GENERIC```, and ```COMMAND_CONTROL```.
* ```modules``` If the stattype is set to one of the factories, ```POWER_GEN``` or ```RESEARCH_LAB```, then this property is set to the
number of module upgrades it has.
* ```canHitAir``` True if the structure has anti-air capabilities. (3.2+ only)
* ```canHitGround``` True if the structure has anti-ground capabilities. (3.2+ only)
* ```isSensor``` True if the structure has sensor ability. (3.2+ only)
* ```isCB``` True if the structure has counter-battery ability. (3.2+ only)
* ```isRadarDetector``` True if the structure has radar detector ability. (3.2+ only)
* ```range``` Maximum range of its weapons. (3.2+ only)
* ```hasIndirect``` One or more of the structure's weapons are indirect. (3.2+ only)
* ```health``` Percentage that this structure is damaged (where 100 means not damaged at all).

## Feature

Describes a feature (a **game object** not owned by any player). It inherits all the properties of the base object (see below).
In addition, the following properties are defined:
* ```type``` It will always be ```FEATURE```.
* ```stattype``` The type of feature. Defined types are ```OIL_RESOURCE```, ```OIL_DRUM``` and ```ARTIFACT```.
* ```damageable``` Can this feature be damaged?
* ```health``` Percentage that this feature is damaged (where 100 means not damaged at all).

## Droid

Describes a droid. It inherits all the properties of the base object (see below).
In addition, the following properties are defined:

* ```type``` It will always be ```DROID```.
* ```order``` The current order of the droid. This is its plan. The following orders are defined:
  * ```DORDER_ATTACK``` Order a droid to attack something.
  * ```DORDER_MOVE``` Order a droid to move somewhere.
  * ```DORDER_SCOUT``` Order a droid to move somewhere and stop to attack anything on the way.
  * ```DORDER_BUILD``` Order a droid to build something.
  * ```DORDER_HELPBUILD``` Order a droid to help build something.
  * ```DORDER_LINEBUILD``` Order a droid to build something repeatedly in a line.
  * ```DORDER_REPAIR``` Order a droid to repair something.
  * ```DORDER_PATROL``` Order a droid to patrol.
  * ```DORDER_DEMOLISH``` Order a droid to demolish something.
  * ```DORDER_EMBARK``` Order a droid to embark on a transport.
  * ```DORDER_DISEMBARK``` Order a transport to disembark its units at the given position.
  * ```DORDER_FIRESUPPORT``` Order a droid to fire at whatever the target sensor is targeting. (3.2+ only)
  * ```DORDER_COMMANDERSUPPORT``` Assign the droid to a commander. (3.2+ only)
  * ```DORDER_STOP``` Order a droid to stop whatever it is doing. (3.2+ only)
  * ```DORDER_RTR``` Order a droid to return for repairs. (3.2+ only)
  * ```DORDER_RTB``` Order a droid to return to base. (3.2+ only)
  * ```DORDER_HOLD``` Order a droid to hold its position. (3.2+ only)
  * ```DORDER_REARM``` Order a VTOL droid to rearm. If given a target, will go to specified rearm pad. If not, will go to nearest rearm pad. (3.2+ only)
  * ```DORDER_OBSERVE``` Order a droid to keep a target in sensor view. (3.2+ only)
  * ```DORDER_RECOVER``` Order a droid to pick up something. (3.2+ only)
  * ```DORDER_RECYCLE``` Order a droid to factory for recycling. (3.2+ only)
* ```action``` The current action of the droid. This is how it intends to carry out its plan. The
C++ code may change the action frequently as it tries to carry out its order. You never want to set
the action directly, but it may be interesting to look at what it currently is.
* ```droidType``` The droid's type. The following types are defined:
  * ```DROID_CONSTRUCT``` Trucks and cyborg constructors.
  * ```DROID_WEAPON``` Droids with weapon turrets, except cyborgs.
  * ```DROID_PERSON``` Non-cyborg two-legged units, like scavengers.
  * ```DROID_REPAIR``` Units with repair turret, including repair cyborgs.
  * ```DROID_SENSOR``` Units with sensor turret.
  * ```DROID_ECM``` Unit with ECM jammer turret.
  * ```DROID_CYBORG``` Cyborgs with weapons.
  * ```DROID_TRANSPORTER``` Cyborg transporter.
  * ```DROID_SUPERTRANSPORTER``` Droid transporter.
  * ```DROID_COMMAND``` Commanders.
* ```armed``` The percentage of weapon capability that is fully armed. Will be \emph{null} for droids other than VTOLs.
* ```experience``` Amount of experience this droid has, based on damage it has dealt to enemies.
* ```cost``` What it would cost to build the droid. (3.2+ only)
* ```isVTOL``` True if the droid is VTOL. (3.2+ only)
* ```isFlying``` True if the droid is currently flying. (4.6.0+ only)
* ```canHitAir``` True if the droid has anti-air capabilities. (3.2+ only)
* ```canHitGround``` True if the droid has anti-ground capabilities. (3.2+ only)
* ```isSensor``` True if the droid has sensor ability. (3.2+ only)
* ```isCB``` True if the droid has counter-battery ability. (3.2+ only)
* ```isRadarDetector``` True if the droid has radar detector ability. (3.2+ only)
* ```hasIndirect``` One or more of the droid's weapons are indirect. (3.2+ only)
* ```range``` Maximum range of its weapons. (3.2+ only)
* ```body``` The body component of the droid. (3.2+ only)
* ```propulsion``` The propulsion component of the droid. (3.2+ only)
* ```weapons``` The weapon components of the droid, as an array. Contains 'name', 'id', 'armed' percentage and 'lastFired' properties. (3.2+ only)
* ```cargoCapacity``` Defined for transporters only: Total cargo capacity (number of items that will fit may depend on their size). (3.2+ only)
* ```cargoSpace``` Defined for transporters only: Cargo capacity left. (3.2+ only)
* ```cargoCount``` Defined for transporters only: Number of individual \emph{items} in the cargo hold. (3.2+ only)
* ```cargoSize``` The amount of cargo space the droid will take inside a transport. (3.2+ only)
* ```health``` Percentage that this droid is damaged (where 100 means not damaged at all).

## Base Object

Describes a basic object. It will always be a droid, structure or feature, but sometimes the
difference does not matter, and you can treat any of them simply as a basic object. These
fields are also inherited by the droid, structure and feature objects.
The following properties are defined:

* ```type``` It will be one of ```DROID```, ```STRUCTURE``` or ```FEATURE```.
* ```id``` The unique ID of this object.
* ```x``` X position of the object in tiles.
* ```y``` Y position of the object in tiles.
* ```z``` Z (height) position of the object in tiles.
* ```player``` The player owning this object.
* ```selected``` A boolean saying whether 'selectedPlayer' has selected this object.
* ```name``` A user-friendly name for this object.
* ```armour``` Amount of armour points that protect against kinetic weapons.
* ```thermal``` Amount of thermal protection that protect against heat based weapons.
* ```born``` The game time at which this object was produced or came into the world. (3.2+ only)
* ```group``` The group this object is member of. This is a numerical ID. If not a member of any group, will be set to \emph{null}.

## Template

Describes a template type. Templates are droid designs that a player has created.
The following properties are defined:

* ```id``` The ID of this object.
* ```name``` Name of the template.
* ```cost``` The power cost of the template if put into production.
* ```droidType``` The type of droid that would be created.
* ```body``` The name of the body type.
* ```propulsion``` The name of the propulsion type.
* ```brain``` The name of the brain type.
* ```repair``` The name of the repair type.
* ```ecm``` The name of the ECM (electronic counter-measure) type.
* ```construct``` The name of the construction type.
* ```weapons``` An array of weapon names attached to this template.