---@meta
-- Types for router scripts (routers/<id>/router.lua), for lua-language-server:
--   lua-language-server --check routers/<id> --configpath <a .luarc.json whose
--   "workspace.library" lists this folder>
-- The Router API is described in docs/router-api.md. Positions and sizes are in
-- the game's own units and axes (router.toml's `units`).

---A live object of the game (on Unreal: a UE4SS UObject). Its fields and
---methods are the game's own: `obj.Health`, `obj:SetHealth(50)`.
---@class GameObject
---@field [string] any

---@class Vector
---@field X number
---@field Y number
---@field Z number

---@class Rotator
---@field Pitch number
---@field Yaw number
---@field Roll number

---Where Fusion's origin goes in the game's world, and the way Fusion's forward faces.
---@class Anchor
---@field x number
---@field y number
---@field z number
---@field yaw number

---What the kit knows once the game is in its world.
---@class WorldInfo
---@field world GameObject
---@field controller GameObject
---@field pawn GameObject the game's own player character
---@field anchor Anchor

---What a game object is, for Fusion's entity registry.
---@class EntityInfo
---@field kind string e.g. "zombie"
---@field name? string shown in Fusion
---@field health? number
---@field max_health? number
---@field team? integer

---Functions a block can have. Which ones depends on the block (the kit says
---which when a field doesn't fit):
---world blocks: enter, ready, anchor, hidden; blocks that give `entities`:
---describe, spawn, actions.
---@class BlockFunctions
---Runs twice a second while the kit gets the game into its world (after it opened `bind.map`).
---@field enter? fun()
---Return false to keep waiting after the kit thinks the world is ready.
---@field ready? fun(player: GameObject): boolean?
---Where Fusion's origin goes (default: open ground near the player).
---@field anchor? fun(info: WorldInfo): Anchor
---Actors Fusion's captures don't draw (default: the player).
---@field hidden? fun(info: WorldInfo): GameObject[]
---What an object is: a table, false to leave it out, nil to let the data rules decide.
---@field describe? fun(object: GameObject, class: string, is_character: boolean): EntityInfo|false|nil
---Makes what Fusion asked for, feet at `at`; returns the new object, or nil.
---@field spawn? table<string, fun(at: Vector, rotation: Rotator, info: WorldInfo): GameObject?>
---Actions Fusion can run on the block's entities (`stun`, ...): true if done, false if not.
---Without one, the kit's own: remove, set_health, move_to, stop.
---@field actions? table<string, fun(entity: GameObject, args: number[]): boolean?>

---@class RouterApi
---@field id string the router's id
---@field name string
---@field data table the whole router.toml
---@field settings table<string, string> the scenario's block settings by id, as text (`[[block.setting]]`); filled when Fusion connects
Router = {}

---Gives a block from router.toml its functions: `Router.block "vein.world" { enter = function() ... end }`.
---@param id string a block id from router.toml
---@return fun(functions: BlockFunctions)
function Router.block(id) end

---Reflection and helpers. The same names on every kit.
Game = {}

---@param o any
---@return boolean
function Game.valid(o) end

---Seconds, for measuring waits.
---@return number
function Game.time() end

---Writes to the kit's log (`fusion_kit.log`).
---@param fmt string
---@param ... any
function Game.log(fmt, ...) end

---The first live object of a class (its short name, e.g. "PlayerController"), or nil.
---@param class string
---@return GameObject?
function Game.find(class) end

---Every live object of a class.
---@param class string
---@return GameObject[]
function Game.find_all(class) end

---An object by its full path ("/Script/Engine.Character"), or nil.
---@param path string
---@return GameObject?
function Game.object(path) end

---A class by path, loading its asset if needed ("/Game/Zombies/BP_Zombie").
---@param path string
---@return GameObject?
function Game.class(path) end

---@param o GameObject?
---@return string? # "BP_Zombie_C"
function Game.class_name(o) end

---@param o GameObject?
---@return string?
function Game.full_name(o) end

---True if `o` is of `class` (a class or its path) or a class made from it.
---@param o GameObject?
---@param class GameObject|string
---@return boolean
function Game.is_a(o, class) end

---A field by path ("Health.Health"), or nil if any part is missing.
---@param o GameObject
---@param path string
---@return any
function Game.get(o, path) end

---Sets a field by path; true if it worked.
---@param o GameObject
---@param path string
---@param value any
---@return boolean
function Game.set(o, path, value) end

---Calls a method by name: `Game.call(o, "SetHealth", 50)` is `o:SetHealth(50)`.
---@param o GameObject
---@param name string
---@param ... any
---@return any
function Game.call(o, name, ...) end

---Player controller 0, or nil.
---@return GameObject?
function Game.controller() end

---The game's own player character, or nil.
---@return GameObject?
function Game.player() end

---@return GameObject?
function Game.world() end

---The map the game is in: "/Game/Maps/Town".
---@return string
function Game.map() end

---Runs a console command; false if there's no player controller yet.
---@param command string
---@return boolean
function Game.console(command) end

---A line trace (what blocks sight): the point it hit, or nil.
---@param from Vector
---@param to Vector
---@param ignore? GameObject[]
---@return Vector?
function Game.trace(from, to, ignore) end

---Spawns an object of `class` (a class or its path) at `at`; the object, or nil.
---@param class GameObject|string
---@param at Vector
---@param rotation? Rotator
---@return GameObject?
function Game.spawn(class, at, rotation) end

---The live widget of this class that's on screen, or nil.
---@param class string
---@return GameObject?
function Game.widget(class) end

---True once the game finished loading the world around the player.
---@return boolean
function Game.loaded() end

---(Unity kit.) A static field or property of a game class, or a function calling its static
---method: `Game.static("GameManager", "m_Instance")`, `Game.static("GameManager", "GetPlayerManager")()`.
---@param class string the class's short name
---@param name string
---@return any
function Game.static(class, name) end

---(Unity kit.) Opens a scene by name; true if asked.
---@param name string
---@return boolean
function Game.load_scene(name) end

---(Unity kit.) A component of `class` on the same GameObject as `o` (or its children), or nil.
---@param o GameObject
---@param class string
---@return GameObject?
function Game.component(o, class) end

---(Unity kit.) What an object (or a class by name: its statics) has, for exploring a game: its class, its fields
---("name: Type") and methods ("Name(Type, ...)").
---@param o GameObject|string
---@return table
function Game.members(o) end

---(Unity kit.) Where an object is, in the game's space.
---@param o GameObject
---@return Vector?
function Game.position(o) end