---@meta
---@diagnostic disable: missing-fields
-- Empire at War / Forces of Corruption engine API stubs.
-- This file is never executed — the Lua Language Server reads it as definitions only.

-- ==================================================
-- Engine Object Types
-- ==================================================

---A player in the game (C++ PlayerWrapper userdata).
---@class PlayerWrapper
---@field Get_Name fun(): string
---@field Get_ID fun(): integer
---@field Get_Faction fun(): string
---@field Get_Credits fun(): number
---@field Is_Valid fun(): boolean
---@field Is_Human fun(): boolean
---@field Is_Ally fun(other: PlayerWrapper): boolean
---@field Is_Enemy fun(other: PlayerWrapper): boolean
---@field Select_Object fun(other: GameObjectWrapper)

---A game object instance (C++ GameObjectWrapper userdata).
---@class GameObjectWrapper
---@field Get_Type fun(): GameObjectTypeWrapper
---@field Get_Owner fun(): PlayerWrapper
---@field Get_Final_Blow_Player fun(): PlayerWrapper
---@field Get_Game_Scoring_Type fun(): GameObjectTypeWrapper
---@field Is_Valid fun(): boolean
---@field Is_Pool_Safe fun(): boolean
---@field Service_Wrapper fun()

---A game object type definition (C++ GameObjectTypeWrapper userdata).
---@class GameObjectTypeWrapper
---@field Get_Name fun(): string
---@field Is_Valid fun(): boolean

-- ==================================================
-- Script Object
-- ==================================================

---The engine-injected script context object.
---@class ScriptObject
---@field Debug_Should_Issue_Event_Alert fun(): boolean

---Engine-injected script context. Set by the engine before the script runs.
---@type ScriptObject
Script = {}

---Engine-injected object context. Set by the engine before the script runs.
---@type GameObjectWrapper
Object = {}

-- ==================================================
-- GlobalValue / ThreadValue
-- (callable table: GlobalValue("key") to get, GlobalValue.Set("key", val) to set)
-- ==================================================

---@class ValueStore
---@field Set fun(key: string, value: any)
---@operator call(string): any

---Persistent global value store shared across scripts.
---@type ValueStore
GlobalValue = {}

---Per-thread value store.
---@type ValueStore
ThreadValue = {}

-- ==================================================
-- Engine Global Functions
-- ==================================================

---Pumps services for the script.
function Pump_Service() end

---Compares two strings for equality (case-insensitive in FoC).
---@param a string
---@param b string
---@return boolean
function StringCompare(a, b) end

---Finds a player by name (e.g. "local", "empire", "rebel").
---@param name string
---@return PlayerWrapper
function Find_Player(name) end

---Returns the current game time in seconds.
---@return number
function GetCurrentTime() end

---Returns the ID of the current thread, or -1 if not in a thread.
---@return integer
function GetThreadID() end

---Returns the next pending event function, or nil if the queue is empty.
---@return (fun(...): any) | nil
function GetEvent() end

---Exits the current script.
function _ScriptExit() end

---Pops up a message box (internal engine call).
---@param message string
function _MessagePopup(message) end

---Sends a message to the script log (internal engine call).
---@param message string
function _ScriptMessage(message) end

---Sends a message to the debug output (internal engine call — note: typo in original source).
---@param message string
function _OuputDebug(message) end

---Dumps the current Lua call stack as a string.
---@return string
function DumpCallStack() end

---Sets the visibility of the named component.
---@param component string
---@param isVisible boolean
function GUI_Component_Visibility(component, isVisible) end

---Sets the text for the named component.
---@param component string
---@param text string
function GUI_Component_Text(component, text) end

---Sets the text color for the named component.
---@param component string
---@param r number
---@param g number
---@param b number
---@param a number
function GUI_Text_Color(component, r, g, b, a) end

---Sets the icon for the named component.
---@param component string
---@param icon string
---@param r number
---@param g number
---@param b number
---@param a number
function GUI_Button_Icon(component, icon, r, g, b, a) end

---Finds all objects matching the criteria.
---@param a any
---@param b any
---@param c any
---@param d any
---@return GameObjectWrapper[]
function Find_All_Objects_Of_Type(a, b, c, d) end