Lua API reference

Function form of `input.getAxis`. Convenient for legacy shims and event callbacks.

Returns the current value of a float input axis.

local yaw = input.getAxis("pointer.dragX")
self:setRotation(0, yaw * 180, 0)

Returns true while an input button is held.

if input.isPressed("gesture.open_palm") then
  game.playAnimation(self.id, "flap")
end

Removes an entity from the scene and destroys its physics body.

game.destroy("enemy_42")

Looks up an entity declared in the manifest by its ID.

local bird = game.findEntity("phoenix")
if bird then bird:setPosition(0, 1, 0) end

Spawns a new entity at runtime. Overloaded: - First arg is a string → spawn a registered prefab/asset by name (2nd arg optional position). - First arg is a table → spawn a primitive with `{ mesh, id?, position? }`.

local enemy = game.spawn("goblin", { x = 0, y = 0, z = -2 })
local cube = game.spawn({ mesh = "box", position = { x = 1, y = 0, z = 0 } })

Returns an entity's world-space axis-aligned bounding box.

local b = game.getBounds(self.id)
if b then game.log("height:", b.size_y) end

Returns an entity's current world position.

local p = game.getPosition(self.id)
if p then game.log(p.x, p.y, p.z) end

Sets an entity's world position.

game.move(self.id, { x = 0, y = 1, z = 0 })

Sets an entity's Euler rotation in **degrees**. Susceptible to gimbal lock — prefer `game.rotateQ` for accumulated rotations.

game.rotate(self.id, { x = 0, y = 90, z = 0 })

Sets an entity's rotation from a quaternion. No gimbal lock — preferred for frame-to-frame accumulated rotations.

game.rotateQ(self.id, 1, 0, 0, 0)  -- identity

Sets an entity's scale. Pass a single number for uniform scale, or `{x, y, z}` for per-axis scale.

game.scale(self.id, 1.5)
game.scale(self.id, { x = 1, y = 2, z = 1 })

Adds a dynamic cannon-es rigid body to the entity at runtime. If the entity already has a body this is a no-op.

game.addPhysics(self.id, { mass = 2, gravity = true })

Applies an instantaneous impulse to the entity's rigid body. Wakes sleeping bodies. No-op if the entity has no physics body.

game.push(self.id, { x = 0, y = 5, z = 0 })  -- jump

Cancels any in-flight tween on the entity.

Tweens any combination of entity properties to target values over a duration. Targets are a flat table keyed by property name — accepted keys include `position_x/y/z`, `rotation_x/y/z` (degrees), `scale_x/y/z`, and any entity property your `GameAPI` registers.

game.tween(self.id, { position_y = 2, rotation_y = 90 }, 0.5, "easeInOutQuad")

Returns the list of animation clip names available on an entity's model. Returns an empty array for entities without a model or with no clips.

for i, name in ipairs(game.listAnimations(self.id)) do game.log(name) end

Plays an animation clip on an entity. Returns `true` if the clip exists.

game.playAnimation(self.id, "flap", { loop = true, crossFadeDuration = 0.2 })

Plays an animation clip exactly once (loop=false, no crossfade). Returns `true` if the clip exists.

Stops the entity's current animation (if any) and returns the model to its bind pose.

Fades out **all** music channels simultaneously. Useful for scene transitions.

Fades a music channel's volume to zero over `duration` seconds, then stops it.

Plays a looping/long-running music track on a named channel. Music channels are independent: call `playMusic` with different `channel` strings to layer tracks. Use `game.setMusic` to adjust volume/pitch mid-playback.

game.playMusic("theme", { channel = "bg", volume = 0.4 })

Plays a one-shot sound effect. Sound names map to assets via the manifest's `sounds` table.

game.playSound("pop", { volume = 0.6 })

Adjusts volume and/or pitch on a playing music channel without restarting it.

game.setMusic("bg", { volume = 0.2, pitch = 1.2 })

Immediately stops music on the named channel.

Stops any currently-playing instances of the named sound.

Runs a callback once after `seconds`. Returns a timer ID you can cancel.

game.after(1.5, function() game.playSound("pop") end)

Cancels a timer returned by `game.after` or `game.every`. Unknown IDs are ignored.

Runs a callback repeatedly at `seconds` interval. Returns a timer ID.

local t = game.every(1, function() game.log("tick") end)
game.after(10, function() game.cancelTimer(t) end)

Fires a named event. All subscribers registered via `game.on(event, ...)` are called synchronously in registration order.

game.fireEvent("score", 10)

Subscribes a callback to a named event. Events can come from the runtime (collisions, gestures) or be fired from any script via `game.fireEvent`. For multiplayer-scoped events see `game.onPlayer`.

game.on("score", function(points) total = total + points end)

Returns the currently active player ID, set via `game.setActivePlayer`.

Subscribes to an event scoped to a specific player. Sugar for `game.on("p{playerId}_{event}", callback)`. Use with the multiplayer relay which dispatches phone-controller inputs as player-scoped events.

game.onPlayer(1, "swing", function(power) hit(1, power) end)

Sets the active player ID used by gameplay systems that route input/state by current player (e.g. turn-based games).

Removes a 3D UI text label.

Creates a 3D world-space text label. The label renders in the scene at the given coordinates and follows the camera orientation (billboarded).

local h = game.ui.text("HP: 10", { y = 2, size = 0.5 })

Replaces the content of an existing 3D UI text label.

Returns the currently active side set via `game.side.set`.

Instantiates a registered side-UI prefab (HUD/status/score widget) on a side of the Pepper's Ghost diamond.

Removes a side overlay by its handle.

Sets the active side for the Pepper's Ghost diamond viewport. Subsequent calls that omit a `side` argument use this value.

Sets the color of a named sub-element of a side prefab.

Updates a fill ratio (0..1) on a named sub-element of a side prefab — e.g. a progress bar's "bar" path.

Places a 2D text overlay on one face of the Pepper's Ghost diamond. Overlays are screen-space per side — they stay put as the user looks around.

local h = game.side.text("front", "Hello", { size = 48, anchor_y = 0.1 })

Destroys all runtime-spawned entities. Entities declared in the manifest are preserved.

Requests a scene transition. The client handles the actual navigation — typically maps `name` to a manifest and loads it.

game.loadScene("main_menu")

Adjusts bloom post-processing at runtime. Pass any subset of `{ intensity, threshold, radius }`; omitted keys keep their current value.

game.setBloom({ intensity = 1.5, threshold = 0.7 })

Sets the camera distance for the Pepper's Ghost viewport. No effect in standard viewport mode.

Spawns a one-shot visual effect at a world position. VFX names are registered by the runtime (e.g. sparkles, explosions).

game.vfx("sparkle", { x = 0, y = 1, z = 0, scale = 2 })

Slices an entity's mesh along a plane, producing two new entities. The plane is defined by a normal `{nx, ny, nz}` and an optional point `{px, py, pz}` (defaults to entity center). The original entity is destroyed.

local pieces = game.cut(self.id, { nx = 0, ny = 1, nz = 0 })
if pieces then pieces.pos:applyImpulse(0, 2, 0) end

Reads a key previously stored via `game.setSetting`.

Stores a key/value in the runtime settings bag. Used for cross-script communication and manifest-level tuning knobs.

Seconds since the Unix epoch — useful as a seed for `math.randomseed`.

math.randomseed(game.clock())

Writes any number of arguments to the in-UI debug console. The global `print(...)` is rewired to call this.

game.log("hp:", hp, "pos:", self:getPosition())

Standard Lua `print` is overridden to route through `game.log`, so all output appears in the runtime's in-UI debug console.

Applies a continuous force to the entity's rigid body (ignored if no physics body). Must be called every frame for sustained motion. Wakes sleeping bodies.

Applies an instantaneous impulse to the entity's rigid body. Wakes sleeping bodies. Use for jumps, knockbacks, projectile launches.

Destroys this entity.

self:destroy()

Returns the entity's world position as three separate numbers (not a table).

local x, y, z = self:getPosition()

Returns the entity's Euler rotation in **degrees** as three separate numbers.

Returns the entity's scale as three separate numbers.

Returns the entity's current rigid-body velocity as three numbers. Returns `(0, 0, 0)` if the entity has no physics body.

Sets the entity's world position.

self:setPosition(0, 1, 0)

Sets the entity's Euler rotation in **degrees**. Prefer `game.rotateQ` for accumulated frame-to-frame rotations (avoids gimbal lock).

Sets the entity's per-axis scale.

Directly sets the entity's rigid-body velocity. Ignored if no physics body.

Tweens a single named property on this entity. For multi-property tweens prefer `game.tween(self.id, {...}, duration, easing)`.

self:tween("position", { x = 0, y = 2, z = 0 }, 0.5, "easeInOutQuad")