api

B--- id: api title: Engine API Reference sidebar_label: API Reference

Engine API Reference

The engine exposes a single global Engine table to all Lua scripts.
All subsystems are fields on that table.

Engine API overview

Engine.scene     -- scene graph
Engine.events    -- global event bus
Engine.input     -- input queries
Engine.time      -- timing
Engine.log       -- logging
Engine.data      -- persistent data / save state
Engine.coroutine -- managed coroutine scheduler
Engine.ui        -- RmlUi documents
Engine.world     -- creature spawning and lookup

---

Engine.scene

Engine.scene.find(name) → Node | nil

Find a node in the current scene by its unique name.
Returns nil if the node does not exist.

Finding a scene node

local helmet = Engine.scene.find("helmet")
if helmet then
    helmet:set_visible(false)
end

---

Node

Returned by Engine.scene.find. Represents a single scene node.

Method	Description
node:get_position()	Returns x, y, z
node:set_position(x, y, z)	Set world position
node:get_rotation()	Returns pitch, yaw, roll in degrees
node:set_rotation(pitch, yaw, roll)	Set rotation in degrees
node:set_scale(x, y, z)	Set uniform or non-uniform scale
node:set_visible(bool)	Show or hide the node
node:set_intensity(n)	Set light intensity (light nodes only)
node:set_color(r, g, b)	Set light colour (light nodes only)

Light and transform control

local sun = Engine.scene.find("sun")
sun:set_intensity(5.0)
sun:set_color(1.0, 0.9, 0.7)

local box = Engine.scene.find("crate")
box:set_rotation(0.0, 45.0, 0.0)

---

Engine.events

Global event bus. Any script can publish or subscribe to any named event.

Method	Description
Engine.events.on(event, fn)	Subscribe fn to event
Engine.events.off(event)	Unsubscribe all callbacks for event
Engine.events.fire(event)	Fire event, calling all subscribers immediately

Event subscription

Engine.events.on("door_open", function()
    Engine.scene.find("door_mesh"):set_visible(false)
end)

-- Trigger nodes in the scene fire their event name automatically when entered.
-- Scripts can also fire events manually:
Engine.events.fire("player_died")

---

Engine.input

Method	Returns	Description
Engine.input.is_down(action)	boolean	True while keybind action is held (from keybinds.json)
Engine.input.is_pressed(action)	boolean	True on the first frame the action is pressed
Engine.input.is_key_down(key)	boolean	Raw key check by name (e.g. "space", "left_shift")
Engine.input.mouse_delta()	dx, dy	Mouse cursor delta since last frame

Input polling

function on_update(dt)
    if Engine.input.is_down("forward") then
        -- move forward
    end

    local dx, dy = Engine.input.mouse_delta()
    -- use dx, dy for camera rotation
end

---

Engine.time

Method	Returns	Description
Engine.time.elapsed()	number	Seconds since scene start
Engine.time.delta()	number	Delta time for the current frame in seconds

Timing queries

local t  = Engine.time.elapsed()   -- total time running
local dt = Engine.time.delta()     -- same value as the on_update(dt) argument

---

Engine.log

Writes to the engine log file (logs/glitter.log).

Method	Level
Engine.log.debug(msg)	DEBUG
Engine.log.info(msg)	INFO
Engine.log.warn(msg)	WARN
Engine.log.error(msg)	ERROR

Logging

Engine.log.info("Player health: " .. tostring(hp))
Engine.log.warn("Missing spawn marker: " .. name)

---

Engine.data

Persistent key-value store backed by JSON files in gamedata:// (maps to the platform user-preferences directory via SDL_GetPrefPath).

Method	Description
Engine.data.load(uri)	Load a JSON file; returns a Lua table
Engine.data.save(uri, table)	Save a Lua table to a JSON file
Engine.data.get(key)	Get a dot-path value from runtime data (e.g. "player.health")
Engine.data.set(key, value)	Set a dot-path value in runtime data

Save/load game data

-- Save game
Engine.data.save("gamedata://save01.json", {
    player_health = 80,
    level = "cave_01"
})

-- Load game
local save = Engine.data.load("gamedata://save01.json")
Engine.log.info("Resuming at level: " .. save.level)

-- Runtime blackboard
Engine.data.set("player.health", 80)
local hp = Engine.data.get("player.health")

---

Engine.coroutine

Managed coroutine scheduler. Coroutines are ticked each frame by the engine — no manual resuming required.

Method	Description
Engine.coroutine.start(fn)	Wrap fn in a coroutine and register it
Engine.coroutine.wait(seconds)	Yield the current coroutine for the given duration

Coroutine example

function on_init()
    Engine.coroutine.start(intro_sequence)
end

function intro_sequence()
    local door = Engine.scene.find("entrance_door")
    door:set_visible(false)

    Engine.coroutine.wait(1.5)

    door:set_visible(true)
    Engine.events.fire("intro_done")
end

Engine.coroutine.wait must be called from inside a coroutine — calling it in on_update directly will error.

---

Engine.ui

RmlUi document management. Documents are defined in .rml (markup) and .rcss (styles) files under ui://.

Loading and showing

Loading an RmlUi document

local hud = Engine.ui.load("ui://hud/hud.rml")
hud:show()

Document methods

Method	Description
doc:show()	Make the document visible
doc:hide()	Hide without unloading
doc:close()	Unload and destroy the document
doc:set_inner_text(id, text)	Set the text content of element with the given id
doc:add_class(id, class)	Add a CSS class to an element
doc:remove_class(id, class)	Remove a CSS class from an element

Document methods

hud:set_inner_text("health_value", tostring(hp))
hud:add_class("health_bar", "critical")     -- triggers .critical CSS state
hud:remove_class("health_bar", "critical")

---

Engine.world

Creature spawning and lookup. See Creature & Brain for the full entity model.

Method	Returns	Description
Engine.world.spawn_creature(marker)	Creature	Spawn at a named marker node
Engine.world.find_creature(name)	Creature|nil	Look up a spawned creature by name
Engine.world.make_player_brain()	PlayerBrain	Create a human-input brain
Engine.world.make_creature_brain(uri)	CreatureBrain	Create an AI brain backed by a Lua script

Creature lookup

local boss = Engine.world.find_creature("boss")
if boss and boss:is_alive() then
    boss:take_damage(9999, nil)
end

---

URI schemes

All file references in the Engine API use URI schemes rather than raw paths.

Scheme	Maps to
scripts://	resources/testGame/scripts/
scenes://	resources/testGame/scenes/
textures://	resources/testGame/textures/
models://	resources/testGame/models/
materials://	resources/testGame/materials/
shaders://	resources/testGame/shaders/
ui://	resources/testGame/ui/
gamedata://	Platform user-preferences directory (SDL_GetPrefPath)