---@meta
-- Editor declarations only. Do not load this file as a game script.
-- Public live types and command declarations. Unavailable results are nullable.

---@class Vector2
---@field x number
---@field y number
---@field Distance fun(self: Vector2, other: Vector2|Vector3): number
---@field Distance2D fun(self: Vector2, other: Vector2|Vector3): number
local Vector2Type = {}

---@class Vector3: Vector2
---@field z number
local Vector3Type = {}

---@class Vector4: Vector3
---@field w number
local Vector4Type = {}

---@class Color
---@field r number
---@field g number
---@field b number
---@field a number
local ColorType = {}

---@class ResourceCost
---@field resourceId integer
---@field amount integer
---@field [integer] integer Indices 1 and 2 also contain resourceId and amount.
local ResourceCostType = {}

---@param x number
---@param y number
---@return Vector2
function Vector2(x, y) end

---@param x number
---@param y number
---@param z? number
---@return Vector3
function Vector3(x, y, z) end

---@overload fun(value: number): Vector4
---@param x? number
---@param y? number
---@param z? number
---@param w? number
---@return Vector4
function Vector4(x, y, z, w) end

---@class Object
---@field GetId fun(self: Object): integer
---@field GetName fun(self: Object): string
---@field GetInternalName fun(self: Object): string
---@field GetMasterName fun(self: Object): string
---@field GetObjectType fun(self: Object): integer
---@field GetOwningPlayer fun(self: Object): Player|nil
---@field GetGarrisonObject fun(self: Object): Object|nil
---@field GetGarrisonCount fun(self: Object): integer|nil
---@field IsGarrisoned fun(self: Object): boolean|nil
---@field GetUnitObjectType fun(self: Object): integer
---@field GetClass fun(self: Object): integer
---@field GetHitpoints fun(self: Object): number
---@field GetMaxHitpoints fun(self: Object): number
---@field GetPosition fun(self: Object): Vector3|nil
---@field GetCurrentMapTile fun(self: Object): MapTile|nil
---@field GetBuildStatus fun(self: Object): integer
---@field GetCarriedResourceType fun(self: Object): integer
---@field GetCarriedResourceAmount fun(self: Object): number
---@field GetAttribute fun(self: Object, attribute: integer, damageClass?: integer): number|nil
---@field GetObjectData fun(self: Object, dataId: integer): integer
---@field GetTargetPosition fun(self: Object): Vector3|nil
---@field GetActionTargetPosition fun(self: Object): Vector3|nil
---@field GetTargetObject fun(self: Object): Object|nil
---@field GetActionType fun(self: Object): integer|nil
---@field GetSubActionType fun(self: Object): integer|nil
---@field IsNativeIdle fun(self: Object): boolean
---@field IsIdle fun(self: Object): boolean
---@field IsMoving fun(self: Object): boolean
---@field IsAlive fun(self: Object): boolean
---@field IsVisible fun(self: Object): boolean
---@field IsExplored fun(self: Object): boolean
---@field GetDirection fun(self: Object): nil Compatibility placeholder.
---@field IsScouting fun(self: Object): nil Compatibility placeholder.
---@field GetPath fun(self: Object): nil Compatibility placeholder.
---@field CalculatePath fun(self: Object, ...: any): nil Compatibility placeholder.
local Object = {}

---@class ProductionQueueEntry
---@field kind "unit"|"research"
---@field typeId integer Unit type or technology ID, according to kind.
---@field quantity integer Remaining quantity in this native batch.
---@field batchId string Native batch identity, scoped to this building; do not convert to a number.

---Read native production batches in order. Empty is distinct from unavailable.
---@return ProductionQueueEntry[]|nil entries
---@return string|nil reason
function Object:GetProductionQueue() end

---Total remaining quantity. Zero is an observed empty queue, never read failure.
---@return integer|nil count
---@return string|nil reason
function Object:GetProductionQueueCount() end

---@class Player
---@field GetId fun(self: Player): integer
---@field GetPlayerType fun(self: Player): integer|nil
---@field IsResigned fun(self: Player): boolean|nil
---@field GetPlayerName fun(self: Player): string|nil
---@field GetCivilizationId fun(self: Player): integer
---@field GetCivilizationName fun(self: Player): string Compatibility placeholder: returns an empty string.
---@field GetColor fun(self: Player): Color|nil
---@field GetPlayerObjects fun(self: Player): Object[]
---@field GetTownCenters fun(self: Player): Object[]
---@field GetCameraPosition fun(self: Player): Vector2|nil
---@field GetMouseHoveredObject fun(self: Player): nil Compatibility placeholder.
---@field GetSelectedObject fun(self: Player): Object|nil
---@field GetSelectedObjectCount fun(self: Player): integer|nil
---@field HasWon fun(self: Player): boolean
---@field IsAlliedWith fun(self: Player, other: Player): boolean|nil
---@field IsEnemyTo fun(self: Player, other: Player): boolean|nil
---@field GetAttribute fun(self: Player, attribute: integer): number|nil
---@field GetUnitTypeCount fun(self: Player, unitType: integer): integer
---@field GetUnitTypeCountTotal fun(self: Player, unitType: integer): integer
---@field GetBuildingTypeCount fun(self: Player, buildingType: integer): integer
---@field GetBuildingTypeCountTotal fun(self: Player, buildingType: integer): integer
---@field GetFact fun(self: Player, factId: integer, parameter?: integer): integer
---@field IsObjectTypeAvailable fun(self: Player, objectType: integer): boolean
---@field CanAfford fun(self: Player, objectType: integer, isBuilding: boolean): boolean|nil
---@field GetTechCost fun(self: Player, technology: integer): ResourceCost[], boolean
---@field GetObjectCost fun(self: Player, objectType: integer, multiplier?: number): ResourceCost[], boolean
---@field GetResearchState fun(self: Player, technology: integer): integer
---@field CanAffordResearch fun(self: Player, technology: integer): boolean|nil
---@field CanResearch fun(self: Player, technology: integer): boolean|nil
---@field IsTechnologyResearched fun(self: Player, technology: integer): boolean
---@field GetObjectsByTypes fun(self: Player, types: integer|integer[], ...: integer): Object[]
---@field GetObjectsByMostCommonType fun(self: Player, types: integer|integer[]): Object[]
---@field GetObjectsByClass fun(self: Player, unitClass: integer): Object[]
---@field GetObjectsByClassDeadInclusive fun(self: Player, unitClass: integer): Object[]
local Player = {}

---@class MapTile
---@field GetPosition fun(self: MapTile): Vector2
---@field GetTerrain fun(self: MapTile): integer
---@field GetElevation fun(self: MapTile): integer
---@field GetTileVisibility fun(self: MapTile): integer
---@field IsNavigatable fun(self: MapTile): boolean
---@field IsWalkable fun(self: MapTile): boolean
---@field IsBuildable fun(self: MapTile): false Compatibility placeholder.
---@field GetObjectCount fun(self: MapTile): integer
---@field GetObjects fun(self: MapTile): Object[]
local MapTileType = {}

---@return Player|nil player
function GetAssignedPlayer() end

---@param playerId integer
---@return Player|nil player
function GetPlayerById(playerId) end

---@overload fun(x: number, y: number): MapTile|nil
---@param position Vector2|Vector3
---@return MapTile|nil tile
function GetMapTile(position) end

---@return integer|nil seconds
function GetGameTime() end

---Read the entire local selection in native order, without filtering ownership.
---Empty selection returns {}; unavailable or changing selection returns nil and a reason.
---@return Object[]|nil objects
---@return string|nil reason
function Player:GetSelectedObjects() end

---@class CommandObservation
---@field kind string "diplomacy" or "object-target".
---@field state 'matched'|'not-matched'|'unavailable'|'not-submitted'|'session-ended' Current observation, not command causality or completion.

---@class CommandReceipt
---@field observation? CommandObservation Available after execution begins for supported commands; refreshed on each receipt read.
---@field id? string Opaque decimal identity; never convert to a number.
---@field state string Queue/transport evidence, not proof of game completion.
---@field reason? string
---@field elapsedMs? number Milliseconds since native submission returned.
---@field sessionEnded? boolean

---Read current queue/transport evidence. Nil means unknown identity.
---@param id string Opaque receipt identity; never convert to a number.
---@return CommandReceipt|nil receipt
function CommandReceipt(id) end

---Cancel only work that is still queued; inspect the returned current state.
---@param id string
---@return CommandReceipt|nil receipt
function CancelCommandReceipt(id) end

---Release terminal metadata. False means active or unknown; this does not undo an order.
---@param id string
---@return boolean released
function ReleaseCommandReceipt(id) end

---Admit one native group stop. Invalid actors reject the whole group.
---@param units Object|Object[]
---@return boolean accepted Queue admission only.
function UnitsStop(units) end

---@param units Object|Object[]
---@return boolean accepted
---@return CommandReceipt receipt
function UnitsStopTracked(units) end

---Admit the native default object action with a tracked receipt.
---The game chooses the contextual action; submission does not prove completion.
---@param units Object|Object[]
---@param target Object
---@return boolean accepted
---@return CommandReceipt receipt
---@param append? boolean True appends to native orders; defaults to false.
function UnitsTargetObjectTracked(units, target, append) end

---@param units Object|Object[]
---@param target Object Must remain live at submission.
---@return boolean accepted
---@return CommandReceipt receipt
function SetUnitStanceFollowTracked(units, target) end

---@param units Object|Object[]
---@param target Object Must remain live at submission.
---@return boolean accepted
---@return CommandReceipt receipt
function SetUnitStanceGuardTracked(units, target) end

---@param units Object|Object[]
---@param position {x:number, y:number}
---@return boolean accepted
---@return CommandReceipt receipt
function SetUnitStancePatrolTracked(units, position) end

---@param units Object|Object[]
---@param position {x:number, y:number}
---@return boolean accepted
---@return CommandReceipt receipt
function SetUnitStanceAttackMoveTracked(units, position) end

---@param units Object|Object[]
---@param stance integer UnitCombatStance value in 0..3.
---@return boolean accepted
---@return CommandReceipt receipt
function SetUnitCombatStanceTracked(units, stance) end

---@param units Object|Object[]
---@param formationId integer Non-negative signed 32-bit ID.
---@return boolean accepted
---@return CommandReceipt receipt
function SetUnitFormationTracked(units, formationId) end

---@param units Object|Object[]
---@return boolean accepted
---@return CommandReceipt receipt
function SetUnitStanceAutoScoutTracked(units) end

---@param buildings Object|Object[]
---@param state? integer -1, 0 or 1; defaults to -1.
---@return boolean accepted
---@return CommandReceipt receipt
function GatherInsideTracked(buildings, state) end

---Deletes live objects. Cancellation cannot restore objects after submission.
---@param objects Object|Object[]
---@return boolean accepted
---@return CommandReceipt receipt
function DeleteUnitTracked(objects) end

---@param resource integer
---@param amount? integer Multiple of 100 in 100..25500; defaults to 100.
---@return boolean accepted
---@return CommandReceipt receipt
function BuyCommodityTracked(resource, amount) end

---@param resource integer
---@param amount? integer Multiple of 100 in 100..25500; defaults to 100.
---@return boolean accepted
---@return CommandReceipt receipt
function SellCommodityTracked(resource, amount) end

---@param position {x:number, y:number}
---@return boolean accepted
---@return CommandReceipt receipt
function SendFlareTracked(position) end

---Request resignation. Cancellation cannot retract a submitted request.
---@return boolean accepted
---@return CommandReceipt receipt
function ResignTracked() end

---@param buildings Object|Object[]
---@param target Object|{x:number, y:number}
---@return boolean accepted
---@return CommandReceipt receipt
function SetGatherPointTracked(buildings, target) end

---@param townCenter Object
---@param active? boolean Defaults to true.
---@return boolean accepted
---@return CommandReceipt receipt
function RingTownBellTracked(townCenter, active) end

---@param townCenter Object
---@return boolean accepted
---@return CommandReceipt receipt
function SendBackToWorkTracked(townCenter) end

---@param townCenter Object
---@return boolean accepted
---@return CommandReceipt receipt
function SendAllBackToWorkTracked(townCenter) end

---Partial packet submission produces indeterminate/partial-submission; do not retry the whole group.
---@param units Object|Object[]
---@return boolean accepted
---@return CommandReceipt receipt
function DropResourcesTracked(units) end

---@param buildings Object|Object[]
---@param buildingType integer
---@param unitType integer
---@param count? integer Defaults to 1; valid range 1..32767.
---@return boolean accepted
---@return CommandReceipt receipt
function TrainUnitTracked(buildings, buildingType, unitType, count) end

---@param buildings Object|Object[]
---@param technology integer
---@return boolean accepted
---@return CommandReceipt receipt
function ResearchTechnologyTracked(buildings, technology) end

---@param builders Object|Object[]
---@param buildingType integer
---@param position {x:number, y:number}
---@param options? table Release-dependent native placement options.
---@return boolean accepted
---@return CommandReceipt receipt
function UnitsBuildStructureTracked(builders, buildingType, position, options) end

---@class ApiCapability
---@field supportsObservation? boolean Whether this recognized command supplies receipt observations; independent of live query availability.
---@field supportsAppend? boolean Whether a recognized command accepts the native-order append option; absent when unknown.
---@field implemented? boolean Absent for values that are not native functions.
---@field available? boolean Absent when readiness cannot be queried.
---@field reason? string

---Inspect a native callable without invoking it. Readiness is not acceptance.
---@param callable function|nil
---@return ApiCapability capability
function GetApiCapability(callable) end

---Submit an immediate native route; does not append to existing orders.
---@param units Object|Object[]
---@param positions {x:number, y:number}[] Ordered route of 1 to 10 finite positions.
---@return boolean accepted
function UnitsPatrolRoute(units, positions) end

---Submit an immediate native route; does not append to existing orders.
---@param units Object|Object[]
---@param positions {x:number, y:number}[] Ordered route of 1 to 10 finite positions.
---@return boolean accepted
---@return CommandReceipt receipt
function UnitsPatrolRouteTracked(units, positions) end

---Submit an immediate native route; does not append to existing orders.
---@param units Object|Object[]
---@param positions {x:number, y:number}[] Ordered route of 1 to 10 finite positions.
---@return boolean accepted
function UnitsAttackMoveRoute(units, positions) end

---Submit an immediate native route; does not append to existing orders.
---@param units Object|Object[]
---@param positions {x:number, y:number}[] Ordered route of 1 to 10 finite positions.
---@return boolean accepted
---@return CommandReceipt receipt
function UnitsAttackMoveRouteTracked(units, positions) end


---Issue native immediate attack-ground; submission does not prove firing.
---@param units Object|Object[] One to 255 owned live actors; invalid members reject the group.
---@param position {x:number, y:number} Finite ground position.
---@return boolean accepted
function UnitsAttackGround(units, position) end

---Issue native immediate attack-ground; submission does not prove firing.
---@param units Object|Object[] One to 255 owned live actors; invalid members reject the group.
---@param position {x:number, y:number} Finite ground position.
---@return boolean accepted
---@return CommandReceipt receipt
function UnitsAttackGroundTracked(units, position) end


---Unload only the specified occupant using the native default destination.
---@param container Object Owned live container.
---@param occupant Object Owned live occupant currently inside container.
---@return boolean accepted
function UngarrisonUnit(container, occupant) end

---Unload only the specified occupant using the native default destination.
---@param container Object Owned live container.
---@param occupant Object Owned live occupant currently inside container.
---@return boolean accepted
---@return CommandReceipt receipt
function UngarrisonUnitTracked(container, occupant) end


---Request native group unloading toward a position.
---@param containers Object|Object[] One to 255 owned live containers.
---@param position {x:number, y:number} Finite unload destination.
---@return boolean accepted
function UngarrisonTo(containers, position) end

---Request native group unloading toward a position.
---@param containers Object|Object[] One to 255 owned live containers.
---@param position {x:number, y:number} Finite unload destination.
---@return boolean accepted
---@return CommandReceipt receipt
function UngarrisonToTracked(containers, position) end


---Request native pack; submission does not prove completion.
---@param units Object|Object[] Owned live actors; invalid members reject the group.
---@return boolean accepted
function UnitsPack(units) end

---Request native pack; submission does not prove completion.
---@param units Object|Object[] Owned live actors; invalid members reject the group.
---@return boolean accepted
---@return CommandReceipt receipt
function UnitsPackTracked(units) end

---Request native unpack; submission does not prove completion.
---@param units Object|Object[] Owned live actors; invalid members reject the group.
---@return boolean accepted
function UnitsUnpack(units) end

---Request native unpack; submission does not prove completion.
---@param units Object|Object[] Owned live actors; invalid members reject the group.
---@return boolean accepted
---@return CommandReceipt receipt
function UnitsUnpackTracked(units) end


---Toggle native gate locking once; retries may undo a submitted toggle.
---@param gate Object Owned live gate.
---@return boolean accepted
function ToggleGate(gate) end

---Toggle native gate locking once; retries may undo a submitted toggle.
---@param gate Object Owned live gate.
---@return boolean accepted
---@return CommandReceipt receipt
function ToggleGateTracked(gate) end


---Cancel one production item. Native network delay may shift the target position.
---@param building Object Owned live building.
---@param batchId string Exact identity from GetProductionQueue.
---@return boolean accepted
function CancelProduction(building, batchId) end

---Cancel one production item; submission is not confirmation of cancellation.
---@param building Object Owned live building.
---@param batchId string Exact identity from GetProductionQueue.
---@return boolean accepted
---@return CommandReceipt receipt
function CancelProductionTracked(building, batchId) end

---Monotonic elapsed clock in milliseconds; its origin is unspecified.
---@return number milliseconds
function GetHighResolutionTimeMs() end

---@class LuaTimingStats
---@field managedLastMs? number Last managed update duration in milliseconds.
---@field managedMaxMs? number Maximum managed update duration in milliseconds.
---@field renderLastMs? number Last managed render duration in milliseconds.
---@field renderMaxMs? number Maximum managed render duration in milliseconds.
---@field managedCount? number Managed update counter.
---@field workerEnabled? boolean Whether the managed worker is enabled.

---Aggregate counters for this Lua engine, not a per-script timing list.
---@return LuaTimingStats stats Empty when the engine context is unavailable.
function GetLuaTimingStats() end

---Returns zero when the local player cannot be read.
---@return integer playerId
function GetAssignedPlayerId() end

---Unknown game state returns nil.
---@return boolean|nil open
function IsMenuOpen() end

---Returns no values if the executable path cannot be obtained.
---@return string|nil path
function GetExecutablePath() end

---Set the WololoLabs overlay visibility.
---@param visible boolean
function SetEngineUIVisibility(visible) end

---Move the camera. Success returns no values; failure returns nil and a reason.
---@param position Vector2|Vector3
---@return nil
---@return string|nil reason
function SetCameraPosition(position) end

---Write values separated by tabs; an initial level is accepted with another value.
---@param ... any
function log(...) end

---Write values separated by tabs; an initial level is accepted with another value.
---@param ... any
function Log(...) end

---@param ... any
function LogDebug(...) end

---@param ... any
function LogInfo(...) end

---@param ... any
function LogWarn(...) end

---@param ... any
function LogWarning(...) end

---@param ... any
function LogError(...) end


---@alias DiplomacyStance 'ally'|'neutral'|'enemy'
---Queue a native diplomacy request. Rejects locked teams and unavailable state.
---@param targetPlayerId integer Another existing non-Gaia player ID.
---@param stance DiplomacyStance
---@return boolean accepted Queue admission only.
function SetDiplomacy(targetPlayerId, stance) end

---Submission does not prove the relationship changed.
---@param targetPlayerId integer
---@param stance DiplomacyStance
---@return boolean accepted
---@return CommandReceipt receipt
function SetDiplomacyTracked(targetPlayerId, stance) end


---Queue movement, optionally after existing native orders.
---@param units Object|Object[]
---@param position {x:number, y:number}
---@param append? boolean Defaults to false; true requests native tail insertion.
---@return boolean accepted
function UnitsMove(units, position, append) end

---@param units Object|Object[]
---@param position {x:number, y:number}
---@param append? boolean Defaults to false.
---@return boolean accepted
---@return CommandReceipt receipt
function UnitsMoveTracked(units, position, append) end


---Request the native default action for this target.
---@param units Object|Object[]
---@param target Object
---@param append? boolean True appends to native orders; defaults to false.
---@return boolean accepted
function UnitsTargetObject(units, target, append) end


---Submit an immediate native order; no append parameter is supported.
---@param units Object|Object[]
---@param target Object
---@return boolean accepted
function SetUnitStanceFollow(units, target) end


---Submit an immediate native order; no append parameter is supported.
---@param units Object|Object[]
---@param target Object
---@return boolean accepted
function SetUnitStanceGuard(units, target) end


---Submit an immediate native order; no append parameter is supported.
---@param units Object|Object[]
---@param position {x:number, y:number}
---@return boolean accepted
function SetUnitStancePatrol(units, position) end


---Submit an immediate native order; no append parameter is supported.
---@param units Object|Object[]
---@param position {x:number, y:number}
---@return boolean accepted
function SetUnitStanceAttackMove(units, position) end


---@param buildings Object|Object[]
---@param buildingType integer
---@param unitType integer
---@param count? integer Defaults to 1; valid range 1..32767.
---@return boolean accepted
function TrainUnit(buildings, buildingType, unitType, count) end


---Partial packet submission produces indeterminate/partial-submission; do not retry the whole group.
---@param units Object|Object[]
---@return boolean accepted
function DropResources(units) end


---@param builders Object|Object[]
---@param buildingType integer
---@param position {x:number, y:number}
---@param options? table Release-dependent native placement options.
---@return boolean accepted
function UnitsBuildStructure(builders, buildingType, position, options) end


---@param buildings Object|Object[]
---@param technology integer
---@return boolean accepted
function ResearchTechnology(buildings, technology) end


---Deletes live objects. Cancellation cannot restore objects after submission.
---@param objects Object|Object[]
---@return boolean accepted
function DeleteUnit(objects) end


---@param buildings Object|Object[]
---@param target Object|{x:number, y:number}
---@return boolean accepted
function SetGatherPoint(buildings, target) end


---@param townCenter Object
---@param active? boolean Defaults to true.
---@return boolean accepted
function RingTownBell(townCenter, active) end


---@param townCenter Object
---@return boolean accepted
function SendBackToWork(townCenter) end


---@param townCenter Object
---@return boolean accepted
function SendAllBackToWork(townCenter) end


---@param units Object|Object[]
---@return boolean accepted
function SetUnitStanceAutoScout(units) end


---@param units Object|Object[]
---@param stance integer UnitCombatStance value in 0..3.
---@return boolean accepted
function SetUnitCombatStance(units, stance) end


---@param units Object|Object[]
---@param formationId integer Non-negative signed 32-bit ID.
---@return boolean accepted
function SetUnitFormation(units, formationId) end


---@param resource integer
---@param amount? integer Multiple of 100 in 100..25500; defaults to 100.
---@return boolean accepted
function BuyCommodity(resource, amount) end


---@param resource integer
---@param amount? integer Multiple of 100 in 100..25500; defaults to 100.
---@return boolean accepted
function SellCommodity(resource, amount) end


---@param position {x:number, y:number}
---@return boolean accepted
function SendFlare(position) end


---Request resignation. Cancellation cannot retract a submitted request.
---@return boolean accepted
function Resign() end


---@param buildings Object|Object[]
---@param state? integer -1, 0 or 1; defaults to -1.
---@return boolean accepted
function GatherInside(buildings, state) end


---Consume the observer's pending human-command actor IDs.
---@return integer[] unitIds
function ConsumeHumanCommandUnitIds() end

---With no units, choose the first eligible local auto-scout candidate.
---@param units? Object|Object[]
---@return boolean accepted
function EnableScouting(units) end

---@param objects Object|Object[]
---@return boolean accepted
function DestroyBuilding(objects) end

---@param units Object|Object[]
---@return boolean accepted
function SetUnitStanceSeekShelter(units) end

---@param units Object|Object[]
---@return boolean accepted
---@return CommandReceipt receipt
function SetUnitStanceSeekShelterTracked(units) end

---Alias for the native seek-shelter command.
---@param units Object|Object[]
---@return boolean accepted
function SetUnitStanceGarrison(units) end

---@param buildings Object|Object[]
---@return boolean accepted
function SetUnitStanceUngarrison(buildings) end

---Optional occupants guard the deferred whole-building release; they do not select who is released.
---@param buildings Object|Object[]
---@param occupants? Object|Object[]
---@return boolean accepted
---@return CommandReceipt receipt
function SetUnitStanceUngarrisonTracked(buildings, occupants) end


---Live game-options facade. Setter success reports a local write, not replicated acceptance.
---@class GameOptions

---@return integer|nil value
function GameOptions:GetGameMode() end

---@param value integer
---@return boolean written Local write only.
function GameOptions:SetGameMode(value) end

---@return integer|nil value
function GameOptions:GetMapSize() end

---@param value integer
---@return boolean written Local write only.
function GameOptions:SetMapSize(value) end

---@return integer|nil value
function GameOptions:GetStartingAge() end

---@param value integer
---@return boolean written Local write only.
function GameOptions:SetStartingAge(value) end

---@return integer|nil value
function GameOptions:GetEndingAge() end

---@param value integer
---@return boolean written Local write only.
function GameOptions:SetEndingAge(value) end

---@return integer|nil value
function GameOptions:GetGameSpeed() end

---@param value integer
---@return boolean written Local write only.
function GameOptions:SetGameSpeed(value) end

---@return integer|nil value
function GameOptions:GetRevealMap() end

---@param value integer
---@return boolean written Local write only.
function GameOptions:SetRevealMap(value) end

---@return integer|nil value
function GameOptions:GetResources() end

---@param value integer
---@return boolean written Local write only.
function GameOptions:SetResources(value) end

---@return integer|nil value
function GameOptions:GetPopulation() end

---@param value integer
---@return boolean written Local write only.
function GameOptions:SetPopulation(value) end

---@return boolean|nil value
function GameOptions:GetRecordGame() end

---@param value boolean
---@return boolean written Local write only.
function GameOptions:SetRecordGame(value) end

---@return boolean|nil value
function GameOptions:GetFullTechTree() end

---@param value boolean
---@return boolean written Local write only.
function GameOptions:SetFullTechTree(value) end

---@return boolean|nil value
function GameOptions:GetLockTeams() end

---@param value boolean
---@return boolean written Local write only.
function GameOptions:SetLockTeams(value) end

---@return boolean|nil value
function GameOptions:GetLockSpeed() end

---@param value boolean
---@return boolean written Local write only.
function GameOptions:SetLockSpeed(value) end

---@return boolean|nil value
function GameOptions:GetTurboMode() end

---@param value boolean
---@return boolean written Local write only.
function GameOptions:SetTurboMode(value) end

---@return integer|nil value
function GameOptions:GetLocation() end

---@param value integer
---@return boolean written Local write only.
function GameOptions:SetLocation(value) end

---@param locations integer[] Exactly one map ID is currently supported.
---@return boolean written Local write only.
function GameOptions:SetRandomMapPoolLocations(locations) end

---@return boolean|nil value
function GameOptions:GetHandicap() end

---@param value boolean
---@return boolean written Local write only.
function GameOptions:SetHandicap(value) end

---@param slot integer Zero-based lobby slot in 0..7; not an in-game player ID.
---@return integer|nil value
function GameOptions:GetPlayerTeam(slot) end

---@param slot integer Zero-based lobby slot in 0..7; not an in-game player ID.
---@param value integer
---@return boolean written Local write only.
function GameOptions:SetPlayerTeam(slot, value) end

---@param slot integer Zero-based lobby slot in 0..7; not an in-game player ID.
---@return integer|nil value
function GameOptions:GetPlayerColor(slot) end

---@param slot integer Zero-based lobby slot in 0..7; not an in-game player ID.
---@param value integer
---@return boolean written Local write only.
function GameOptions:SetPlayerColor(slot, value) end

---@param slot integer Zero-based lobby slot in 0..7; not an in-game player ID.
---@return integer|nil value
function GameOptions:GetPlayerCivilization(slot) end

---@param slot integer Zero-based lobby slot in 0..7; not an in-game player ID.
---@param value integer
---@return boolean written Local write only.
function GameOptions:SetPlayerCivilization(slot, value) end

---@param value integer
---@return boolean written Local write only.
function GameOptions:SetAssignedPlayerCivilization(value) end

---Unsupported compatibility placeholder.
---@param ... any
---@return nil
function GameOptions:GetAIDifficulty(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return false
function GameOptions:SetAIDifficulty(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return nil
function GameOptions:GetCivilizationSet(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return false
function GameOptions:SetCivilizationSet(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return nil
function GameOptions:GetVictory(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return false
function GameOptions:SetVictory(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return nil
function GameOptions:GetVictoryLimit(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return false
function GameOptions:SetVictoryLimit(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return nil
function GameOptions:GetTeamsNotTogether(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return false
function GameOptions:SetTeamsNotTogether(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return nil
function GameOptions:GetTeamPositions(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return false
function GameOptions:SetTeamPositions(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return nil
function GameOptions:GetAntiquityMode(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return false
function GameOptions:SetAntiquityMode(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return nil
function GameOptions:GetPlayersCount(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return false
function GameOptions:SetPlayersCount(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return nil
function GameOptions:GetTreatyLength(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return false
function GameOptions:SetTreatyLength(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return nil
function GameOptions:GetPlayerHandicapPercentage(...) end

---Unsupported compatibility placeholder.
---@param ... any
---@return false
function GameOptions:SetPlayerHandicapPercentage(...) end

---@return GameOptions|nil options
function GetCurrentGameOptions() end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@return boolean|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsDoesUnitExist(unitId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@return number|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetUnitHitpoints(unitId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@return number|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetUnitBuildPoints(unitId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@return number|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetUnitCharge(unitId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@param attributeId integer
---@return number|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetUnitAttributeHeld(unitId, attributeId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetUnitTargetUnitId(unitId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetUnitType(unitId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetUnitClass(unitId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetUnitOwner(unitId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetUnitGroupId(unitId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetUnitTaskCount(unitId) end


---Live native observation; nil means the query was unavailable.
---@param unitId integer
---@param taskId integer
---@return boolean|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsUnitTaskAmount(unitId, taskId) end


---Live native observation; nil means the query was unavailable.
---@param taskFieldId integer
---@return number|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetTaskAmount(taskFieldId) end


---Live native observation; nil means the query was unavailable.
---@param playerId integer
---@return boolean|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetPlayerInGame(playerId) end


---Live native observation; nil means the query was unavailable.
---@param playerId integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetPlayerType(playerId) end


---Live native observation; nil means the query was unavailable.
---@param sourcePlayerId integer
---@param targetPlayerId integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetDiplomacy(sourcePlayerId, targetPlayerId) end


---Live native observation; nil means the query was unavailable.
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetLocalPlayerId() end


---Live native observation; nil means the query was unavailable.
---@param scenarioPlayerId integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetWorldPlayerId(scenarioPlayerId) end


---Live native observation; nil means the query was unavailable.
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetDifficulty() end


---Live native observation; nil means the query was unavailable.
---@param technologyId integer
---@param playerId? integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetTechState(technologyId, playerId) end


---Live native observation; nil means the query was unavailable.
---@param objectId integer
---@param playerId? integer
---@return boolean|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsIsObjectValid(objectId, playerId) end


---Live native observation; nil means the query was unavailable.
---@param objectType integer
---@param playerId? integer
---@return boolean|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsIsObjectAvailable(objectType, playerId) end


---Live native observation; nil means the query was unavailable.
---@param objectId integer
---@param playerId? integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetObjectTaskCount(objectId, playerId) end


---Live native observation; nil means the query was unavailable.
---@param playerId integer
---@param technologyId integer
---@param attributeId integer
---@param indexOrCostType? integer
---@return integer|nil value
---@return boolean available True when the native query returned; not an action-success flag.
function XsGetTechAttribute(playerId, technologyId, attributeId, indexOrCostType) end


---@class SettingsColor
---@field r number
---@field g number
---@field b number
---@field a number

---@class SettingsModule
---@field Name string
local SettingsModule = {}

Settings = {}
---@param name string
---@return SettingsModule module
function Settings.Module(name) end

---@overload fun(module: string, option: string, fallback?: boolean): boolean
---@param path string Dotted module.option path.
---@param fallback? boolean
---@return boolean value
function Settings.GetBool(path, fallback) end

---@param option string
---@param fallback? boolean
---@return boolean value
function SettingsModule:GetBool(option, fallback) end

---@overload fun(module: string, option: string, value: boolean)
---@param path string Dotted module.option path.
---@param value boolean
function Settings.SetBool(path, value) end

---@param option string
---@param value boolean
function SettingsModule:SetBool(option, value) end

---@overload fun(module: string, option: string, value?: boolean)
---@param path string Dotted module.option path.
---@param value? boolean
function Settings.AddBool(path, value) end

---@param option string
---@param value? boolean
---@param label? string
function SettingsModule:AddBool(option, value, label) end

---@overload fun(module: string, option: string, fallback: integer): integer
---@param path string Dotted module.option path.
---@param fallback integer
---@return integer value
function Settings.GetInt(path, fallback) end

---@param option string
---@param fallback integer
---@return integer value
function SettingsModule:GetInt(option, fallback) end

---@overload fun(module: string, option: string, value: integer)
---@param path string Dotted module.option path.
---@param value integer
function Settings.SetInt(path, value) end

---@param option string
---@param value integer
function SettingsModule:SetInt(option, value) end

---@overload fun(module: string, option: string, value: integer)
---@param path string Dotted module.option path.
---@param value integer
function Settings.AddInt(path, value) end

---@param option string
---@param value integer
---@param minimumOrLabel? number|string
---@param maximum? number
---@param label? string
function SettingsModule:AddInt(option, value, minimumOrLabel, maximum, label) end

---@overload fun(module: string, option: string, fallback: number): number
---@param path string Dotted module.option path.
---@param fallback number
---@return number value
function Settings.GetFloat(path, fallback) end

---@param option string
---@param fallback number
---@return number value
function SettingsModule:GetFloat(option, fallback) end

---@overload fun(module: string, option: string, value: number)
---@param path string Dotted module.option path.
---@param value number
function Settings.SetFloat(path, value) end

---@param option string
---@param value number
function SettingsModule:SetFloat(option, value) end

---@overload fun(module: string, option: string, value: number)
---@param path string Dotted module.option path.
---@param value number
function Settings.AddFloat(path, value) end

---@param option string
---@param value number
---@param minimumOrLabel? number|string
---@param maximum? number
---@param label? string
function SettingsModule:AddFloat(option, value, minimumOrLabel, maximum, label) end

---@overload fun(module: string, option: string, fallback: string): string
---@param path string Dotted module.option path.
---@param fallback string
---@return string value
function Settings.GetString(path, fallback) end

---@param option string
---@param fallback string
---@return string value
function SettingsModule:GetString(option, fallback) end

---@overload fun(module: string, option: string, value: string)
---@param path string Dotted module.option path.
---@param value string
function Settings.SetString(path, value) end

---@param option string
---@param value string
function SettingsModule:SetString(option, value) end

---@overload fun(module: string, option: string, fallback: integer): integer
---@param path string Dotted module.option path.
---@param fallback integer
---@return integer value
function Settings.GetKeybind(path, fallback) end

---@param option string
---@param fallback integer
---@return integer value
function SettingsModule:GetKeybind(option, fallback) end

---@overload fun(module: string, option: string, value: integer)
---@param path string Dotted module.option path.
---@param value integer
function Settings.AddKeybind(path, value) end

---@param option string
---@param value integer
---@param label? string
function SettingsModule:AddKeybind(option, value, label) end

---@overload fun(module: string, option: string, fallback?: SettingsColor|integer): SettingsColor
---@param path string Dotted module.option path.
---@param fallback? SettingsColor|integer
---@return SettingsColor value
function Settings.GetColor(path, fallback) end

---@param option string
---@param fallback? SettingsColor|integer
---@return SettingsColor value
function SettingsModule:GetColor(option, fallback) end

---@overload fun(module: string, option: string, value?: SettingsColor|integer)
---@param path string Dotted module.option path.
---@param value? SettingsColor|integer
function Settings.AddColor(path, value) end

---@param option string
---@param value? SettingsColor|integer
function SettingsModule:AddColor(option, value) end


---@overload fun(module: string, option: string, value: string)
---@param path string
---@param value string
function Settings.AddDropdown(path, value) end

---@param option string
---@param value string
---@param choicesOrLabel? string[]|string
---@param label? string
function SettingsModule:AddDropdown(option, value, choicesOrLabel, label) end

---Unsupported placeholder; returns no values.
---@param ... any
function Settings.AddTooltip(...) end

---Unsupported placeholder; returns no values.
---@param ... any
function SettingsModule:AddTooltip(...) end

---Returns whether the Windows virtual key is currently held, not a key-down edge.
---@param virtualKey integer
---@return boolean held
function IsKeyPressed(virtualKey) end


---@alias RenderColor integer|{r:number,g:number,b:number,a:number}

---Capture-only frames return zero dimensions.
---@return Vector2 value
function GetScreenSize() end

---Capture-only frames return false.
---@param position Vector2
---@return boolean value
function IsOnScreen(position) end

---Unavailable views and capture-only frames return false.
---@param position Vector3
---@return boolean value
function IsWorldPosOnScreen(position) end

---Unavailable views and capture-only frames return nil.
---@param position Vector3
---@return Vector2|nil value
function WorldToScreen(position) end

---Unavailable projection returns nil.
---@param position Vector3
---@return Vector2|nil value
function WorldToMinimap(position) end

---Capture-only frames return zero; unavailable camera returns nil.
---@return number|nil value
function GetZoom() end

---Capture-only frames return zero coordinates; unavailable camera returns nil.
---@return Vector2|nil value
function GetCameraPosition() end

---Screen pixels.
---@param text string
---@param position Vector2
---@param size? number
---@param color? RenderColor
---@param center? boolean
---@param border? boolean
function RenderText(text, position, size, color, center, border) end

---Margins default to 12 pixels.
---@param text string
---@param marginX? number
---@param marginY? number
---@param size? number
---@param color? RenderColor
---@param border? boolean
function RenderTopRightText(text, marginX, marginY, size, color, border) end

---Screen pixels; thickness defaults to 1.
---@param from Vector2
---@param to Vector2
---@param color? RenderColor
---@param thickness? number
function RenderLine(from, to, color, thickness) end

---Screen pixels; segments default to 32.
---@param center Vector2
---@param radius number
---@param color? RenderColor
---@param thickness? number
---@param segments? integer
function RenderCircle(center, radius, color, thickness, segments) end

---Screen pixels.
---@param center Vector2
---@param radius number
---@param color? RenderColor
---@param segments? integer
function RenderCircleFilled(center, radius, color, segments) end

---Screen pixels.
---@param minimum Vector2
---@param maximum Vector2
---@param color? RenderColor
---@param rounding? number
---@param flags? integer
---@param thickness? number
function RenderRect(minimum, maximum, color, rounding, flags, thickness) end

---Screen pixels.
---@param minimum Vector2
---@param maximum Vector2
---@param color? RenderColor
---@param rounding? number
---@param flags? integer
function RenderRectFilled(minimum, maximum, color, rounding, flags) end

---World coordinates.
---@param from Vector3
---@param to Vector3
---@param color? RenderColor
---@param thickness? number
function RenderWorldLine(from, to, color, thickness) end

---World coordinates.
---@param center Vector3
---@param width number
---@param height number
---@param color? RenderColor
---@param thickness? number
function RenderWorldRect(center, width, height, color, thickness) end

---World coordinates.
---@param center Vector3
---@param width number
---@param height number
---@param color? RenderColor
function RenderWorldRectFilled(center, width, height, color) end

---World coordinates.
---@param center Vector3
---@param radius number
---@param color? RenderColor
---@param thickness? number
---@param segments? integer
function RenderWorldCircle(center, radius, color, thickness, segments) end

---World coordinates.
---@param center Vector3
---@param radius number
---@param color? RenderColor
---@param segments? integer
function RenderWorldCircleFilled(center, radius, color, segments) end

---World position, screen font size.
---@param text string
---@param position Vector3
---@param size? number
---@param color? RenderColor
---@param center? boolean
---@param border? boolean
function RenderWorldText(text, position, size, color, center, border) end

---No values returned, including when unavailable.
---@param object Object
---@param color? RenderColor
---@param thickness? number
function RenderObjectBounds(object, color, thickness) end

---No values returned, including when unavailable.
---@param object Object
---@param color? RenderColor
function RenderObjectBoundsFilled(object, color) end

---World position; radius in minimap pixels.
---@param position Vector3
---@param radius number
---@param color? RenderColor
function RenderMinimapDot(position, radius, color) end

---World endpoints; thickness precedes color.
---@param from Vector3
---@param to Vector3
---@param thickness number
---@param color? RenderColor
function RenderMinimapLine(from, to, thickness, color) end

---World bounds projected onto the minimap.
---@param center Vector3
---@param width number
---@param height number
---@param color RenderColor
---@param thickness number
function RenderMinimapRect(center, width, height, color, thickness) end

---World bounds projected onto the minimap.
---@param center Vector3
---@param width number
---@param height number
---@param color? RenderColor
function RenderMinimapRectFilled(center, width, height, color) end


---Submit native tribute. The receiver can reduce the amount to available funds after fees.
---@param playerId integer Other non-Gaia player ID, 1..255.
---@param resource integer 0 food, 1 wood, 2 stone, 3 gold.
---@param amount integer 1..16777216. Fee is read natively at execution.
---@return boolean accepted Queue admission only.
function TributeToPlayer(playerId, resource, amount) end

---Tracked tribute; receipt does not prove recipient credit or transferred amount.
---@param playerId integer Other non-Gaia player ID, 1..255.
---@param resource integer 0 food, 1 wood, 2 stone, 3 gold.
---@param amount integer 1..16777216.
---@return boolean accepted
---@return CommandReceipt receipt
function TributeToPlayerTracked(playerId, resource, amount) end

---Assigned-player native fact 10. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetCommodityBuyingPrice(parameter) end

---Assigned-player native fact 11. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetCommoditySellingPrice(parameter) end

---Assigned-player native fact 20. Returns nil when unavailable.
---@return integer|nil value
function GetCurrentScore() end

---Assigned-player native fact 23. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetPlayerInGame(parameter) end

---Assigned-player native fact 35. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetPlayerDistance(parameter) end

---Assigned-player native fact 39. Returns nil when unavailable.
---@return integer|nil value
function GetEnemyBuildingsInTown() end

---Assigned-player native fact 40. Returns nil when unavailable.
---@return integer|nil value
function GetEnemyUnitsInTown() end

---Assigned-player native fact 41. Returns nil when unavailable.
---@return integer|nil value
function GetEnemyVillagersInTown() end

---Assigned-player native fact 42. Returns nil when unavailable.
---@param parameter? integer Defaults to 0.
---@return integer|nil value
function GetPlayersInGame(parameter) end

---Assigned-player native fact 43. Returns nil when unavailable.
---@return integer|nil value
function GetDefenderCount() end

---Assigned-player native fact 44. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetBuildingTypeInTown(parameter) end

---Assigned-player native fact 45. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetUnitTypeInTown(parameter) end

---Assigned-player native fact 46. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetVillagerTypeInTown(parameter) end

---Assigned-player native fact 47. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetGaiaTypeCount(parameter) end

---Assigned-player native fact 48. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetGaiaTypeCountTotal(parameter) end

---Assigned-player native fact 49. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetCcGaiaTypeCount(parameter) end

---Assigned-player native fact 52. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetPlayersTribute(parameter) end

---Assigned-player native fact 53. Returns nil when unavailable.
---@param parameter integer Native fact parameter.
---@return integer|nil value
function GetPlayersTributeMemory(parameter) end

---Assigned-player native fact 55. Returns nil when unavailable.
---@return integer|nil value
function GetBattleRoyaleTime() end

---Compatibility query: returns value, available; unavailable facts return 0, false and confirmed zero returns 0, true.
---@param factId integer
---@param parameter? integer Defaults to 0.
---@return integer value
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetFact(factId, parameter) end

---Native remaining treaty time; inactive or absent treaty returns 0, unavailable game state returns nil.
---@return integer|nil value
function GetTreatyTime() end

---Assigned-player native attribute; nil when unavailable.
---@param attribute integer
---@return number|nil value
function GetAttribute(attribute) end

---Compatibility count for assigned player; unavailable reads can return 0.
---@param unitType integer
---@return integer count
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetUnitTypeCount(unitType) end

---Compatibility count for assigned player; unavailable reads can return 0.
---@param unitType integer
---@return integer count
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetUnitTypeCountTotal(unitType) end

---Compatibility count for assigned player; unavailable reads can return 0.
---@param buildingType integer
---@return integer count
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetBuildingTypeCount(buildingType) end

---Compatibility count for assigned player; unavailable reads can return 0.
---@param buildingType integer
---@return integer count
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetBuildingTypeCountTotal(buildingType) end

---Compatibility query; unavailable reads can return 0. Counts can reflect partial live reads.
---@return integer value
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetTotalUnitCount() end

---Compatibility query; unavailable reads can return 0. Counts can reflect partial live reads.
---@return integer value
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetTotalUnitCountTotal() end

---Compatibility query; unavailable reads can return 0. Counts can reflect partial live reads.
---@return integer value
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetTotalBuildingCount() end

---Compatibility query; unavailable reads can return 0. Counts can reflect partial live reads.
---@return integer value
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetTotalBuildingCountTotal() end

---Compatibility query; unavailable reads can return 0. Counts can reflect partial live reads.
---@return integer value
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetPlayerCount() end

---Compatibility query; unavailable reads can return 0. Counts can reflect partial live reads.
---@return integer value
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetMapWidth() end

---Compatibility query; unavailable reads can return 0. Counts can reflect partial live reads.
---@return integer value
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetMapHeight() end

---Compatibility query; unavailable reads can return 0. Counts can reflect partial live reads.
---@return integer value
---@return boolean available False means the first result is compatibility data, not a confirmed value.
function GetVictoryCondition() end

---Native current-age time for the assigned player; nil when unavailable.
---@return integer|nil value
function GetTimeInCurrentAge() end

---Resolve a current native object identity.
---@param objectId integer
---@return Object|nil object
function GetObjectById(objectId) end

---Available only after endgame with a valid native victory player.
---@return Player|nil player
function GetVictoryPlayer() end

---Relationship from the assigned player; unavailable is nil.
---@param player Player|nil
---@return boolean|nil enemy
function IsEnemyPlayer(player) end

---Native path distance; nil when unavailable.
---@param object Object
---@param destination {x:number, y:number}
---@param mode? integer Defaults to 0.
---@return integer|nil distance
function CalculatePathDistance(object, destination, mode) end

---Known world objects within inclusive rectangle bounds, normalized from both corners.
---@param a {x:number, y:number}
---@param b {x:number, y:number}
---@return Object[] objects
function GetObjectsInArea(a, b) end

---Reads a known representative object; returns 0 if none exists or the query fails.
---@param objectType integer
---@param dataId integer
---@return integer value
function GetObjectTypeData(objectType, dataId) end

---Reads a known representative object; returns 0 if none exists or the query fails.
---@param objectType integer
---@param attribute integer
---@param damageClass? integer Defaults to 0.
---@return number value
function GetObjectTypeAttribute(objectType, attribute, damageClass) end

---@class NativeFactDiagnostics
---@field version integer
---@field playerId integer
---@field objectType integer
---@field gotCurrentAgeTime boolean
---@field currentAgeTime integer
---@field worldGameTime integer
---@field gotWorldGameTime boolean
---@field gotUnitCurrent boolean
---@field unitCurrent integer
---@field gotUnitTotal boolean
---@field unitTotal integer
---@field gotBuildingCurrent boolean
---@field buildingCurrent integer
---@field gotBuildingTotal boolean
---@field buildingTotal integer
---@field nativeUnitTypeCount integer
---@field nativeUnitTypeCountTotal integer
---@field nativeBuildingTypeCount integer
---@field nativeBuildingTypeCountTotal integer
---@field objectTrackerCurrentCount integer
---@field objectTrackerCurrentClassCount integer
---@field objectTrackerBuildRecord integer
---@field objectTrackerPromotePending integer
---@field currentAgeTimeValue integer
---@field worldClockGetter integer


---@class NativeXsDiagnostics
---@field version integer
---@field playerId integer
---@field unitId integer
---@field techId integer
---@field objectType integer
---@field xsGetTechState {resolved:boolean, offset:integer}
---@field xsIsObjectValid {resolved:boolean, offset:integer}
---@field xsDoesUnitExist {resolved:boolean, offset:integer}
---@field xsGetUnitTargetUnitId {resolved:boolean, offset:integer}
---@field xsGetUnitHitpoints {resolved:boolean, offset:integer}
---@field xsObjectHasAction {resolved:boolean, offset:integer}
---@field xsGetObjectTaskCount {resolved:boolean, offset:integer}
---@field xsGetUnitTaskCount {resolved:boolean, offset:integer}
---@field xsObjectTaskAmount {resolved:boolean, offset:integer}
---@field xsUnitTaskAmount {resolved:boolean, offset:integer}
---@field xsGetTaskAmount {resolved:boolean, offset:integer}
---@field xsGetDifficulty {resolved:boolean, offset:integer}
---@field techStateOk boolean
---@field techState integer
---@field objectAvailableOk boolean
---@field objectAvailable boolean
---@field unitExistsOk? boolean
---@field unitExists? boolean
---@field unitHitpointsOk? boolean
---@field unitTargetOk? boolean
---@field unitTargetUnitId? integer
---@field unitTaskCountOk? boolean
---@field unitTaskCount? integer
---@field unitHitpoints? number


---@class ResearchDiagnostics
---@field ok boolean
---@field contextOk boolean
---@field refreshed boolean
---@field stateBefore integer
---@field stateAfter integer
---@field availabilityErrorWithEscrow integer
---@field availabilityErrorWithoutEscrow integer
---@field producer integer


---Use got* booleans before interpreting paired values; offsets are diagnostic evidence only.
---@param objectType? integer Defaults to 109.
---@return NativeFactDiagnostics diagnostics
function GetNativeFactDiagnostics(objectType) end

---Use *Ok booleans before interpreting paired observations.
---@param playerId? integer Defaults to assigned player.
---@param unitId? integer Defaults to -1; unit observations require nonnegative ID.
---@param techId? integer Defaults to 22.
---@param objectType? integer Defaults to 83.
---@return NativeXsDiagnostics diagnostics
function GetNativeXsDiagnostics(playerId, unitId, techId, objectType) end

---Native research diagnostics; inspect ok/contextOk before interpreting results.
---@param techId integer
---@return ResearchDiagnostics diagnostics
function GetResearchDiagnostics(techId) end

---Native query; availability does not establish action completion.
---@param playerId integer
---@param unitType integer
---@param actionId integer
---@param targetPlayerId? integer Defaults to -1.
---@param targetType? integer Defaults to -1.
---@param targetUnitLevel? integer Defaults to -1.
---@return boolean|nil value
---@return boolean available
function XsObjectHasAction(playerId, unitType, actionId, targetPlayerId, targetType, targetUnitLevel) end

---Two-argument form uses assigned player; despite its name this native result is boolean.
---@overload fun(objectId: integer, playerId: integer, taskId: integer): boolean|nil, boolean
---@param objectId integer
---@param taskId integer
---@return boolean|nil value
---@return boolean available
function XsObjectTaskAmount(objectId, taskId) end

---Compatibility predicate: unavailable reads can return false.
---@return boolean value
function IsDeathMatchGame() end

---Compatibility predicate: unavailable reads can return false.
---@param objectType integer
---@return boolean value
function IsObjectTypeAvailable(objectType) end

---Compatibility predicate: unavailable reads can return false.
---@param techId integer
---@return boolean value
function IsTechnologyResearched(techId) end

---Compatibility predicate: unavailable reads can return false.
---@param objectType integer
---@param isBuilding? boolean Defaults to false.
---@return boolean value
function CanAfford(objectType, isBuilding) end

---Assigned-player research availability; nil when unavailable.
---@param techId integer
---@return boolean|nil value
function CanResearch(techId) end

---Positive resource costs only; unavailable data can produce an empty table, not proof of a free technology.
---@param techId integer
---@return ResourceCost[] costs
---@return boolean available Ignore the cost table when false; an empty table alone does not prove zero cost.
function GetTechCost(techId) end

---Positive resource costs only; unavailable data can produce an empty table, not proof of a free object.
---@param objectType integer
---@param multiplier? number Defaults to 1.
---@return ResourceCost[] costs
---@return boolean available Ignore the cost table when false; an empty table alone does not prove zero cost.
function GetObjectCost(objectType, multiplier) end

---Matching objects from known world objects; an empty list does not prove world-query availability.
---@param objectType integer
---@return Object[] objects
function GetObjectsByType(objectType) end

---@param objectClass integer -1 accepts every known object; native and public class IDs are matched.
---@return Object[] objects
function GetObjectsByClass(objectClass) end

---Accepts a type list or variadic numeric types.
---@overload fun(firstType: integer, ...: integer): Object[]
---@param objectTypes integer[]
---@return Object[] objects
function GetObjectsByTypes(objectTypes) end

---Current native tile storage; nil and 0 when unavailable. Pointer lifetime is tied to the current map.
---@return lightuserdata|nil tiles
---@return integer count
function GetMapTilesPtr() end

---Row-major tile list, x varying fastest; empty when map dimensions are unavailable.
---@return MapTile[] tiles
function GetAllMapTiles() end


---Request native locked state for up to255 distinct owned gates. No explicit unlock option.
---@param gates Object|Object[]
---@return boolean accepted Queue admission only.
function LockGates(gates) end

---Tracked explicit lock. Receipt reports transport, not observed lock state.
---@param gates Object|Object[] Up to255 distinct owned gates.
---@return boolean accepted
---@return CommandReceipt receipt
function LockGatesTracked(gates) end