Low-level queries and diagnostics

These APIs expose specialized game data and troubleshooting results. They can change after a WololoLabs or game update. Use the normal reference first.

Check every result. Keep each advanced call in a small function that you can test after an update.

Fact shortcuts

GetFact(factId[, parameter = 0]) reads a fact for the assigned player. Use a Fact constant for factId. It returns value, available, where available is a boolean. An unavailable read returns 0, false; a confirmed zero returns 0, true. Check the flag before using the value. See Query availability for compatibility with existing single-value callers.

These helpers return a numeric value or nil when the value is unavailable.

Call	Parameter
GetCommodityBuyingPrice(resource)	Resource ID.
GetCommoditySellingPrice(resource)	Resource ID.
GetCurrentScore()	None.
GetPlayerInGame(playerId)	Player ID.
GetPlayerDistance(playerId)	Player ID.
GetEnemyBuildingsInTown()	None.
GetEnemyUnitsInTown()	None.
GetEnemyVillagersInTown()	None.
GetPlayersInGame([parameter = 0])	Optional value.
GetDefenderCount()	None.
GetBuildingTypeInTown(buildingType)	Object type.
GetUnitTypeInTown(unitType)	Object type.
GetVillagerTypeInTown(unitType)	Object type.
GetGaiaTypeCount(objectType)	Object type.
GetGaiaTypeCountTotal(objectType)	Object type.
GetCcGaiaTypeCount(objectType)	Object type.
GetPlayersTribute(resource)	Resource ID.
GetPlayersTributeMemory(resource)	Resource ID.
GetTreatyTime()	None.
GetBattleRoyaleTime()	None.

Treat a fact result as a snapshot. Do not use one result as a permanent proof of game state.

Xs queries

Every Xs* query returns two values: value, available. When available is false, value is nil.

local hitpoints, available = XsGetUnitHitpoints(unit_id)
if available then
    LogInfo("HP: " .. hitpoints)
end

Call	Value type
XsGetTechState(technology[, playerId])	Integer.
XsGetTechAttribute(playerId, technology, attribute[, indexOrCost = 0])	Integer.
XsIsObjectValid(objectId[, playerId])	Boolean.
XsIsObjectAvailable(objectType[, playerId])	Boolean.
XsDoesUnitExist(unitId)	Boolean.
XsGetUnitHitpoints(unitId)	Number.
XsGetUnitBuildPoints(unitId)	Number.
XsGetUnitCharge(unitId)	Number.
XsGetUnitAttributeHeld(unitId, attributeId)	Number.
XsGetUnitTargetUnitId(unitId)	Integer.
XsGetUnitType(unitId)	Integer.
XsGetUnitClass(unitId)	Integer.
XsGetUnitOwner(unitId)	Integer.
XsGetUnitGroupId(unitId)	Integer.
XsObjectHasAction(playerId, unitType, actionId[, targetPlayerId = -1[, targetType = -1[, targetLevel = -1]]])	Boolean.
XsGetObjectTaskCount(objectId[, playerId])	Integer.
XsGetUnitTaskCount(unitId)	Integer.
XsObjectTaskAmount(objectId, taskId)	Boolean.
XsObjectTaskAmount(objectId, playerId, taskId)	Boolean.
XsUnitTaskAmount(unitId, taskId)	Boolean.
XsGetTaskAmount(taskFieldId)	Number.
XsGetPlayerInGame(playerId)	Boolean.
XsGetPlayerType(playerId)	Native integer; nil for invalid IDs or unavailable queries.
XsGetDiplomacy(sourcePlayerId, targetPlayerId)	Raw native diplomacy integer; nil for invalid IDs or unavailable queries.
XsGetLocalPlayerId()	Integer.
XsGetWorldPlayerId(scenarioPlayerId)	Integer.
XsGetDifficulty()	Integer.

Specialized object and path data

Call	Result
GetObjectTypeData(objectType, dataId)	Integer object-data value, or 0.
GetObjectTypeAttribute(objectType, attribute[, damageClass = 0])	Numeric attribute value, or 0.
CalculatePathDistance(object, destination[, mode = 0])	Integer distance, or nil.
GetResearchDiagnostics(technology)	Troubleshooting table.
ConsumeHumanCommandUnitIds()	Array of observed command object IDs.

ConsumeHumanCommandUnitIds() returns data only when command observation is enabled. An empty array does not prove that no command occurred.

Diagnostics and raw data

Call	Result
GetNativeFactDiagnostics([objectType = 109])	Troubleshooting table.
GetNativeXsDiagnostics([playerId[, unitId[, technology = 22[, objectType = 83]]]])	Troubleshooting table.
GetMapTilesPtr()	Raw value and tile count.

The diagnostic table fields can change. Use them for temporary troubleshooting, not as normal script data.

Do not dereference or save the raw value from GetMapTilesPtr(). Use MapTile methods instead.

Compatibility

The Legacy api namespace and the API name index show older aliases and names that do not perform an action.