---@meta engine
---
--- LSP type stubs for the Zig engine API.
--- This file is NEVER executed — it only exists so lua-language-server
--- can provide autocomplete, type checking, and inline docs.
---
--- Usage in your scripts:
---   ---@param self RectNode   (or NodeBase for base nodes)

-- ─── Color type ──────────────────────────────────────────────────────────────

---@class Color
---@field r number Red   0-255
---@field g number Green 0-255
---@field b number Blue  0-255
---@field a number Alpha 0-255

-- ─── Node self types ─────────────────────────────────────────────────────────

---@class NodeBase
---@field x    number World X position (read/write)
---@field y    number World Y position (read/write)

--- Extends NodeBase with rectangle geometry.
--- The engine draws the rect each frame; modify fields to change it.
---@class RectNode : NodeBase
---@field width  number Rectangle width
---@field height number Rectangle height
---@field color  Color  Fill color (r/g/b/a subtable)

-- ─── Drawing ─────────────────────────────────────────────────────────────────

---@param x number
---@param y number
---@param w number
---@param h number
---@param r number Red   0-255
---@param g number Green 0-255
---@param b number Blue  0-255
---@param a? number Alpha 0-255 (default 255)
function draw_rect(x, y, w, h, r, g, b, a) end

---@param x      number
---@param y      number
---@param radius number
---@param r      number
---@param g      number
---@param b      number
---@param a?     number
function draw_circle(x, y, radius, r, g, b, a) end

---@param text string
---@param x    number
---@param y    number
---@param size number Font size in pixels
---@param r    number
---@param g    number
---@param b    number
---@param a?   number
function draw_text(text, x, y, size, r, g, b, a) end

---@param x1 number
---@param y1 number
---@param x2 number
---@param y2 number
---@param r  number
---@param g  number
---@param b  number
---@param a? number
function draw_line(x1, y1, x2, y2, r, g, b, a) end

-- ─── Input ───────────────────────────────────────────────────────────────────

--- Returns true while key is held.
---@param key integer Use Key.X constants
---@return boolean
function key_down(key) end

--- Returns true only on the first frame the key is pressed.
---@param key integer
---@return boolean
function key_pressed(key) end

--- Returns true while mouse button is held. 0=left 1=right 2=middle
---@param button integer
---@return boolean
function mouse_down(button) end

---@return number
function mouse_x() end

---@return number
function mouse_y() end

-- ─── Key constants ───────────────────────────────────────────────────────────

---@class KeyTable
---@field LEFT  integer
---@field RIGHT integer
---@field UP    integer
---@field DOWN  integer
---@field SPACE integer
---@field W     integer
---@field A     integer
---@field S     integer
---@field D     integer

---@type KeyTable
Key = {}

-- ─── Utility ─────────────────────────────────────────────────────────────────

---@param message string
function log(message) end