Lua values and game objects¶

The API returns Lua tables for vectors and colors. It returns Object, Player, and MapTile values for live game data.

Call methods with :. The colon passes the value to its method.

local player = GetAssignedPlayer()
if player ~= nil and player:GetId() > 0 then
    LogInfo(player:GetPlayerName())
end

Vectors¶

Constructor	Result
`Vector2(x, y)`	`{ x, y }` with distance methods.
`Vector3(x, y[, z = 0])`	`{ x, y, z }` with distance methods.
`Vector4(value)`	`{ x, y, z, w }` with every component set to `value`.
`Vector4([x[, y[, z[, w]]]])`	Four-component vector. Missing components are `0`.

Each vector has these methods:

Method	Result
`left:Distance(right)`	Three-dimensional Euclidean distance. Missing `z` is `0`.
`left:Distance2D(right)`	Two-dimensional Euclidean distance.

You can pass a plain { x = ..., y = ... } table to a position command. Use a vector constructor when you need its distance methods.

Colors¶

Color returns { r, g, b, a } tables.

Call	Result
`Color()`	Opaque white.
`Color(r[, g[, b[, a]]])`	Numeric color channels.
`Color("#RRGGBB")`	Opaque RGB color.
`Color("#RRGGBBAA")`	RGBA color.
`Color("0xAARRGGBB")`	ARGB color.
`Color.Parse(text)`	Parse a hex color.
`Color.HSV(h, s, v[, a = 255])`	Convert an HSV color.

Color.HSV accepts hue in 0..1 or degrees. Saturation and value use 0..1. When every color channel is in 0..1, drawing functions scale them to 0..255. Use one channel convention in a script.

Object¶

An Object is a live game entity. Get one from a query or from a Player. Do not construct an Object yourself.

Method	Result	Meaning
GetId()	Integer	Object ID, or `0`.
GetName()	String	Readable object name.
GetInternalName()	String	Technical object name.
GetMasterName()	String	Master object name.
GetObjectType()	Integer	`1` for a building, `2` for a unit, or `0`.
GetOwningPlayer()	`Player` or `nil`	Current owner.
GetGarrisonObject()	`Object` or `nil`	Related garrison object.
GetGarrisonCount()	Integer or `nil`	Garrison count.
IsGarrisoned()	Boolean or `nil`	Garrison state.
GetUnitObjectType()	Integer	Game object type.
GetClass()	Integer	Unit class.
GetHitpoints()	Number	Current hitpoints.
GetMaxHitpoints()	Number	Maximum hitpoints.
GetPosition()	`Vector3` or `nil`	Current world position.
GetCurrentMapTile()	`MapTile` or `nil`	Current map tile.
GetBuildStatus()	Integer	Build state.
GetProductionQueueCount()	Integer or `nil, reason`	Total remaining quantity across verified native batches, including the current batch. Zero means a successfully read empty queue. Unavailable or changing data returns nil and a reason.
GetProductionQueue()	Batch array or `nil, reason`	Building production batches in native order. Each entry has `kind` (`"unit"` or `"research"`), `typeId`, remaining `quantity`, and string `batchId`. Includes the current batch. Empty queue returns `{}`; unavailable or changing data returns nil and a reason.
GetCarriedResourceType()	Integer	Resource type, or `-1`.
GetCarriedResourceAmount()	Number	Carried resource amount.
GetAttribute(attribute[, damageClass = 0])	Number or `nil`	Object attribute.
GetObjectData(dataId)	Integer	Object data, or `0`.
GetTargetPosition()	`Vector3` or `nil`	Current target position.
GetActionTargetPosition()	`Vector3` or `nil`	Alias for target position.
GetTargetObject()	`Object` or `nil`	Current target object.
GetActionType()	Integer or `nil`	Current action type.
GetSubActionType()	Integer or `nil`	Current subaction type.
IsNativeIdle()	Boolean / nil	Native action/substate idle predicate with the native boolean flag enabled (as used by idle selection). Returns nil if the object, verified callee signature, or live read is unavailable. Unlike `IsIdle()`, an attached action can still be idle.
IsIdle()	Boolean	General idle check.
IsMoving()	Boolean	General movement check.
IsAlive()	Boolean	`true` when hitpoints are positive.
IsVisible()	Boolean	Visible to the assigned player.
IsExplored()	Boolean	Visible or explored to the assigned player.

Use ObjectAttribute for attribute and ObjectData for dataId when the enum index supplies a name. IsIdle and IsMoving are general checks. Use the action methods when you need current target information.

GetDirection, IsScouting, GetPath, and CalculatePath are not implemented compatibility methods. See their placeholder returns.

MapTile¶

A MapTile represents one valid map coordinate. Get one with GetMapTile, GetAllMapTiles, or Object:GetCurrentMapTile.

Method	Result	Meaning
GetPosition()	`Vector2`	Integer tile coordinate.
GetTerrain()	Integer	Terrain value, or `-1`.
GetElevation()	Integer	Elevation value, or `0`.
GetTileVisibility()	Integer	`TileVisibility` value.
IsNavigatable()	Boolean	Terrain navigation result.
IsWalkable()	Boolean	Alias for `IsNavigatable`.
`IsBuildable()`	`false`	Not implemented. Placeholder; use `IsNavigatable()` only for its documented navigation check.
GetObjectCount()	Integer	Object count on the tile.
GetObjects()	Object array	Objects on the tile.

Use Terrain and TileVisibility constants for tile values.

Player¶

A Player represents a current game player. Get one with GetAssignedPlayer, GetPlayerById, or Object:GetOwningPlayer.

Method	Result	Meaning
GetId()	Integer	Player ID, or `-1` when the validated ID contract or live player is unavailable.
GetPlayerType()	Integer or nil	Native `PlayerType` value; nil when unavailable.
IsResigned()	Boolean or nil	Live resignation state; nil when its validated member contract or player memory is unavailable.
GetPlayerName()	String or nil	Copied player name; nil when discovery or reading is unavailable. An empty string is a known empty name.
GetCivilizationId()	Integer	Civilization ID.
`GetCivilizationName()`	Empty string	Not implemented. Placeholder; it does not look up a name.
GetColor()	`Color` or nil	Player color; nil if its layout/value is unavailable or outside the supported palette.
GetPlayerObjects()	Object array	Current player objects.
GetTownCenters()	Object array	Current town centers.
GetCameraPosition()	`Vector2`	Current camera position.
`GetMouseHoveredObject()`	`nil`	Not implemented. Placeholder; it does not inspect the cursor.
GetSelectedObject()	`Object` or `nil`	Current selected object.
GetSelectedObjects()	Object array or `nil, reason`	Complete local selection in native order, including objects owned by other players. Empty selection returns an empty array. Unavailable or changing selection returns nil and a reason. Only callable for the local player.
GetSelectedObjectCount()	Integer or nil	Current selection count for the local player; nil when the player or selection query is unavailable.
HasWon()	Boolean	Victory state after a match ends.
IsAlliedWith(other)	Boolean or nil	Directed alliance relation; nil when unavailable. Self and Gaia are distinct from allied.
IsEnemyTo(other)	Boolean or nil	Directed enemy relation; nil when unavailable.
GetAttribute(attribute)	Number or `nil`	Native player attribute; `nil` when unavailable, including the ambiguous native `-1` error sentinel.
GetUnitTypeCount(unitType)	Integer	Completed unit count.
GetUnitTypeCountTotal(unitType)	Integer	Unit count, including incomplete objects.
GetBuildingTypeCount(buildingType)	Integer	Completed building count.
GetBuildingTypeCountTotal(buildingType)	Integer	Building count, including incomplete objects.
GetFact(factId[, parameter = 0])	Integer	Fact value.
IsObjectTypeAvailable(objectType)	Boolean	Object availability.
CanAfford(objectType, isBuilding)	Boolean or `nil`	Exact player-specific object affordability; `nil` when unavailable. The legacy `isBuilding` argument remains accepted.
GetResearchState(technology)	Integer	`ResearchState` value.
GetTechCost(technology)	Cost array, available	Positive cost entries; an empty array with `available=true` means free. Ignore costs when unavailable.
GetObjectCost(objectType[, multiplier = 1])	Cost array, available	Positive cost entries; an empty array with `available=true` means free. Ignore costs when unavailable.
CanAffordResearch(technology)	Boolean or `nil`	Technology affordability; `nil` when costs or resource queries are unavailable.
CanResearch(technology)	Boolean or `nil`	Technology availability; `nil` when required queries fail.
IsTechnologyResearched(technology)	Boolean	Research completion state.
GetObjectsByTypes(types[, ...])	Object array	Objects matching any supplied type.
GetObjectsByMostCommonType(types)	Object array	Objects with the most common supplied type.
GetObjectsByClass(unitClass)	Object array	Objects in one class.
GetObjectsByClassDeadInclusive(unitClass)	Object array	Same result as `GetObjectsByClass`.

Lifetime rule¶

Object and Player values describe live game data. An entity can disappear or change after a callback. Save its ID, then query it again in a later callback. See Write reliable scripts.