Game API — Facts

This page mirrors the Facts block in BindGameAPI(). Most facts read game state and should be called from Init, Update, Render, or End while the match or end-state is available. Tournament Mode applies to game commands, not these read-only APIs.

Game must be running

Calling these APIs before the game starts logs an error.

Lua signatures are strict

Pass every argument shown below. A C++ default value does not make the parameter optional in Lua unless a separate overload is bound.

Reference

Function	Signature	Returns	Description
`GetFact`	`(fact)`	`number`	Overload: returns a fact value for the assigned player with parameter `0`.
`GetFact`	`(fact, parameter)`	`number`	Returns a fact value for the assigned player.
`IsObjectTypeAvailable`	`(unitObjectType)`	`boolean`	Returns whether the assigned player currently has access to a unit or building type.
`GetUnitTypeCount`	`(unitId)`	`number`	Returns the assigned player's count for a unit type.
`GetAttribute`	`(attribute)`	`number`	Returns a `PlayerAttribute` value for the assigned player.
`CanAfford`	`(unitId, isBuilding)`	`boolean`	Returns whether the assigned player meets the item's resource and population cost. Availability is queried separately.
`GetTechCost`	`(technology)`	`{ resourceId = ResourceType, amount = number }[]`	Returns the assigned player's current technology cost entries.
`GetObjectCost`	`(unitObjectType)`	`{ resourceId = ResourceType, amount = number }[]`	Returns the assigned player's current object cost entries with multiplier `1.0`.
`GetObjectCost`	`(unitObjectType, costMultiplier)`	`{ resourceId = ResourceType, amount = number }[]`	Returns the assigned player's current object cost entries with the given multiplier applied.
`CanResearch`	`(technology)`	`boolean`	Returns whether the assigned player can currently research a technology.
`IsTechnologyResearched`	`(technology)`	`boolean`	Returns whether the assigned player has researched a technology.
`GetObjectsByType`	`(unitType)`	`Object[]`	Returns matching world objects, not just owned objects. Loot-bearing dead huntables and livestock are included.
`GetObjectsByTypes`	`(unitTypes)`	`Object[]`	Returns matching world objects for any listed type. Loot-bearing dead huntables and livestock are included.
`GetObjectsByClass`	`(unitClass)`	`Object[]`	Returns matching world objects of a class, not just owned objects. Loot-bearing dead huntables and livestock are included.
`GetGameTime`	`()`	`number`	Returns the current match time in seconds.
`GetAllChatMessages`	`()`	`string[]`	Returns the current chat buffer as plain message strings.
`GetNewChatMessages`	`()`	`string[]`	Returns chat messages that became visible since this module instance last called the function.
`GetLastChatMessage`	`()`	`string \\| nil`	Returns the newest chat message, or `nil` if the chat buffer is empty.
`GetAssignedPlayer`	`()`	`Player`	Returns the player currently assigned to this module instance.
`GetPlayerById`	`(id)`	`Player`	Returns a player by index. Gaia is typically `0`, regular players are typically `1` to `8`.
`GetPlayerCount`	`()`	`number`	Returns the size of the world player list.
`GetMapTilesPtr`	`()`	`number, number`	Returns `(ptr, count)` for a packed tile snapshot owned by the current module instance and load generation. Intended for IPC / RPM readers.
`GetMapWidth`	`()`	`number`	Returns the current map width in tiles.
`GetMapHeight`	`()`	`number`	Returns the current map height in tiles.
`GetMapTile`	`(x, y)`	`MapTile`	Overload: returns the tile at integer map coordinates, or `nil` if out of bounds.
`GetMapTile`	`(position)`	`MapTile`	Overload: floors a `Vector2` world/tile position to a map tile lookup.
`GetAllMapTiles`	`()`	`MapTile[]`	Returns all map tiles. Individual tile methods still respect fog-aware visibility.
`CalculatePath`	`(startPos, targetPos)`	`Vector3[]`	Calculates a native path between two `Vector3` positions.
`CalculatePath`	`(startPos, targetPos, collisionRadius)`	`Vector3[]`	Overload: calculates a native path between two `Vector3` positions with an explicit collision radius.
`GetObjectsInArea`	`(pos1, pos2)`	`Object[]`	Returns objects whose current tile lies inside the rectangular area between two `Vector2` positions. Loot-bearing dead huntables and livestock are included.
`GetObjectsPtr`	`()`	`number, number`	Returns `(ptr, count)` for a packed object snapshot owned by the current module instance and load generation. Intended for IPC / RPM readers.
`GetObjectTypeData`	`(objectTypeId, objectData)`	`number`	Returns game-resolved object-type data for a `UnitObjectType` and `ObjectData` field.
`GetObjectTypeAttribute`	`(objectTypeId, objectAttribute, damageType)`	`number`	Returns a game-resolved object-type attribute value for a `UnitObjectType`.
`IsEnemyPlayer`	`(player)`	`boolean`	Returns whether the given player is an enemy of the assigned player.
`GetObjectById`	`(id)`	`Object`	Returns a world object by id.
`GetProjectileById`	`(id)`	`Object`	Returns a projectile object by id.
`GetAllProjectiles`	`()`	`Object[]`	Returns visible projectile objects.
`GetProjectilesByType`	`(projectileType)`	`Object[]`	Returns projectile objects matching a `ProjectileType`.
`GetVictoryCondition`	`()`	`VictoryCondition`	Returns the current victory condition.
`GetVictoryPlayer`	`()`	`Player`	Returns the winner when the game has ended, otherwise `nil`.

Examples

function Update()
    local assigned = GetAssignedPlayer()
    if not assigned then
        return
    end

    local population = GetFact(Fact.POPULATION, 0)
    local wood = GetAttribute(PlayerAttribute.WOOD)

    if population < 60
        and IsObjectTypeAvailable(UnitObjectType.HOUSE)
        and CanAfford(UnitObjectType.HOUSE, true) then
        Log("Player " .. tostring(assigned:GetId()) .. " has " .. tostring(wood) .. " wood.")
    end
end

function Render()
    for i = 0, GetPlayerCount() - 1 do
        local player = GetPlayerById(i)
        if player and IsEnemyPlayer(player) then
            for _, tc in ipairs(player:GetTownCenters()) do
                RenderObjectBounds(tc, Color(255, 64, 64, 255), 2.0)
            end
        end
    end
end

function Update()
    local tile = GetMapTile(40, 40)
    if not tile then
        return
    end

    if tile:GetTileVisibility() == TileVisibility.VISIBLE then
        Log(
            "Tile 40,40 terrain=" .. tostring(tile:GetTerrain())
            .. " elevation=" .. tostring(tile:GetElevation())
            .. " objects=" .. tostring(tile:GetObjectCount())
        )
    end
end

function Update()
    local path = CalculatePath(Vector3(20, 20, 0), Vector3(60, 60, 0), 0.5)
    Log("Path waypoint count: " .. tostring(#path))
end

function Render()
    for _, projectile in ipairs(GetAllProjectiles()) do
        RenderObjectBounds(projectile, Color(255, 160, 64, 255), 1.0)
    end
end

function Init()
    for _, entry in ipairs(GetTechCost(Technology.LOOM)) do
        if entry.resourceId == ResourceType.GOLD then
            Log("Loom gold cost: " .. tostring(entry.amount))
        end
    end
end

function Init()
    local villagerHp = GetObjectTypeAttribute(UnitObjectType.VILLAGER_MALE, ObjectAttribute.HITPOINTS, 0)
    local villagerTrainTime = GetObjectTypeData(UnitObjectType.VILLAGER_MALE, ObjectData.CREATION_TIME)

    Log("Villager HP=" .. tostring(villagerHp) .. ", train time=" .. tostring(villagerTrainTime))
end

Notes

Use GetAssignedPlayer(), not GetLocalPlayer().
GetAssignedPlayerId() is documented on the control page because it is bound under the engine section and is also available in Load(playerId).
GetObjectsByType, GetObjectsByTypes, and GetObjectsByClass scan world objects, not only the assigned player's objects. Loot-bearing dead huntables and livestock are included, and explored animals or resources can still be returned outside active vision.
GetMapTile(position) floors position.x and position.y to integer tile coordinates before resolving the tile.
CalculatePath() uses the game's native pathfinding, accepts Vector3 start and target positions, and returns an empty list when no path is available.
GetObjectsInArea(pos1, pos2) uses the same object filter as the other scan APIs. Loot-bearing dead huntables and livestock are included, and fog-aware visibility still applies.
GetTechCost() and GetObjectCost() return arrays of resource-cost entries. Use entry.resourceId and entry.amount; numeric indexes entry[1] and entry[2] mirror the same values.
GetAllChatMessages() and GetLastChatMessage() read from the game's current chat buffer.
GetNewChatMessages() tracks unread chat state per module instance. On the first call after load or reload, it returns the currently visible buffer.
Projectile lookup functions return normal Object references whose ObjectType is ObjectType.PROJECTILE and follow the same visibility restrictions as other object queries.
Treat Object, Player, and MapTile userdata as callback-scoped views. Retaining these userdata values across Load, Init, Update, Render, or End callbacks is deprecated: synchronous mode may expose a mutable game-owned pointer, while snapshot-backed mode exposes immutable point-in-time data that can become stale. Retain stable value data such as an object/player ID or position, then query the current callback again before reading state or issuing a command. Commands re-resolve IDs against the current world generation and reject stale or unavailable targets.
When Modules See Everything is disabled, object retrieval functions follow the assigned player's fog-of-war with one exception: explored animals and resources can still be returned. On those non-visible references, only IsVisible(), IsExplored(), GetId(), GetPosition(), GetClass(), and GetUnitObjectType() are safe.
When Modules See Everything is disabled, player-state access through GetPlayerById() is limited. Resource, fact, tech, and object-availability methods only expose the assigned player's data.
GetAllMapTiles() returns the full map grid, but MapTile methods only expose what the assigned player is currently allowed to know.
GetMapTilesPtr() and GetObjectsPtr() return engine-owned buffers rebuilt on demand. Every buffer requested by one module instance during a callback remains stable through that callback; another module instance cannot invalidate it. The engine currently retains the last requested set until that same instance requests another snapshot or unloads, but external readers should copy it before that boundary. The second return value is an element count, not a byte count; an empty snapshot is (0, 0).
GetObjectsPtr() is dead-inclusive. Read the alive state from the snapshot flags instead of assuming every entry is alive.
The snapshot helpers are primarily intended for IPC / external ML readers that want to transfer compact RPM-friendly buffers. See the IPC page for the exact packed C++ layouts.
CanAfford(unitId, isBuilding) forwards the isBuilding flag to the engine affordability helper. It intentionally does not imply IsObjectTypeAvailable(unitId); check both before issuing a train/build command.