--!strict
-- Type definitions of Fusion's addon API (Luau), for editors and agents: luau-lsp reads this as a
-- definitions file ("luau-lsp.types.definitionFiles": ["docs/types/fusion-addons.d.luau"]).
-- The API itself is in docs/lua-api.md; this file must match crates/fusion-lua/src/api.rs
-- (BUILD.md step 5.7, "types and schemas").

-- An entity of any game (or one of Fusion's props), as Fusion's entity registry has it.
export type Entity = {
	id: number,
	source: string, -- the block it comes from, or "fusion" for Fusion's props
	kind: string,
	name: string,
	pos: vector,
	health: number,
	maxHealth: number,
	team: number,
}

-- A block of the scenario being played.
export type Block = {
	id: string, -- its name in the scenario (instance)
	name: string,
	kind: string, -- world, character, npc_group, system, items
	router: string,
	actions: { string },
}

export type PropOptions = {
	pos: vector,
	shape: ("box" | "sphere" | "cylinder")?,
	velocity: vector?,
	color: string?, -- "#3a86ff" or a name like "red"
}

export type ToolDefinition = {
	name: string?,
	description: string?,
	-- Left click: where the player aimed, its surface's normal, and the entity there (or nil).
	onFire: (pos: vector, normal: vector, entity: Entity?) -> (),
	-- Right click.
	onAltFire: ((pos: vector, normal: vector, entity: Entity?) -> ())?,
}

-- Writes a line to the addon's log (on screen and in Fusion's log).
declare function log(...: any): ()
declare function print(...: any): ()
-- A vector in Fusion's space: meters, Y up, -Z forward.
declare function Vector(x: number?, y: number?, z: number?): vector

declare hook: {
	-- Events: "Fusion.KeyPressed" (key: string), "Fusion.Think" (dt: number),
	-- "Fusion.EntitySpawned" (entity), "Fusion.EntityRemoved" (id: number),
	-- "Fusion.EntityDamaged" (entity, amount: number), "Fusion.EntityDied" (entity),
	-- "Fusion.Signal" (name: string).
	add: (event: string, name: string, fn: (...any) -> ()) -> (),
	remove: (event: string, name: string) -> (),
}

declare Fusion: {
	version: string,
	-- Tells every addon and Device (their "Fusion.Signal" hooks, next frame).
	signal: (name: string) -> (),
	Prop: {
		-- Spawns one of Fusion's props; returns its number.
		spawn: (options: PropOptions) -> number,
	},
	Player: {
		eyePos: (...any) -> vector,
		aimDir: (...any) -> vector,
	},
	Entities: {
		-- Every entity, or those of one block ("fusion" for Fusion's props).
		all: (source: string?) -> { Entity },
		get: (id: number) -> Entity?,
		near: (pos: vector, radius: number) -> { Entity },
		-- Asks the entity's game to do one of its block's actions (Fusion's props: set_health,
		-- remove, freeze), with up to 8 numbers.
		act: (id: number, action: string, ...number) -> (),
		-- Walks it to `target` with Fusion's steering (its block must need steering).
		steer: (id: number, target: vector) -> (),
	},
	Tool: {
		-- A tool for the sandbox's Tools tab (M3).
		define: (id: string, tool: ToolDefinition) -> (),
	},
}

declare Blocks: {
	list: () -> { Block },
	sleep: (router: string) -> (),
	wake: (router: string) -> (),
}

declare HUD: {
	-- A message in the middle of the screen for `seconds` (default 3).
	toast: (text: string, seconds: number?) -> (),
	-- A line in the top right, by key; nil text removes it.
	text: (key: string, text: string?) -> (),
}

declare Experience: {
	win: (text: string?) -> (),
	lose: (text: string?) -> (),
}