Lua API

Called once when the script first loads, and again on every hot-reload and after every engine.load_scene(). Use this to look up object IDs with engine.find_object() and engine.find_objects_by_prefix(), reset animation state, and read any persisted state from engine.get_var().

Do not cache object IDs across hot-reloads in module-level Lua variables — the scene may have changed. Always re-discover them inside init().

Called every frame before rendering. dt is the frame delta time in seconds (capped; safe for physics and animation). All game logic, input polling, scoring, object movement, and scale/emissive animations go here.

Called on engine exit (before Vulkan teardown). Save any game state that must survive process restart using engine.set_var(). This is your last chance to write persistent data.

Return a short string shown in the engine's terminal status area (bottom line). Called every frame. Return "" to show nothing. Keep it under ~80 characters for clean display.

Returns the camera's world-space position as three separate floats. Y is vertical — the primary axis for height-based scoring.

local _, cy, _ = engine.get_camera_position()
if cy > peak_height then
    peak_height = cy
    score = (peak_height - spawn_y) * 100.0
end

Teleports the camera (and player) to the given world-space position. Used for respawning. Always follow with engine.set_vertical_velocity(0.0) to clear falling momentum.

local cx, cy, cz = engine.get_checkpoint()
engine.set_camera_position(cx, cy, cz)
engine.set_vertical_velocity(0.0)

Returns the normalised camera look direction. Useful for shooting, raycasting, or directional movement logic.

Returns the normalised camera right vector (perpendicular to forward in the horizontal plane). Use with forward for strafe-relative logic.

Returns a table describing the player's current physics state.

Directly sets the player's vertical velocity. Use to trigger a jump or cancel falling momentum on respawn. Engine gravity is −18.0 m/s².

Returns a snapshot of the current frame's input state. Read this once at the top of update().

local inp = engine.get_input()

-- One-shot: restart or advance level
if inp.key_just_pressed[KEY_R] then
    -- restart current level
elseif inp.key_just_pressed[KEY_N] then
    engine.load_scene(LEVELS[current_level + 1])
end

Returns wall-clock seconds as a double. Use for continuous animations: emissive pulses, scale breathe effects, rotation offsets.

local t = engine.get_time()

-- Hazard breathe: scale oscillates between 0.92 and 1.08
local breathe = 1.0 + 0.08 * math.sin(t * 2.5)
for _, hid in ipairs(hazard_ids) do
    engine.set_object_scale(hid, breathe)
end

-- Emissive pulse
local p = (math.sin(t * 3.0) + 1.0) * 0.5
engine.set_object_emissive(glow_id, 0.0, 1.0, 0.9, 2.0 + p * 3.0)

Returns the same dt passed to update(dt). Convenient for helper functions that don't receive dt as a parameter.

Looks up a scene object by its exact GLTF node name. Returns the integer ID, or 0 if not found.

function init()
    goal_id = engine.find_object("goal_pad")
    if goal_id == 0 then
        engine.print_status("WARNING: goal_pad not found")
    end
end

Returns true if id is non-zero and present in the current scene. Use as a guard before transform calls.

Returns the world-space position of the object's transform origin as three floats.

Moves the object to the given world-space position. Internally rebuilds the per-object BLAS and TLAS. Safe to call every frame for moving platforms and hazards.

Returns Euler rotation in degrees (YXZ order, matching the Ra Engine editor).

Sets Euler rotation in degrees (YXZ order). The primary tool for spinning hazard platforms.

-- Rotate all hazard spinners at 45°/sec on Y axis
spinner_angle = (spinner_angle + 45.0 * dt) % 360.0
for _, hid in ipairs(hazard_ids) do
    engine.set_object_rotation(hid, 0.0, spinner_angle, 0.0)
end

Returns the current scale as three floats. Default is 1, 1, 1. Minimum per-axis value enforced by the engine: 0.01. Use the current scale as the basis for lerp animations to avoid drift.

-- Ease goal pad scale toward 1.0 on reveal (pop-in)
local sx, _, _ = engine.get_object_scale(goal_id)
if sx < 0.99 then
    engine.set_object_scale(goal_id, sx + (1.0 - sx) * 0.15)
end

Sets object scale. Pass one value for uniform scale; pass three for non-uniform. Minimum component: 0.01.

-- Goal pad throbs between 1.0 and 1.15 on the finish screen
local sc = 1.0 + 0.15 * (math.sin(goal_scale_t * 0.8 * 2.0 * math.pi) + 1.0) * 0.5
engine.set_object_scale(goal_id, sc)

-- Checkpoint scale pop: arc up to 1.3 and back over 0.5s
local progress = 1.0 - (timer / 0.5)
local pop_sc = 1.0 + 0.3 * math.sin(progress * math.pi)
engine.set_object_scale(glow_id, pop_sc)

-- Non-uniform: wide flat platform
engine.set_object_scale(platform_id, 3.0, 0.3, 3.0)

Sets the emissive colour and intensity at runtime. Drives RTX GI — nearby geometry is lit by the emissive surface. intensity defaults to 1.0.

-- Checkpoint orange flash (4Hz, fading out over 1.2s)
local p = (math.sin(t * 4.0 * 2.0 * math.pi) + 1.0) * 0.5
engine.set_object_emissive(glow_id, 1.0, 0.5, 0.0, p * 6.0)

-- Goal pad glow (slow 1.5Hz cyan pulse)
engine.set_object_emissive(goal_glow_id, 0.0, 1.0, 0.9, 2.0 + p * 3.0)

-- Turn off
engine.set_object_emissive(glow_id, 0.0, 0.0, 0.0, 0.0)

Shows or hides an object in the ray-traced scene. Hidden objects are collapsed to a degenerate position in the BVH. Use for goal pad reveals, collectibles, and cinematic triggers. Combine with set_object_scale(id, 0.1) before revealing for a pop-in effect.

-- Reveal goal pad with a pop-in: start tiny, lerp to full size
engine.set_object_visible(goal_id, true)
engine.set_object_scale(goal_id, 0.1)   -- init() resets to 1.0 on reload

Returns six floats describing the world-space AABB of the object. Returns a degenerate zero-size AABB if the ID is invalid.

Returns the player's world-space AABB (a capsule approximation centred on camera position).

Convenience AABB overlap test between the player and a scene object. The primary method for checkpoint triggers, goal detection, and collectibles.

if goal_id and engine.player_overlaps_object(goal_id) then
    state        = "finished"
    goal_scale_t = 0.0
    engine.print_status("★ LEVEL COMPLETE!")
end

Returns a 1-indexed Lua table of all object IDs whose GLTF node name starts with prefix. Returns an empty table if none match. The preferred way to manage groups of similarly-named objects (hazard spinners, collectibles, checkpoints).

function init()
    -- Discover all hazard spinners: platform_hazard_01, _02, _03 ...
    hazard_ids = engine.find_objects_by_prefix("platform_hazard_")

    -- Reset each one to neutral scale
    for _, hid in ipairs(hazard_ids) do
        engine.set_object_scale(hid, 1.0)
    end

    engine.print_status("Hazards: " .. #hazard_ids)
end

Returns a 1-indexed Lua table of every GLTF node name in the current scene. Useful for debugging scene layout in init().

local names = engine.get_all_object_names()
engine.print_status(
    "Level " .. current_level .. "  |  Objects: " .. #names ..
    "  |  Hazards: " .. #hazard_ids
)

Requests a deferred scene transition. The new GLTF loads at the start of the next frame — the current update() finishes cleanly first. After load, the engine calls init() again so the script re-discovers objects in the new scene.

local LEVELS = {
    "scenes/launch_up_tutorial1.gltf",
    "scenes/launch_up_level1.gltf",
    "scenes/launch_up_level2.gltf",
    "scenes/launch_up_level3.gltf",
    "scenes/launch_up_level4.gltf",
    "scenes/launch_up_level5.gltf",
    "scenes/launch_up_level6.gltf",
    "scenes/launch_up_level7.gltf",
}

-- On level complete (KEY_N handler):
local next = current_level + 1
if next <= #LEVELS then
    engine.set_var("launch_up.level", next)
    engine.set_var("launch_up.peak_height", spawn_pos.y)
    engine.load_scene(LEVELS[next])
    -- init() is called automatically after the scene loads
end

Sets the respawn position. Call when the player reaches a new height tier or crosses a trigger zone. Typically also triggers a flash animation on the checkpoint glow object.

Returns the current respawn position. Use in the dead-state handler alongside set_camera_position().

local function do_respawn()
    local cx, cy, cz = engine.get_checkpoint()
    engine.set_camera_position(cx, cy, cz)
    engine.set_vertical_velocity(0.0)
    state = "exploring"
end

Stores a float value under an arbitrary string key.

Retrieves a stored value. Returns default if the key has never been set. Always provide a sensible default — the key won't exist on first run.

Prints a line to the engine's terminal status area. Transient — overwritten on the next call. Use for event notifications (checkpoint reached, level complete, debug info). Also captured by the F1 Console View.

Pushes score and height to the in-viewport HUD overlay (top-left bitmap font readout). Call every frame while playing.

local height_gained = peak_height - spawn_pos.y
engine.set_hud_data(score, height_gained)