@@ -0,0 +1,608 @@
---@meta
-- Generated by usagi 0.6.1. Run `usagi refresh` to update.
-- Usagi API stubs for lua-language-server.
-- Declarations only; this file is never executed by the runtime.
---Pico-8 palette, indices 0-15.
---@class Usagi.Gfx
---@field COLOR_BLACK integer 0
---@field COLOR_DARK_BLUE integer 1
---@field COLOR_DARK_PURPLE integer 2
---@field COLOR_DARK_GREEN integer 3
---@field COLOR_BROWN integer 4
---@field COLOR_DARK_GRAY integer 5
---@field COLOR_LIGHT_GRAY integer 6
---@field COLOR_WHITE integer 7
---@field COLOR_RED integer 8
---@field COLOR_ORANGE integer 9
---@field COLOR_YELLOW integer 10
---@field COLOR_GREEN integer 11
---@field COLOR_BLUE integer 12
---@field COLOR_INDIGO integer 13
---@field COLOR_PINK integer 14
---@field COLOR_PEACH integer 15
gfx = { }
---Clears the screen to the given color.
---@param color integer a gfx.COLOR_* constant
function gfx . clear ( color ) end
---Draws text at (x, y) in the given color. Uses the bundled monogram
---font at its 16px design size (a 5×
---@param text string string to render
---@param x number left edge in game-space pixels
---@param y number top edge in game-space pixels
---@param color integer a gfx.COLOR_* constant
function gfx . text ( text , x , y , color ) end
---Draws a rectangle outline.
---@param x number left edge in game-space pixels
---@param y number top edge in game-space pixels
---@param w number width in pixels
---@param h number height in pixels
---@param color integer a gfx.COLOR_* constant
function gfx . rect ( x , y , w , h , color ) end
---Draws a filled rectangle.
---@param x number left edge in game-space pixels
---@param y number top edge in game-space pixels
---@param w number width in pixels
---@param h number height in pixels
---@param color integer a gfx.COLOR_* constant
function gfx . rect_fill ( x , y , w , h , color ) end
---Draws a circle outline centered at (x, y).
---@param x number center x in game-space pixels
---@param y number center y in game-space pixels
---@param r number radius in pixels
---@param color integer a gfx.COLOR_* constant
function gfx . circ ( x , y , r , color ) end
---Draws a filled circle centered at (x, y).
---@param x number center x in game-space pixels
---@param y number center y in game-space pixels
---@param r number radius in pixels
---@param color integer a gfx.COLOR_* constant
function gfx . circ_fill ( x , y , r , color ) end
---Draws a line from (x1, y1) to (x2, y2).
---@param x1 number start x in game-space pixels
---@param y1 number start y in game-space pixels
---@param x2 number end x in game-space pixels
---@param y2 number end y in game-space pixels
---@param color integer a gfx.COLOR_* constant
function gfx . line ( x1 , y1 , x2 , y2 , color ) end
---Sets a single pixel.
---@param x number x in game-space pixels
---@param y number y in game-space pixels
---@param color integer a gfx.COLOR_* constant
function gfx . pixel ( x , y , color ) end
---Draws a 16×
---`sprites.png` next to the game's main .lua; indices run left-to-right,
---top-to-bottom. Alpha-channel pixels render as transparent.
---@param index integer one-based sprite index (1 = top-left cell)
---@param x number destination left edge in game-space pixels
---@param y number destination top edge in game-space pixels
function gfx . spr ( index , x , y ) end
---Extended `spr`: draws a 16×
---indexing as `gfx.spr`.
---@param index integer one-based sprite index (1 = top-left cell)
---@param x number destination left edge in game-space pixels
---@param y number destination top edge in game-space pixels
---@param flip_x boolean flip horizontally (mirror left/right) when true
---@param flip_y boolean flip vertically (mirror top/bottom) when true
function gfx . spr_ex ( index , x , y , flip_x , flip_y ) end
---Draws an arbitrary (sx, sy, sw, sh) rectangle from `sprites.png` at
---(dx, dy) at its original size. `s*` args index into the source sheet
---in pixels; `d*` args are the destination on screen.
---@param sx number source rect left edge on `sprites.png` (pixels)
---@param sy number source rect top edge on `sprites.png` (pixels)
---@param sw number source rect width in pixels
---@param sh number source rect height in pixels
---@param dx number destination left edge in game-space pixels
---@param dy number destination top edge in game-space pixels
function gfx . sspr ( sx , sy , sw , sh , dx , dy ) end
---Extended `sspr`: source rect stretched to (dw, dh) at the destination
---with required flip flags. All ten args required; write a thin
---wrapper if a particular flag combination shows up often in your
---code.
---@param sx number source rect left edge on `sprites.png` (pixels)
---@param sy number source rect top edge on `sprites.png` (pixels)
---@param sw number source rect width in pixels
---@param sh number source rect height in pixels
---@param dx number destination left edge in game-space pixels
---@param dy number destination top edge in game-space pixels
---@param dw number destination width in pixels (stretches the source)
---@param dh number destination height in pixels (stretches the source)
---@param flip_x boolean flip horizontally (mirror left/right) when true
---@param flip_y boolean flip vertically (mirror top/bottom) when true
function gfx . sspr_ex ( sx , sy , sw , sh , dx , dy , dw , dh , flip_x , flip_y ) end
---Activates a post-process fragment shader. Loads `shaders/<name>.fs`
---(and optional `<name>.vs`) and runs it as the final pass when the
---game render target is blitted to the window. Pass nil to clear.
---On web the loader prefers `<name>_es.fs` (GLSL ES 100); on desktop
---it prefers `<name>.fs` (GLSL 330). Shader source live-reloads on
---save in `usagi dev`.
---@param name string|nil shader name (file stem under `shaders/`), or nil to clear
function gfx . shader_set ( name ) end
---Sets a uniform on the active shader. The value type drives the
---uniform type: a number maps to float, a 2/3/4-length numeric table
---maps to vec2 / vec3 / vec4. Queues the write; the engine flushes
---queued uniforms once per frame before the post-process pass.
---@param name string uniform name as declared in the shader source
---@param value number|number[] float, or {x, y} / {x, y, z} / {x, y, z, w}
function gfx . shader_uniform ( name , value ) end
---@class Usagi.Sfx
sfx = { }
---Plays a sound effect by name. Names are file stems from the `sfx/`
---directory next to the game's main .lua (e.g. `sfx/jump.wav` → "jump").
---Unknown names silently no-op. Calling while already playing restarts.
---@param name string file stem of a `.wav` under `sfx/`
function sfx . play ( name ) end
---@class Usagi.Music
music = { }
---Plays a music track once and stops at the end. Names are file stems
---from the `music/` directory next to the game's main .lua (e.g.
---`music/intro.ogg` → "intro"). Recognized extensions: ogg, mp3, wav,
---flac. Stops the currently-playing track first if there is one.
---Unknown names silently no-op. Callable from `_init` so a title
---track can start the moment the window opens.
---@param name string file stem under `music/`
function music . play ( name ) end
---Plays a music track and loops it forever. Stops the currently-
---playing track first. Callable from `_init`.
---@param name string file stem under `music/`
function music . loop ( name ) end
---Stops whatever music is currently playing. No-op when nothing is.
function music . stop ( ) end
---Abstract input actions. Each is a union over keyboard keys, gamepad
---buttons, and analog-stick directions:
---
---- LEFT: arrow left, A, dpad left, left stick left
---- RIGHT: arrow right, D, dpad right, left stick right
---- UP: arrow up, W, dpad up, left stick up
---- DOWN: arrow down, S, dpad down, left stick down
---- BTN1: Z, J; gamepad south face (Xbox A, PS Cross)
---- BTN2: X, K; gamepad east face (Xbox B, PS Circle)
---- BTN3: C, L; gamepad north + west face (Xbox Y/X, PS Triangle/Square)
---
---Mouse buttons (separate from the action constants above):
---
---- MOUSE_LEFT: left mouse button
---- MOUSE_RIGHT: right mouse button
---
---Source identifiers for `input.last_source()` and the source-aware
---`input.mapping_for`:
---
---- SOURCE_KEYBOARD: "keyboard"
---- SOURCE_GAMEPAD: "gamepad"
---@class Usagi.Input
---@field LEFT integer
---@field RIGHT integer
---@field UP integer
---@field DOWN integer
---@field BTN1 integer
---@field BTN2 integer
---@field BTN3 integer
---@field MOUSE_LEFT integer
---@field MOUSE_RIGHT integer
---@field SOURCE_KEYBOARD string
---@field SOURCE_GAMEPAD string
---@field KEY_A integer
---@field KEY_B integer
---@field KEY_C integer
---@field KEY_D integer
---@field KEY_E integer
---@field KEY_F integer
---@field KEY_G integer
---@field KEY_H integer
---@field KEY_I integer
---@field KEY_J integer
---@field KEY_K integer
---@field KEY_L integer
---@field KEY_M integer
---@field KEY_N integer
---@field KEY_O integer
---@field KEY_P integer
---@field KEY_Q integer
---@field KEY_R integer
---@field KEY_S integer
---@field KEY_T integer
---@field KEY_U integer
---@field KEY_V integer
---@field KEY_W integer
---@field KEY_X integer
---@field KEY_Y integer
---@field KEY_Z integer
---@field KEY_0 integer
---@field KEY_1 integer
---@field KEY_2 integer
---@field KEY_3 integer
---@field KEY_4 integer
---@field KEY_5 integer
---@field KEY_6 integer
---@field KEY_7 integer
---@field KEY_8 integer
---@field KEY_9 integer
---@field KEY_F1 integer
---@field KEY_F2 integer
---@field KEY_F3 integer
---@field KEY_F4 integer
---@field KEY_F5 integer
---@field KEY_F6 integer
---@field KEY_F7 integer
---@field KEY_F8 integer
---@field KEY_F9 integer
---@field KEY_F10 integer
---@field KEY_F11 integer
---@field KEY_F12 integer
---@field KEY_SPACE integer
---@field KEY_ENTER integer
---@field KEY_ESCAPE integer
---@field KEY_TAB integer
---@field KEY_BACKSPACE integer
---@field KEY_DELETE integer
---@field KEY_LEFT integer
---@field KEY_RIGHT integer
---@field KEY_UP integer
---@field KEY_DOWN integer
---@field KEY_LSHIFT integer
---@field KEY_RSHIFT integer
---@field KEY_LCTRL integer
---@field KEY_RCTRL integer
---@field KEY_LALT integer
---@field KEY_RALT integer
---@field KEY_BACKTICK integer
---@field KEY_MINUS integer
---@field KEY_EQUAL integer
---@field KEY_LBRACKET integer
---@field KEY_RBRACKET integer
---@field KEY_BACKSLASH integer
---@field KEY_SEMICOLON integer
---@field KEY_APOSTROPHE integer
---@field KEY_COMMA integer
---@field KEY_PERIOD integer
---@field KEY_SLASH integer
input = { }
---Returns true the frame any source bound to `action` first went down.
---@param action integer one of input.LEFT / RIGHT / UP / DOWN / BTN1 / BTN2 / BTN3
---@return boolean
function input . pressed ( action ) end
---Returns true while any source bound to `action` is held.
---@param action integer one of input.LEFT / RIGHT / UP / DOWN / BTN1 / BTN2 / BTN3
---@return boolean
function input . held ( action ) end
---Returns true the frame any source bound to `action` first went up
---(transitioned from held to released). Mirrors `input.pressed` for the
---release edge.
---@param action integer one of input.LEFT / RIGHT / UP / DOWN / BTN1 / BTN2 / BTN3
---@return boolean
function input . released ( action ) end
---Label of the active input source's primary binding for `action` (e.g.
---"Z" on keyboard, "Pad-A" on gamepad). Honors any keymap remap the
---player set via the pause menu's Configure Keys flow. Useful for
---rendering contextual control prompts. Returns `nil` for unknown
---actions or when the active source has no binding for `action`.
---@param action integer one of input.LEFT / RIGHT / UP / DOWN / BTN1 / BTN2 / BTN3
---@return string?
function input . mapping_for ( action ) end
---The input source that most recently fired any bound action. Returns
---`input.SOURCE_KEYBOARD` ("keyboard") or `input.SOURCE_GAMEPAD`
---("gamepad"). Switches only when a *bound* input fires, so menu keys
---and idle activity don't flip it.
---@return string matches one of input.SOURCE_KEYBOARD / input.SOURCE_GAMEPAD
function input . last_source ( ) end
---Cursor position in game-space pixels (so it lines up with `gfx.*`
---coords regardless of window size or pixel-perfect scaling). Returns
---two values: `x, y`. When the cursor sits over the letterbox bars,
---the values fall outside `0..usagi.GAME_W` / `0..usagi.GAME_H` —
---bounds-check before treating them as in-game coords.
---@return integer x game-space x in pixels
---@return integer y game-space y in pixels
function input . mouse ( ) end
---Returns true while the given mouse button is held.
---@param button integer one of input.MOUSE_LEFT / input.MOUSE_RIGHT
---@return boolean
function input . mouse_held ( button ) end
---Returns true the frame the given mouse button first went down.
---@param button integer one of input.MOUSE_LEFT / input.MOUSE_RIGHT
---@return boolean
function input . mouse_pressed ( button ) end
---Returns true the frame the given mouse button first went up
---(transitioned from held to released).
---@param button integer one of input.MOUSE_LEFT / input.MOUSE_RIGHT
---@return boolean
function input . mouse_released ( button ) end
---Returns true while the given keyboard key is held.
---
---Direct keyboard reads bypass the keymap override and gamepad
---bindings — prefer `input.held(action)` for game actions players
---should be able to remap or play with a controller. Use this for dev
---hotkeys (toggling debug overlays, F-key shortcuts) and for
---keyboard-and-mouse-only games.
---@param key integer one of the input.KEY_* constants
---@return boolean
function input . key_held ( key ) end
---Returns true the frame the given keyboard key first went down. See
---`input.key_held` for the bypass-the-keymap caveat.
---@param key integer one of the input.KEY_* constants
---@return boolean
function input . key_pressed ( key ) end
---Returns true the frame the given keyboard key first went up
---(transitioned from held to released). See `input.key_held` for the
---bypass-the-keymap caveat.
---@param key integer one of the input.KEY_* constants
---@return boolean
function input . key_released ( key ) end
---Show or hide the OS cursor over the game window. Persists until
---changed. Callable from `_init` so games can hide the cursor before
---the first frame draws (e.g. when rendering a custom in-game cursor).
---@param visible boolean true to show, false to hide
function input . set_mouse_visible ( visible ) end
---Returns true when the OS cursor is currently shown over the window.
---Reflects the latest `input.set_mouse_visible` call synchronously, so
---it's safe to use as part of a toggle:
---`input.set_mouse_visible(not input.mouse_visible())`.
---@return boolean
function input . mouse_visible ( ) end
---Engine-level info. The per-domain APIs (`gfx`, `input`) are top-level
---globals, not fields on this table.
---@class Usagi
---@field GAME_W number game render width in pixels
---@field GAME_H number game render height in pixels
---@field SPRITE_SIZE integer side length, in pixels, of one cell in `sprites.png` (drives `gfx.spr` indexing)
---@field IS_DEV boolean true under `usagi dev`; false for `usagi run` and compiled binaries
---@field elapsed number wall-clock seconds since session start; updated once per frame before _update
usagi = { }
---Measures `text` in the bundled font and returns its rendered size
---in pixels. Returns two values: `width, height`. Available from any
---callback (`_init`, `_update`, `_draw`) — useful for pre-computing
---layout once in `_init` and reusing the result every frame.
---@param text string string to measure
---@return integer width pixel width
---@return integer height pixel height (equals the font's line height)
function usagi . measure_text ( text ) end
---Persist a Lua table as JSON. Saves are per-game, namespaced by
---`game_id` from `_config()`. One file per game; nest your own
---structure inside (settings, run state, unlocks).
---@param t table table to serialize. functions, userdata, NaN, and cycles error
function usagi . save ( t ) end
---Read the persisted save table back. Returns `nil` on first run
---(no save file). Idiomatic call: `state = usagi.load() or { ... defaults ... }`.
---@return table?
function usagi . load ( ) end
---Config table returned by `_config()`. All fields optional except
---`game_id`, which is only required if you call `usagi.save` /
---`usagi.load`. Missing fields fall back to engine defaults.
---@class Usagi.Config
---@field name? string display name. Window title, macOS .app bundle directory, and (slugged) archive/binary names on `usagi export` (default: project directory name)
---@field pixel_perfect? boolean false (default) = any scale that fits the window while preserving aspect ratio; true = integer scale only with letterbox bars
---@field game_id? string reverse-DNS identifier (e.g. "com.you.mygame"), required for save/load
---@field icon? integer 1-based tile index into sprites.png to use as the window icon (same indexing as gfx.spr); omit for the default Usagi bunny
---@field game_width? number game render width in pixels (default 320). Tested range 160..640
---@field game_height? number game render height in pixels (default 180). Tested range 90..360
---@field sprite_size? integer side length, in pixels, of one cell in sprites.png (default 16). Drives gfx.spr indexing, the tilepicker tool's grid, and the window-icon slicer. sprites.png must be a multiple of this value on both axes.
---Optional. Returns engine config read once before the window opens.
---Omit if the defaults are fine.
---@return Usagi.Config?
function _config ( ) end
---Called once when the game starts. Use for loading assets and initializing state.
function _init ( ) end
---Called every frame to update game state. Runs before _draw.
---@param dt number delta-time: seconds since last frame
function _update ( dt ) end
---Called every frame to render. Runs after _update.
---@param dt number delta-time: seconds since last frame
function _draw ( dt ) end
---@class Usagi.Vec2
---@field x number
---@field y number
---@class Usagi.Rect
---@field x number
---@field y number
---@field w number
---@field h number
---@class Usagi.Circ
---@field x number
---@field y number
---@field r number
---Drop-in math/geometry helpers. Pure Lua, no engine state. Source
---lives in `runtime/util.lua` — read it for full implementations or
---fork it if you want different semantics.
---@class Usagi.Util
util = { }
---Clamps `v` into `[lo, hi]`.
---@param v number
---@param lo number
---@param hi number
---@return number
function util . clamp ( v , lo , hi ) end
---Returns -1, 0, or 1 according to the sign of `v`.
---@param v number
---@return integer
function util . sign ( v ) end
---Half-up rounding to the nearest integer. Pixel snapping is the
---driving use case in 2D pixel-art games.
---@param v number
---@return integer
function util . round ( v ) end
---Moves `current` toward `target` by at most `max_delta`, never
---overshooting. Per-frame smoothing primitive — pass a delta
---scaled by `dt` for frame-rate independence.
---@param current number
---@param target number
---@param max_delta number
---@return number
function util . approach ( current , target , max_delta ) end
---Linear interpolation. `t = 0` returns `a`, `t = 1` returns `b`.
---Values of `t` outside `[0, 1]` extrapolate (no clamping).
---@param a number
---@param b number
---@param t number
---@return number
function util . lerp ( a , b , t ) end
---Wraps `v` into `[lo, hi)`. Useful for cyclic values like angles or
---looped indexing. Works for negative `v`: `util.wrap(-1, 0, 4) == 3`.
---@param v number
---@param lo number
---@param hi number
---@return number
function util . wrap ( v , lo , hi ) end
---Boolean from time. Toggles `hz` times per second — the on/off
---interval is `1/hz` seconds. For invincibility flicker, UI blinks,
---low-health warnings.
---@param t number seconds
---@param hz number toggles per second
---@return boolean
function util . flash ( t , hz ) end
---Normalizes a `{x, y}` vector to unit length. Returns a new table;
---the input is unchanged. A zero vector returns `{x = 0, y = 0}`.
---@param v Usagi.Vec2
---@return Usagi.Vec2
function util . vec_normalize ( v ) end
---Distance between two `{x, y}` points.
---@param a Usagi.Vec2
---@param b Usagi.Vec2
---@return number
function util . vec_dist ( a , b ) end
---Squared distance between two `{x, y}` points. Cheaper than
---`vec_dist` (skips the sqrt); use for "is X closer than Y?" by
---comparing against `r * r`.
---@param a Usagi.Vec2
---@param b Usagi.Vec2
---@return number
function util . vec_dist_sq ( a , b ) end
---Builds a vector at `angle` (radians) with magnitude `len`. `len`
---defaults to 1 for a unit vector. Pair with `math.atan(dy, dx)` to
---convert any direction into a velocity.
---@param angle number radians
---@param len? number magnitude (default 1)
---@return Usagi.Vec2
function util . vec_from_angle ( angle , len ) end
---True when the `{x, y}` point is inside the rect `{x, y, w, h}`.
---Half-open: left/top edges are inside, right/bottom edges are
---outside. Matches typical sprite-rect hit testing.
---@param p Usagi.Vec2
---@param r Usagi.Rect
---@return boolean
function util . point_in_rect ( p , r ) end
---True when the `{x, y}` point is strictly inside the circle
---`{x, y, r}`. Points on the boundary are considered outside.
---@param p Usagi.Vec2
---@param c Usagi.Circ
---@return boolean
function util . point_in_circ ( p , c ) end
---True when the two AABBs share interior area. Edge-adjacent rects
---are considered non-overlapping.
---@param a Usagi.Rect
---@param b Usagi.Rect
---@return boolean
function util . rect_overlap ( a , b ) end
---True when the two circles overlap. Tangent circles are
---considered non-overlapping.
---@param a Usagi.Circ
---@param b Usagi.Circ
---@return boolean
function util . circ_overlap ( a , b ) end
---True when a circle and a rect overlap. Uses the closest-point
---method: clamp the circle center to the rect, test distance.
---@param c Usagi.Circ
---@param r Usagi.Rect
---@return boolean
function util . circ_rect_overlap ( c , r ) end
---Engine-level juice primitives: hitstop, screen shake, flash, and
---slow-motion. Each call sets per-session state that decays once per
---frame. Stacking rule across all four: longer duration wins; for
---the magnitude param, the latest call wins. Spam-calling is safe.
effect = { }
---Freezes the game's `_update` loop for `time` seconds. `_draw` keeps
---running so the world stays on-screen. The classic juice trick for
---weighty hits: pair with `effect.screen_shake` and `effect.flash` on
---impact. If a longer hitstop is already in flight, this call is a
---no-op (longer wins).
---@param time number seconds to freeze update
function effect . hitstop ( time ) end
---Shakes the rendered view for `time` seconds with up to `intensity`
---game-pixel offset. Magnitude decays linearly to zero across the
---duration. The shake is applied to the RT-to-screen blit, so
---overlays drawn outside the world (error, REC indicator) stay
---stable.
---@param time number seconds to shake
---@param intensity number maximum offset in game pixels (try 2-6)
function effect . screen_shake ( time , intensity ) end
---Flashes a full-screen overlay of palette color `color` over the
---rendered view for `time` seconds. Alpha decays linearly from
---opaque to transparent. White on hits, red on damage, etc.
---@param time number seconds the flash is visible
---@param color integer a gfx.COLOR_* constant
function effect . flash ( time , color ) end
---Scales the `dt` passed to `_update` for `time` seconds. `scale=0.5`
---is half-speed; `scale=0` freezes update (use `effect.hitstop` for
---that explicitly); `scale>1` plays faster. Wall-clock decay is
---unaffected; the slow_mo timer itself counts down at real time.
---@param time number seconds the scale is applied
---@param scale number dt multiplier; 0..1 for slow, >1 for fast
function effect . slow_mo ( time , scale ) end
harper