How Lua talks to the game

API Reference

Each scripted object runs a sandboxed Lua script. Use hooks like on_spawn and on_update, then move the object with self, read editor values with props, and react to controls with input.

Quickstart

Create a Scripted Object in the editor, open its Lua script, and add the hooks you need. Properties from the object overview show up as props.Name. Animation and sound rows are named slots you pass to anim.play and sound.play.

The host does not expose

  • Engine systems, files, networking, or raw C# types
  • require, load, io, os, package, or debug
  • Adding or removing engine components from Lua
  • Building widgets by C# class name — use kinds like button or text instead
Built-in tags

Player, Monster, NPC, Boss, Projectile, Collectable, Environment Block, Path, Tower, Tower Zone, and Spawner. Collision lights use numbers 1–5 that match the object overview (light 1 is the first light).

HUD shorthand

vars and ui.hud accept both display names and shortcuts: health / player_health → "Player Health", max_health → "Player Max Health", money → "Player Money", keys → "Number of Keys", quest → "Number Quest Objects", message → "Interactable Message", touching_interactable → "Touching Interactable", npc_text → "NPC Text", touching_npc → "Touching NPC". Tower Defense also maps td_money, td_life, wave, tower_cost, tower_range, tower_damage, selected_visible, tower_image, and related selected-tower fields.

EXAMPLE · LUA
function on_spawn()
  camera.follow()
  anim.play("Idle", { loop = true })
end

function on_update(dt)
  local x = input.stick()
  self.vx = x * (props.MoveSpeed or 8)
  if self.grounded and input.pressed("A") then
    self.vy = props.JumpPower or 10
    sound.play("Jump")
  end
end

function on_collision(hit)
  if hit:has_tag("Monster") and not self.invulnerable then
    self.hurt(1)
    sound.play("Hurt")
  end
end

sandbox

Sandbox

What your script can do, and what it cannot.

  • Engine systems, files, networking, or raw C# types
  • require, load, io, os, package, or debug
  • Adding or removing engine components from Lua
  • Building widgets by C# class name — use kinds like button or text instead
EXAMPLE · LUA
-- available
math  string  table  bit32  coroutine

-- stripped
-- io  os  package  debug
-- require  load  loadfile  dofile

hooks

Hooks

Optional functions the host calls. Skip any you do not need.

HOOK

function on_spawn()

Called once when this object enters the level.

Use this for camera.follow, a first anim.play, and other one-time setup. It is not a substitute for on_update.

EXAMPLE · LUA
function on_spawn()
  camera.follow()
  anim.play("Idle", { loop = true })
end
HOOK

function on_update(dt)

Called every frame with elapsed seconds.

Use this for movement and input polling. Keep it cheap. Objects off-camera skip updates unless self.always_update is true or the object is the player. Avoid adding UI widgets here unless you must — outside on_ui_build there is a cap of 4 successful adds per frame.

Parameters

dtnumberSeconds since the last update.
EXAMPLE · LUA
function on_update(dt)
  local x, y = input.stick()
  self.vx = x * props.MoveSpeed
end
HOOK

function on_collision(hit)

Called once for each physics contact this frame.

hit is a handle for the other collider — you cannot read a C# type name from it. Contacts come from the physics pass that already ran this frame.

Parameters

hithitHandle for the other collider.
EXAMPLE · LUA
function on_collision(hit)
  if hit:has_tag("Monster") and not self.invulnerable then
    self.hurt(1)
    sound.play("Hurt")
  end
end
HOOK

function on_interact(who)

Called when something interacts with this object.

who is a hit handle for the interacting entity (usually the player). Any return value is ignored; the host only needs the function to exist and run.

Parameters

whohitHit handle for the interacting entity.
EXAMPLE · LUA
function on_interact(who)
  if who:has_tag("Player") then
    conversation.start("MayorQuest", { speaker = self })
  end
end
HOOK

function on_reaction(kind, slot)

Called when an editor animation or sound reaction fires.

Reactions are set up in the object overview; Lua does not replace that list. kind is usually "anim" or "sound". slot is the property name when one exists.

Parameters

kindstringReaction kind, such as anim or sound.
slotstringProperty slot name that fired.
EXAMPLE · LUA
function on_reaction(kind, slot)
  if kind == "anim" then
    -- editor reaction overlays still run in C#
  end
end
HOOK

function on_conversation_line(arc, index, node)

A dialogue line was shown.

Fires when the conversation enters a dialogue node.

Parameters

arcstringDisplay name of the Conversation Arc.
indexnumberConversation index inside the arc.
nodenumberDialogue node id.
EXAMPLE · LUA
function on_conversation_line(arc, index, node)
  anim.play("Talk", { loop = true })
end
HOOK

function on_conversation_choice(option)

A reply option was chosen.

Uses the same numbering as conversation.choose.

Parameters

optionnumberOption index starting at 1.
EXAMPLE · LUA
function on_conversation_choice(option)
  if option == 1 then
    vars.set("HelpedMayor", true)
  end
end
HOOK

function on_conversation_end(arc)

The active conversation finished or was stopped.

A good place to restore an idle animation.

Parameters

arcstringDisplay name of the Conversation Arc.
EXAMPLE · LUA
function on_conversation_end(arc)
  anim.play("Idle", { loop = true })
end
HOOK

function on_conversation_hook(id)

A FireHook action on a conversation node ran.

Use this to set variables or spawn rewards without putting game logic in the arc asset.

Parameters

idstringHook id from the conversation inspector.
EXAMPLE · LUA
function on_conversation_hook(id)
  if id == "give_key" then
    vars.set("HasTownKey", true)
  end
end
HOOK

function on_ui_build(screen)

Called once at bind time with the live overlay screen.

Build or find widgets here — not every frame. Look up named widgets before adding so hot reload does not create duplicates. Adds in this hook do not count against the per-frame cap.

Parameters

screenscreenHandle for the current overlay screen.
EXAMPLE · LUA
function on_ui_build(screen)
  local hp = screen:find("hp")
  if hp == nil then
    hp = screen:add("text", { name = "hp", x = 0.05, y = 0.05, width = 0.2, height = 0.08 })
  end
  hp:bind("text", "Player Health")
end
HOOK

function on_ui_action(hook, widget)

A button with action = "lua" was clicked.

hook is a string saved on the screen asset (not a Lua function), so it works through the UI editor.

Parameters

hookstringThe hook string stored on the button.
widgetwidgetHandle for the clicked widget.
EXAMPLE · LUA
function on_ui_action(hook, widget)
  if hook == "shop.open" then
    ui.screen.open("Shop")
  end
end
HOOK

function on_tap(x, y)

Called when this object is tapped / clicked.

x and y are world coordinates. Only objects that define on_tap are scanned, so empty frames stay cheap.

Parameters

xnumberWorld X.
ynumberWorld Y.
EXAMPLE · LUA
function on_tap(x, y)
  spawn.at(props.Bullet, x, y)
end
HOOK

function on_inventory_changed()

Called when this object's inventory contents change.

Fires after add/remove/use/clear/place on this brain's inventory. Use it to refresh UI or flags.

EXAMPLE · LUA
function on_inventory_changed()
  vars.set("HasKey", inventory.has("Red Key"))
end

util

Math helpers

Pico-8 style helpers plus math.mid. No cart memory peek/poke.

METHOD

rnd(range?) → number

Random number from 0 up to (but not including) range.

Default range is 1. Zero or NaN range returns 0. Uses the host RNG seeded by srand.

Parameters

rangeoptionalnumberOptional upper bound. Defaults to 1.

Returns. number — Random number.

EXAMPLE · LUA
local roll = rnd(10)
local unit = rnd()
METHOD

srand(seed)

Reseed the host random number generator.

Affects later rnd and math.random calls in this script.

Parameters

seednumberSeed value (floored).
EXAMPLE · LUA
srand(42)
METHOD

flr(n) → number

Floor a number (Pico-8 style).

Same as math.floor.

Parameters

nnumberNumber to floor.

Returns. number — math.floor(n).

EXAMPLE · LUA
local tile = flr(self.x)
METHOD

abs(n) → number

Absolute value (Pico-8 style global).

Same as math.abs.

Parameters

nnumberInput number.

Returns. number — Absolute value.

EXAMPLE · LUA
local dist = abs(hit.x - self.x)
METHOD

mid(a, b, c) → number

Median of three numbers.

Handy for clamping: mid(lo, value, hi).

Parameters

anumberFirst value.
bnumberSecond value.
cnumberThird value.

Returns. number — The middle value.

EXAMPLE · LUA
local hp = mid(0, self.health, self.max_health)
METHOD

t() → number

Seconds since this script started.

Advances each script update. Alias of time().

Returns. number — Elapsed seconds.

EXAMPLE · LUA
if t() > 3 then
  anim.play("Idle")
end
METHOD

time() → number

Alias for t().

Same clock as t().

Returns. number — Elapsed seconds.

EXAMPLE · LUA
local elapsed = time()
METHOD

math.mid(a, b, c) → number

Median of three numbers on the math table.

Also available as the global mid. Standard math.abs/floor/ceil/min/max/random/sqrt/sin/cos remain available.

Parameters

anumberFirst value.
bnumberSecond value.
cnumberThird value.

Returns. number — The middle value.

EXAMPLE · LUA
local v = math.mid(0, value, 1)
METHOD

math.randomseed(seed)

Reseed math.random (same generator as srand).

Alias path for scripts that prefer math.randomseed.

Parameters

seednumberSeed value.
EXAMPLE · LUA
math.randomseed(42)

self

self

This object's position, velocity, health, lights, and destroy.

PROP

self.x → number

World X of this object's transform.

Read/write. If there is no transform, reads return 0 and writes are ignored. Writing wakes a sleeping physics body so gravity applies again after a teleport — pair with self.vx = 0 and self.vy = 0 if you want to cancel old speed.

Returns. number — World position X.

EXAMPLE · LUA
self.x = self.x + 1
local here = self.x
PROP

self.y → number

World Y of this object's transform.

Read/write. If there is no transform, reads return 0 and writes are ignored. Like self.x, writing wakes physics so the object does not hang in mid-air after a teleport.

Returns. number — World position Y.

EXAMPLE · LUA
self.y = self.y + 0.5
PROP

self.vx → number

Rigidbody velocity X.

Read/write. If there is no rigidbody, reads return 0 and writes are ignored. Prefer this over setting self.x every frame when the object has physics.

Returns. number — Velocity X.

EXAMPLE · LUA
local x = input.stick()
self.vx = x * props.MoveSpeed
PROP

self.vy → number

Rigidbody velocity Y.

Read/write. Jump by assigning a positive or negative value depending on your gravity direction.

Returns. number — Velocity Y.

EXAMPLE · LUA
if self.grounded and input.pressed("A") then
  self.vy = props.JumpPower
end
PROP

self.gravity → number

How strongly scene gravity pulls this object.

Read/write scale. 1 is full weight (default), 0 ignores scene gravity, negative reverses it. Needs a rigidbody — without one, reads return 0 and writes do nothing. Pair with scene.gravity for world-wide pull.

Returns. number — Gravity scale.

EXAMPLE · LUA
self.gravity = 0
-- ignore scene gravity (astronaut)

self.gravity = 1
-- normal weight
PROP

self.angle → number

Z rotation in radians.

Read/write. 0 keeps an up-facing sprite pointing +Y. Use math.atan2(dx, dy) to aim toward a direction — for example input.stick2() for a look stick.

Returns. number — Rotation in radians.

EXAMPLE · LUA
local dx, dy = input.stick2()
self.angle = math.atan2(dx, dy)
PROP

self.grounded → boolean

Whether this object is standing on the floor.

Read returns the floor probe (blocking colliders count; triggers, walls, ceilings, and bounce pads usually do not). You can also write true to latch grounded for the rest of this frame so a jump in the same on_update sees it — the next ground probe clears that latch. Writing false only clears the latch; a real floor contact still reads grounded. Only true/false apply. Without a ground check, reads are false and writes are ignored.

Returns. boolean — true when standing on ground (or latched this frame).

EXAMPLE · LUA
function on_collision(hit)
  -- latch when the floor probe misses a block you still count as ground
  if hit.ny > 0.5 then
    self.grounded = true
  end
end

function on_update(dt)
  if self.grounded and input.pressed("A") then
    self.vy = props.JumpPower
  end
end
PROP

self.health → number

Current hit points.

Read/write. Writing also updates the play HUD health field when one exists.

Returns. number — Current health.

EXAMPLE · LUA
if self.health <= 0 then
  anim.play("Die", { loop = false, hold = true })
end
PROP

self.max_health → number

Maximum hit points.

Read/write. Used by hurt() when clamping health.

Returns. number — Maximum health.

EXAMPLE · LUA
self.health = self.max_health
PROP

self.invulnerable → boolean

true while the object cannot take damage (i-frames).

Read-only. Check this before applying contact damage.

Returns. boolean — Whether damage should be ignored.

EXAMPLE · LUA
if hit:has_tag("Monster") and not self.invulnerable then
  self.hurt(1)
end
PROP

self.visible → boolean

Whether this object's sprite is drawn.

Read/write. Hiding does not disable collision. Prefer self.show / self.hide for clarity.

Returns. boolean — Whether the sprite is visible.

EXAMPLE · LUA
self.visible = false
self.show()
self.hide()
PROP

self.alpha → number

Sprite opacity from 0 to 1.

Read/write. Values outside 0–1 clamp and warn once. Does not change visible or collision.

Returns. number — Opacity.

EXAMPLE · LUA
self.alpha = 0.5
PROP

self.tint → string

Sprite RGB tint as #rrggbb.

Read/write. Accepts #rrggbb or #rgb. Does not change alpha.

Returns. string — Tint hex string.

EXAMPLE · LUA
self.tint = "#ff8844"
METHOD

self.show()

Show this object's sprite.

Same as self.visible = true.

EXAMPLE · LUA
self.show()
METHOD

self.hide()

Hide this object's sprite.

Same as self.visible = false. Collision still works.

EXAMPLE · LUA
self.hide()
PROP

self.name → string

This object's display name.

Read-only.

Returns. string — Display name.

EXAMPLE · LUA
local n = self.name
PROP

self.tag → string

One primary tag name for this object.

Read-only. Prefer hit:has_tag / collision.overlaps_tag to test a specific tag.

Returns. string — Primary tag, or empty.

EXAMPLE · LUA
local t = self.tag
PROP

self.inventory → inventory

This object's inventory handle.

Same methods as the global inventory table, but pinned to this entity (chests, shops, NPCs).

Returns. inventory — Inventory API for this object.

EXAMPLE · LUA
self.inventory.add("Red Key")
PROP

self.always_update → boolean

Keep this script updating even when off-camera.

Read/write. Managers, spawners, and HUD drivers should set this true in on_spawn. Players usually keep updating without it.

Returns. boolean — Whether off-camera updates are forced.

EXAMPLE · LUA
function on_spawn()
  self.always_update = true
end
METHOD

self.has_light(light) → boolean

true if this object's collision light is enabled.

Reads the overview lights on this entity. Overlap tests still use collision.overlaps_light or hit:has_light.

Parameters

lightnumberLight index from 1 to 5.

Returns. boolean — Whether this object has that light enabled.

EXAMPLE · LUA
if self.has_light(1) then
  -- this object's light 1 is on in the overview
end
METHOD

self.hurt(amount)

Apply damage using the engine health rules.

Respects invulnerability and updates HUD health. Prefer this over subtracting self.health by hand if you want the same rules as default players.

Parameters

amountnumberDamage to apply.
EXAMPLE · LUA
self.hurt(1)
METHOD

self.destroy()

Queue this object for removal.

Removal happens later in the add/remove pass. The rest of this callback may still run, so return soon after calling it.

EXAMPLE · LUA
if self.health <= 0 then
  self.destroy()
end

props

props

Object-overview properties by name. Lua cannot add new ones.

PROP

props.Name → number | boolean | string | prefab | anim | sound | nil

Read an object-overview property by name.

Supports float, int, bool, and string. Scene and UI-screen slots return the display name. Animation, sound, and prefab slots return handles you can pass to anim.play, sound.play, spawn.at, or fx.draw. Missing names are nil.

Returns. any — The property value, handle, or nil.

EXAMPLE · LUA
local speed = props.MoveSpeed
if speed == nil then speed = 8 end
self.vx = speed
spawn.at(props.Bullet, self.x, self.y)
PROP

props.Name = value

Write a numeric, bool, or string property.

Cannot create new overview rows. Cannot write scene or UI screen slots. Unknown names warn once.

Parameters

valuenumber | boolean | stringValue matching the property type.
EXAMPLE · LUA
props.MoveSpeed = 12

objects

objects

Project prefabs by display name, including reading their properties.

PROP

objects.Name → prefab | nil

Look up a project prefab by display name.

Missing names are nil. Assignments warn and are ignored. Pass the handle to spawn.at, or read properties with prefab:prop.

Returns. prefab | nil — A prefab handle, or nil.

EXAMPLE · LUA
spawn.at(objects.Slime, self.x, self.y)
local cost = objects.Cannon:prop("Cost")
PROP

prefab.name → string

Display name of a prefab handle.

Handles come from objects.Name or props prefab slots.

Returns. string — Prefab display name.

EXAMPLE · LUA
local n = objects.Bullet.name
METHOD

prefab:prop(name) → any

Read a property from the prefab without spawning it.

Useful for tower costs, ranges, and other authored numbers.

Parameters

namestringProperty name (display or internal).

Returns. any — The value, or nil.

EXAMPLE · LUA
local range = objects.Cannon:prop("Range")

anim

anim

Play clips from this object's animation slots.

METHOD

anim.play(slot | clip, options?)

Start a clip from an animation slot name or handle.

Looks up this object's animation property by name, or accepts an anim handle from props. Unknown slots warn and do nothing. Options: loop (default true), hold, restart, flip_x / flipX, flip_y / flipY. Finish hooks: on_end / callback / done as a function, or set / done as a global bool name to flip false→true when the clip ends (finish hooks force loop = false unless you override).

Parameters

slotstring | animAnimation slot name or anim handle.
optionsoptionaltableOptional table of loop, hold, restart, flip_x, flip_y, on_end, set, done.
EXAMPLE · LUA
anim.play("RunRight", { loop = true, restart = false })
anim.play("Die", { loop = false, hold = true })
anim.play(props.Walk, { flip_x = true })
anim.play("Attack", { restart = true, loop = false, on_end = function()
  attacking = false
end })
METHOD

anim.stop()

Stop the sprite animator on this object.

Does nothing (with a warning) if the object has no animator.

EXAMPLE · LUA
anim.stop()

sound

sound

Play clips from this object's sound slots.

METHOD

sound.play(slot | clip, options?)

Play a clip from a sound slot name or handle.

Looks up AudioClip properties by name, or accepts a sound handle from props. One-shots play and finish on their own. Pass { loop = true } to loop. Unknown names warn once.

Parameters

slotstring | soundSound slot name or sound handle.
optionsoptionaltableOptional table. loop: boolean.
EXAMPLE · LUA
sound.play("Jump")
sound.play(props.Music, { loop = true })
METHOD

sound.stop(slot | clip)

Stop a playing sound by slot or clip handle.

Accepts an overview sound slot name or a sound handle from props.

Parameters

slotstring | soundSound slot name or sound handle.
EXAMPLE · LUA
sound.stop("Music")
METHOD

sound.stop_all()

Stop every sound started by this script host.

Useful when leaving a level or opening a pause screen.

EXAMPLE · LUA
sound.stop_all()
METHOD

sound.set_volume(slot | clip, volume)

Set volume for one playing sound.

Volume is typically 0–1.

Parameters

slotstring | soundSound slot name or sound handle.
volumenumberVolume 0–1.
EXAMPLE · LUA
sound.set_volume("Music", 0.4)
METHOD

sound.set_volume_all(volume)

Set volume for all sounds from this script.

Applies the same gain to every clip started by this script host.

Parameters

volumenumberVolume 0–1.
EXAMPLE · LUA
sound.set_volume_all(0.5)

input

input

Stick, buttons, touch, pinch, and which object is controlled.

METHOD

input.stick() → x, y

Left stick movement as x and y from -1 to 1.

Returns two numbers: horizontal and vertical tilt of the mapped left stick (or equivalent D-pad / WASD). Neutral is 0, 0. Full right is about 1, 0; full up depends on your world's Y direction. Use local x, y = input.stick().

Returns. number, number — Horizontal tilt, vertical tilt.

EXAMPLE · LUA
local x, y = input.stick()
self.vx = x * 8
self.vy = y * 8
METHOD

input.stick2() → x, y

Joystick 2 movement as x and y from -1 to 1.

Same shape as input.stick, but reads Joystick 2 (the second on-screen stick, or arrow keys on desktop). Use it for aiming or looking while input.stick handles movement. Neutral is 0, 0. Use local x, y = input.stick2().

Returns. number, number — Horizontal tilt, vertical tilt.

EXAMPLE · LUA
local aimX, aimY = input.stick2()
if math.abs(aimX) > 0.1 or math.abs(aimY) > 0.1 then
  self.facing_x = aimX
  self.facing_y = aimY
end
METHOD

input.pressed(name) → boolean

true on the frame a control was first pressed.

Names: A, B, X, Y, Interact, Left, Right, Up, Down, Touch. Left/Right/Up/Down also count when the stick moves past a 0.1 deadzone. Unknown names warn once and return false.

Parameters

namestringControl name.

Returns. boolean — Whether the control was pressed this frame.

EXAMPLE · LUA
if input.pressed("A") then
  self.vy = 10
end
METHOD

input.held(name) → boolean

true while a control is held down.

Same names as input.pressed.

Parameters

namestringControl name.

Returns. boolean — Whether the control is currently held.

EXAMPLE · LUA
if input.held("B") then
  spawn.at(props.Bullet, self.x, self.y)
end
METHOD

input.released(name) → boolean

true on the frame a control was released.

Same names as input.pressed.

Parameters

namestringControl name.

Returns. boolean — Whether the control was released this frame.

EXAMPLE · LUA
if input.released("Interact") then
  vars.set("ShowPrompt", false)
end
METHOD

input.touch() → held, x, y

Primary pointer: whether it is held, plus world X/Y.

Finger or left mouse, converted through the camera to world space. When the pointer lifts, the last known position is kept.

Returns. boolean, number, number — held, world X, world Y.

EXAMPLE · LUA
local held, x, y = input.touch()
if held then
  self.x = x
  self.y = y
end
METHOD

input.touch_claimed() → boolean

true when HUD / overlay UI already took the pointer this frame.

Not limited to the possessed player — camera scripts can skip a pan under the HUD.

Returns. boolean — Whether UI claimed the pointer.

EXAMPLE · LUA
if input.touch_claimed() then return end
METHOD

input.ui_blocking() → boolean

Alias for input.touch_claimed.

Same check as input.touch_claimed.

Returns. boolean — Whether UI claimed the pointer.

EXAMPLE · LUA
if input.ui_blocking() then return end
METHOD

input.screen() → x, y

Primary pointer position in world space.

Same coordinates as input.touch, without the held flag.

Returns. number, number — world X, world Y.

EXAMPLE · LUA
local x, y = input.screen()
METHOD

input.ui() → x, y

Primary pointer in overlay UI coordinates (0–1).

Returns x, y with origin at the top-left, matching Lua UI widget layout. Pair with screen:hit. Unlike input.screen, this is not world space.

Returns. number, number — UI X, UI Y.

EXAMPLE · LUA
local ux, uy = input.ui()
local w = ui.screen.current():hit(ux, uy)
METHOD

input.pinch() → active, scale

Two-finger pinch (or mouse wheel) zoom gesture.

Returns active, scale. Scale is 1 on the first active frame. Returns false, 1 when input is disabled for this object.

Returns. boolean, number — active flag, pinch scale.

EXAMPLE · LUA
local active, scale = input.pinch()
if active then
  camera.zoom(camera.level() * scale, 0)
end
METHOD

input.possess(player | options?)

Give player controls to this object or a named player.

Call with no args to control self. Pass a display name or { player = "Hero" } / { name = "Hero" } to control another entity.

Parameters

playeroptionalstring | tableOptional player name string or options table.
EXAMPLE · LUA
function on_spawn()
  input.possess()
end

input.possess("Hero")
input.possess({ player = "Hero" })
METHOD

input.enabled() → boolean

Whether this object currently receives player input.

Possession and set_enabled both affect this.

Returns. boolean — true when stick, buttons, and touch queries can succeed.

EXAMPLE · LUA
if not input.enabled() then return end
METHOD

input.set_enabled(value)

Enable or disable player input for this object.

Disabled objects still exist; stick and button queries return idle values.

Parameters

valuebooleantrue to accept input, false to ignore it.
EXAMPLE · LUA
input.set_enabled(false)

collision

collision / hit

Overlap checks, tags, paths, and the hit handle from on_collision.

METHOD

collision.overlaps_light(light) → boolean

true if this object overlaps a volume with that collision light.

Light numbers are 1–5 and match the object overview. Invalid light numbers return false.

Parameters

lightnumberLight index from 1 to 5.

Returns. boolean — Whether any overlapping volume has that light.

EXAMPLE · LUA
if collision.overlaps_light(1) then
  facing = -facing
end
METHOD

collision.has_light_at(x, y, light) → boolean

true if a world point sits on a tileset cell with that collision light.

Unlike overlaps_light, this samples a point — useful at the feet or slightly into a surface. Extra lights on the same cell still match. Light numbers are 1–5.

Parameters

xnumberWorld X.
ynumberWorld Y.
lightnumberLight index from 1 to 5.

Returns. boolean — Whether that painted light is present at the point.

EXAMPLE · LUA
if collision.has_light_at(self.x, self.y - 0.1, 2) then
  -- standing on a hazard tile
end
METHOD

collision.overlaps_tag(tag) → boolean

true if this object's collider overlaps an entity with that tag.

Built-in names: Player, Monster, NPC, Boss, Projectile, Collectable, Environment Block, Path, Tower, Tower Zone, Spawner. Custom Design tags work too. Some stock C# monsters, projectiles, collectables, towers, and spawners match even without the Pocket tag.

Parameters

tagstringTag display name.

Returns. boolean — Whether an overlapping entity has the tag.

EXAMPLE · LUA
if collision.overlaps_tag("NPC") then
  vars.set("Touching NPC", true)
end
PROP

hit.is_tile → boolean

true if the other collider is tileset geometry.

Use this to ignore walls when you only care about objects.

Returns. boolean — Whether the contact is a tile.

EXAMPLE · LUA
function on_collision(hit)
  if hit.is_tile then return end
end
PROP

hit.is_trigger → boolean

true if the contact involves a trigger collider.

Trigger volumes still call on_collision.

Returns. boolean — Whether the contact is a trigger.

EXAMPLE · LUA
if hit.is_trigger then
  scene.load("Secret Room")
end
METHOD

hit:exists() → boolean

true if this hit still refers to a living object.

Use before mutating a stored hit handle.

Returns. boolean — Whether the other object is still valid.

EXAMPLE · LUA
if not hit:exists() then return end
PROP

hit.x → number

World X of the other entity.

Also available on hit handles from scene.tagged.

Returns. number — World position X.

EXAMPLE · LUA
local dx = hit.x - self.x
PROP

hit.y → number

World Y of the other entity.

Also available on hit handles from scene.tagged.

Returns. number — World position Y.

EXAMPLE · LUA
local dy = hit.y - self.y
PROP

hit.nx → number

Contact normal X.

Useful for turning around when walking into a wall (hit.nx * facing < 0).

Returns. number — Normal X.

EXAMPLE · LUA
if hit.nx * facing < 0 then
  facing = -facing
end
PROP

hit.ny → number

Contact normal Y.

The sign depends on which way is up in your world.

Returns. number — Normal Y.

EXAMPLE · LUA
if hit.ny < 0 then
  -- landed on something
end
METHOD

hit:has_light(light) → boolean

true if the other object has that collision light.

Same 1–5 numbering as collision.overlaps_light.

Parameters

lightnumberLight index from 1 to 5.

Returns. boolean — Whether the other object has the light.

EXAMPLE · LUA
if hit:has_light(3) then
  self.hurt(1)
end
METHOD

hit:has_tag(tag) → boolean

true if the other object has that tag.

Same tag rules as collision.overlaps_tag, including stock C# monsters.

Parameters

tagstringTag display name.

Returns. boolean — Whether the other object has the tag.

EXAMPLE · LUA
if hit:has_tag("Projectile") then
  sound.play("Hurt")
end
PROP

hit.name → string

Other object's display name.

Read-only. Empty when the handle is stale.

Returns. string — Display name.

EXAMPLE · LUA
local n = hit.name
PROP

hit.tag → string

One primary tag on the other object.

Read-only. Prefer hit:has_tag to test a specific name.

Returns. string — Primary tag, or empty.

EXAMPLE · LUA
local t = hit.tag
METHOD

hit:hurt(amount)

Deal damage to the other object.

Scripted objects use the same hurt path as self.hurt (including i-frames). Stock RPG monsters use their own hit handler. Amounts ≤ 0 do nothing.

Parameters

amountnumberDamage to apply.
EXAMPLE · LUA
if hit:has_tag("Monster") then
  hit:hurt(1)
end
METHOD

hit:knockback(amount?)

Knock this scripted object away from the contact.

Uses the same player knockback path as spikes and monsters. Amount defaults to 5 when omitted or ≤ 0. No-op without a contact normal. Call from on_collision on the object that should be pushed (usually the player).

Parameters

amountoptionalnumberOptional knockback strength. Defaults to 5.
EXAMPLE · LUA
if hit:has_tag("Spike") and not self.invulnerable then
  self.hurt(1)
  hit:knockback(5)
end
METHOD

hit:ride()

Ride the other object if it is a moving platform floor.

Call from on_collision. No-op unless the contact is a floor normal on a moving platform.

EXAMPLE · LUA
hit:ride()
METHOD

hit:collect() → boolean

Collect the other object as a pickup.

Coins play Collected plus their collect sound, then despawn. Returns false if it was already collecting. Non-pickup objects are removed immediately.

Returns. boolean — true if collection started.

EXAMPLE · LUA
if hit:has_tag("Collectable") then
  hit:collect()
  vars.add("Score", 1)
end
METHOD

hit:destroy()

Despawn the other object immediately.

Removes entities only — it does not clear painted tileset cells. Prefer hit:collect() for coins so they can play their collect animation and sound. Use hit:erase() to dig / clear a tileset cell.

EXAMPLE · LUA
if hit:has_tag("Projectile") then
  hit:destroy()
end
PROP

hit.inventory → inventory

The other object's inventory.

Stale handles still return an object; its calls no-op.

Returns. inventory — Inventory API for the other object.

EXAMPLE · LUA
hit.inventory.add("Coin")
METHOD

hit:erase() → boolean

Erase the painted tileset cell under this contact.

Works when hit.is_tile. Clears paint at the contact cell (same sampling as hit:has_light). Returns false if this is not a tile contact or the cell is already empty. Does not destroy entities — use hit:destroy() for that.

Returns. boolean — true if a painted cell was erased.

EXAMPLE · LUA
function on_collision(hit)
  if hit.is_tile and hit:has_light(1) then
    hit:erase()
  end
end
METHOD

hit:prop(name) → any

Read a property on the other object.

NPC templates use names like "Text", "Portrait Icon", and "Interactable".

Parameters

namestringProperty name (display or internal).

Returns. any — The value, or nil.

EXAMPLE · LUA
local text = hit:prop("Text")
if text ~= nil then
  vars.set("NPC Text", text)
end
METHOD

hit:set_prop(name, value) → boolean

Write a property on the other object.

Same rules as props.Name = value. Returns false when stale, unknown, or read-only.

Parameters

namestringProperty name.
valueanyValue to write.

Returns. boolean — true if the write succeeded.

EXAMPLE · LUA
hit:set_prop("Text", "Thanks!")
METHOD

hit:contains(x, y) → boolean

true if a world point lies inside this hit's cells.

For painted tilesets this checks painted cells. Otherwise it uses the object's single placement grid cell.

Parameters

xnumberWorld X.
ynumberWorld Y.

Returns. boolean — Whether the point is inside the hit.

EXAMPLE · LUA
if hit:contains(self.x, self.y) then
  -- standing on this zone / path cell
end
METHOD

hit:path_tile_count() → number

Number of painted path waypoints on this hit.

Path objects from smart tilesets expose ordered waypoints for walkers.

Returns. number — Waypoint count, or 0 if not a path.

EXAMPLE · LUA
local n = hit:path_tile_count()
METHOD

hit:path_tile(index) → ok, x, y

World position of a painted path waypoint.

Returns false when the index is out of range or the hit is not a path.

Parameters

indexnumberWaypoint index starting at 1.

Returns. boolean, number, number — ok flag, world X, world Y.

EXAMPLE · LUA
local ok, x, y = hit:path_tile(1)
if ok then
  self.x = x
  self.y = y
end

inventory

inventory

Add, remove, use, and place items for the player or a pinned object.

METHOD

inventory.add(item, count?) → boolean

Add an item stack to the player (or pinned) inventory.

Global inventory is the current player. self.inventory / hit.inventory pin to that object. Item is a prefab name, objects.Name, or stack display name. Count defaults to 1.

Parameters

itemstring | prefabPrefab name, objects ref, or stack name.
countoptionalnumberOptional count ≥ 1.

Returns. boolean — true if anything was added.

EXAMPLE · LUA
inventory.add("Red Key")
inventory.add(objects.Potion, 3)
METHOD

inventory.remove(item, count?) → number

Remove up to count of an item.

Removes as many as possible up to count. Returns the number actually removed.

Parameters

itemstring | prefabPrefab name, objects ref, or stack name.
countoptionalnumberOptional count. Default 1.

Returns. number — How many were removed.

EXAMPLE · LUA
local n = inventory.remove("Coin", 2)
METHOD

inventory.has(item) → boolean

true if at least one of that item is held.

True when count for that item is at least 1.

Parameters

itemstring | prefabPrefab name, objects ref, or stack name.

Returns. boolean — Whether the item is present.

EXAMPLE · LUA
if inventory.has("Red Key") then scene.load("Treasure") end
METHOD

inventory.count(item) → number

How many of that item are held.

Returns 0 when the item is not held.

Parameters

itemstring | prefabPrefab name, objects ref, or stack name.

Returns. number — Stack count.

EXAMPLE · LUA
local n = inventory.count("Coin")
METHOD

inventory.list() → table

All stacks as a table of { name, count } entries.

Order matches the inventory UI.

Returns. table — Array-style table.

EXAMPLE · LUA
for _, e in ipairs(inventory.list()) do
  -- e.name, e.count
end
METHOD

inventory.clear()

Remove every stack.

Refreshes inventory UI when present.

EXAMPLE · LUA
inventory.clear()
METHOD

inventory.use(item) → boolean

Consume one of an item (potions apply player stats when possible).

Removes one stack unit. Potions may also apply built-in player effects when the host supports them.

Parameters

itemstring | prefabPrefab name, objects ref, or stack name.

Returns. boolean — true if one was consumed/removed.

EXAMPLE · LUA
inventory.use("Potion")
METHOD

inventory.place(item, x, y) → hit | nil

Spawn one held item into the world and remove it from inventory.

Uses the same spawn budget as spawn.at.

Parameters

itemstring | prefabPrefab name, objects ref, or stack name.
xnumberWorld X.
ynumberWorld Y.

Returns. hit | nil — Hit handle for the spawned object, or nil.

EXAMPLE · LUA
local h = inventory.place("Crate", self.x + 1, self.y)

spawn

spawn

Create a prefab or overview object slot in the scene.

METHOD

spawn.at(name | prefab, x, y, options?)

Create a prefab at a world position.

Accepts an overview prefab handle (props.Bullet), a project prefab (objects.Slime), or a display name string. At most 8 successful spawns per script per frame. Direction options dir_x / dir_y default to (1, 0) when omitted or zero. Spawned objects run their own Lua.

Parameters

namestring | prefabPrefab handle, overview slot, or project object name.
xnumberWorld X.
ynumberWorld Y.
optionsoptionaltableOptional table. dir_x, dir_y aim projectiles.

Notes

  • Extra spawns beyond the cap warn once and do nothing.
EXAMPLE · LUA
spawn.at("Bullet", self.x + facing, self.y, { dir_x = facing, dir_y = 0 })
spawn.at(props.Bullet, self.x, self.y)
spawn.at(objects.Slime, self.x, self.y)

fx

fx

One-frame world sprites you redraw each update while they should show.

METHOD

fx.draw(clip, x, y, width?)

Draw a one-frame world sprite at a position.

Pass an anim handle (usually from props). Optional width scales the sprite in world units. At most 4 draws per object per frame; uses the first frame of the clip. Hidden automatically if not redrawn next update.

Parameters

clipanimAnim handle, usually props.SomeSlot.
xnumberWorld X.
ynumberWorld Y.
widthoptionalnumberOptional world width. Defaults to native size.

Notes

  • Extra draws beyond the cap warn once and do nothing.
EXAMPLE · LUA
function on_update(dt)
  local gx, gy = scene.grid(input.screen())
  fx.draw(props.RangeIndicator, gx, gy, props.Range * 2)
end

camera

camera

Follow, shake, pan, zoom, fade, and solid background color.

METHOD

camera.follow(options?)

Make the level camera follow this object or a named player.

side (default true) is side-scroller follow mode. Pass { side = false } for top-down. player / name follows another entity instead of the caller.

Parameters

optionsoptionaltableOptional table. side: boolean. player or name: string.
EXAMPLE · LUA
function on_spawn()
  camera.follow()
  -- camera.follow({ side = false })  -- top-down
  -- camera.follow({ player = "Hero" })
end
METHOD

camera.stop()

Stop following if this object (or a named follow) is the current target.

Does nothing if another object owns the camera. Can also release a named follow target.

EXAMPLE · LUA
camera.stop()
METHOD

camera.change_player(player | options?)

Follow and possess a player in one call.

A string follows and possesses that named entity with side-scroll true. An options table accepts side / side_scroll and player / name.

Parameters

playeroptionalstring | tableOptional player name string or options table.
EXAMPLE · LUA
camera.change_player("Hero")
camera.change_player({ player = "Hero", side = false })
METHOD

camera.shake(intensity?, duration? | options?)

Shake the following camera.

Default intensity and duration are about 0.35. Accepts positional args or { intensity / amount, duration / time }.

Parameters

intensityoptionalnumberShake strength.
durationoptionalnumber | tableSeconds, or an options table when used alone.
EXAMPLE · LUA
camera.shake(0.5, 0.4)
camera.shake({ intensity = 0.6, duration = 0.5 })
METHOD

camera.pan(x, y, duration? | options?)

Pan the camera to a world position.

Default duration is about 0.45s. Options may set relative = true to offset from the current camera position.

Parameters

xnumberWorld X, or ignored when using an options table as the first arg.
ynumberWorld Y.
durationoptionalnumber | tableSeconds, or an options table.
EXAMPLE · LUA
camera.pan(10, 0, 1)
camera.pan({ x = 2, y = 0, relative = true })
METHOD

camera.zoom(level, duration? | options?)

Animate the camera zoom level.

Accepts level + optional duration, or { level / zoom, duration / time }.

Parameters

levelnumberTarget zoom level.
durationoptionalnumber | tableSeconds, or an options table.
EXAMPLE · LUA
camera.zoom(1.5, 0.3)
camera.zoom({ level = 2, duration = 0.5 })
METHOD

camera.level() → number

Current camera zoom level.

Useful with input.pinch for multiplicative zoom.

Returns. number — Zoom level, defaulting to 1 when no camera exists.

EXAMPLE · LUA
local z = camera.level()
PROP

camera.x → number

Camera world X.

Read-only shortcut for the active follow camera position.

Returns. number — World X.

EXAMPLE · LUA
local cx = camera.x
PROP

camera.y → number

Camera world Y.

Read-only shortcut for the active follow camera position.

Returns. number — World Y.

EXAMPLE · LUA
local cy = camera.y
METHOD

camera.pos() → x, y

Camera world position as x, y.

Same values as camera.x and camera.y.

Returns. number, number — World X, world Y.

EXAMPLE · LUA
local x, y = camera.pos()
METHOD

camera.set(x, y | options)

Snap the camera to a world position.

Accepts x, y or { x, y }. Stops follow when you take manual control depending on host behavior — pair with camera.stop if needed.

Parameters

xnumber | tableWorld X, or options table.
yoptionalnumberWorld Y.
EXAMPLE · LUA
camera.set(10, 0)
camera.set({ x = 10, y = 0 })
METHOD

camera.move(dx, dy | options)

Nudge the camera by a world delta.

Accepts dx, dy or { x/dx, y/dy }.

Parameters

dxnumber | tableDelta X, or options table.
dyoptionalnumberDelta Y.
EXAMPLE · LUA
camera.move(1, 0)
METHOD

camera.following() → boolean

true if the camera is currently following a target.

Useful before camera.stop or when sharing the follow camera.

Returns. boolean — Whether follow mode is active.

EXAMPLE · LUA
if camera.following() then camera.stop() end
METHOD

camera.bounds() → left, bottom, right, top | nil

Visible world rectangle of the camera.

Returns left, bottom, right, top, or nil if no camera.

Returns. number, number, number, number | nil — left, bottom, right, top.

EXAMPLE · LUA
local l, b, r, t = camera.bounds()
METHOD

camera.screen_to_world(sx, sy) → x, y | nil

Convert overlay / screen coords to world.

Useful with input.ui coordinates.

Parameters

sxnumberScreen X.
synumberScreen Y.

Returns. number, number | nil — World X, world Y.

EXAMPLE · LUA
local x, y = camera.screen_to_world(ux, uy)
METHOD

camera.world_to_screen(wx, wy) → x, y | nil

Convert world coords to screen / overlay space.

Useful for overlay widgets that track a world object.

Parameters

wxnumberWorld X.
wynumberWorld Y.

Returns. number, number | nil — Screen X, screen Y.

EXAMPLE · LUA
local sx, sy = camera.world_to_screen(self.x, self.y)
METHOD

camera.fade_out(duration? | options?)

Fade the screen out.

Default duration is about 0.4s. Accepts a number or { duration / time }.

Parameters

durationoptionalnumber | tableSeconds, or an options table.
EXAMPLE · LUA
camera.fade_out(0.5)
METHOD

camera.fade_in(duration? | options?)

Fade the screen back in.

Default duration is about 0.4s. Accepts a number or { duration / time }.

Parameters

durationoptionalnumber | tableSeconds, or an options table.
EXAMPLE · LUA
camera.fade_in()
METHOD

camera.background(r, g, b, a? | options?)

Set the active scene background color.

RGB(A) as 0–255, or 0–1 if every RGB channel is ≤ 1. Also accepts an options table with r/g/b/a or a nested color table. Alpha defaults to 255. For parallax layer image, tiling, scroll, and visibility, use the background table instead — if the options include layer controls, camera.background forwards to background.set.

Parameters

rnumber | tableRed, or an options table.
goptionalnumberGreen.
boptionalnumberBlue.
aoptionalnumberOptional alpha.
EXAMPLE · LUA
camera.background(20, 24, 40)
camera.background({ r = 0.1, g = 0.1, b = 0.15 })
METHOD

camera.background_color(r, g, b, a? | options?)

Alias for camera.background.

Same arguments and color rules as camera.background.

Parameters

rnumber | tableRed, or an options table.
goptionalnumberGreen.
boptionalnumberBlue.
aoptionalnumberOptional alpha.
EXAMPLE · LUA
camera.background_color(0, 0, 0)

background

background

Edit scene parallax layers: image, tiling, scroll, tint, and visibility.

METHOD

background.set(layer | options, options?)

Change one or more properties on a parallax layer.

Pass a layer name or 1-based index plus an options table, or a single options table with layer / index. Names match the editor (back, mid, front, or a custom name). Index 1 is always the back layer. Options can include image / texture / sprite, scale, tile / tiling (none, x, y, xy), color, tint, move (parallax or auto), scroll_x / scroll_y, offset_x / offset_y, visible, in_front, and name.

Parameters

layerstring | number | tableLayer name, 1-based index, or options table.
optionsoptionaltableOptional property table when layer is passed first.
EXAMPLE · LUA
background.set("mid", {
  image = "Clouds",
  scale = 1.2,
  tile = "x",
  move = "parallax",
  scroll_x = 0.3,
})

background.set({
  layer = "back",
  color = { r = 20, g = 24, b = 40 },
})
METHOD

background.get(layer) → table | nil

Read the current settings for a parallax layer.

Returns a table with name, index, visible, scale, tile, move, scroll_x, scroll_y, offset_x, offset_y, in_front, has_image, color, tint, and image / image_name when an image is set. Returns nil if the layer is missing.

Parameters

layerstring | numberLayer name or 1-based index.

Returns. table | nil — Layer table, or nil.

EXAMPLE · LUA
local mid = background.get("mid")
if mid and mid.visible then
  background.scroll("mid", mid.scroll_x + 0.01, mid.scroll_y)
end
METHOD

background.image(layer, clip | false)

Set or clear a layer's image.

Accepts a project texture / animation name, an animation property handle (props.ParallaxArt), or false to clear. Unknown names warn once.

Parameters

layerstring | numberLayer name or 1-based index.
clipstring | anim | booleanImage name, animation handle, or false.
EXAMPLE · LUA
background.image("mid", "Mountains")
background.image("front", props.ParallaxArt)
background.image("mid", false)  -- clear
METHOD

background.texture(layer, clip | false)

Alias for background.image.

Same arguments as background.image.

Parameters

layerstring | numberLayer name or 1-based index.
clipstring | anim | booleanImage name, animation handle, or false.
EXAMPLE · LUA
background.texture("back", "Sky")
METHOD

background.clear_image(layer)

Remove the image from a layer.

Same as background.image(layer, false).

Parameters

layerstring | numberLayer name or 1-based index.
EXAMPLE · LUA
background.clear_image("mid")
METHOD

background.scale(layer, scale)

Set a layer's image scale.

Values below 1 are treated as 1.

Parameters

layerstring | numberLayer name or 1-based index.
scalenumberScale multiplier.
EXAMPLE · LUA
background.scale("mid", 1.5)
METHOD

background.tile(layer, "none" | "x" | "y" | "xy")

Set how a layer's image repeats.

Use "none", "x", "y", or "xy". Unknown modes warn once.

Parameters

layerstring | numberLayer name or 1-based index.
modestringnone, x, y, or xy.
EXAMPLE · LUA
background.tile("mid", "x")
background.tile("front", "xy")
METHOD

background.tiling(layer, "none" | "x" | "y" | "xy")

Alias for background.tile.

Same arguments as background.tile.

Parameters

layerstring | numberLayer name or 1-based index.
modestringnone, x, y, or xy.
EXAMPLE · LUA
background.tiling("mid", "y")
METHOD

background.color(layer, r, g, b, a? | color)

Set a layer's solid fill color.

On the back layer this also updates the scene background color (same as camera.background). RGB(A) as 0–255, or 0–1 if every RGB channel is ≤ 1.

Parameters

layerstring | numberLayer name or 1-based index.
rnumber | tableRed, or a color table.
goptionalnumberGreen.
boptionalnumberBlue.
aoptionalnumberOptional alpha.
EXAMPLE · LUA
background.color("back", 12, 18, 32)
background.color("back", { r = 0.05, g = 0.07, b = 0.12 })
METHOD

background.tint(layer, r, g, b, a? | color)

Tint the layer's image.

Same color rules as background.color. Does not replace the solid fill.

Parameters

layerstring | numberLayer name or 1-based index.
rnumber | tableRed, or a color table.
goptionalnumberGreen.
boptionalnumberBlue.
aoptionalnumberOptional alpha.
EXAMPLE · LUA
background.tint("mid", 255, 220, 200)
METHOD

background.move(layer, "parallax" | "auto")

Choose parallax-with-camera or auto-scroll motion.

Use "parallax" (default editor feel) or "auto" for continuous scroll using scroll_x / scroll_y as speeds.

Parameters

layerstring | numberLayer name or 1-based index.
modestringparallax or auto.
EXAMPLE · LUA
background.move("mid", "parallax")
background.move("clouds", "auto")
METHOD

background.scroll(layer, x, y)

Set parallax factors or auto-scroll speeds.

With move = parallax, values are camera-follow factors. With move = auto, values are scroll speeds.

Parameters

layerstring | numberLayer name or 1-based index.
xnumberX factor or speed.
ynumberY factor or speed.
EXAMPLE · LUA
background.scroll("mid", 0.4, 0.1)
METHOD

background.offset(layer, x, y)

Nudge a layer's draw position.

World-space offset applied after scroll / parallax.

Parameters

layerstring | numberLayer name or 1-based index.
xnumberOffset X.
ynumberOffset Y.
EXAMPLE · LUA
background.offset("front", 0, -2)
METHOD

background.in_front(layer, on)

Draw a mid/front layer in front of the level.

The back layer always stays behind the level; turning in_front on for it warns and does nothing.

Parameters

layerstring | numberLayer name or 1-based index.
onbooleantrue to draw in front of gameplay.
EXAMPLE · LUA
background.in_front("front", true)
METHOD

background.visible(layer) → boolean background.visible(layer, shown)

Read or set whether a layer is shown.

Call with one argument to read, or pass shown as the second argument to set.

Parameters

layerstring | numberLayer name or 1-based index.
shownoptionalbooleanOptional boolean when setting.

Returns. boolean — Whether the layer is visible (when reading).

EXAMPLE · LUA
if background.visible("mid") then
  background.visible("mid", false)
end
METHOD

background.show(layer)

Show a layer.

Same as background.visible(layer, true).

Parameters

layerstring | numberLayer name or 1-based index.
EXAMPLE · LUA
background.show("mid")
METHOD

background.hide(layer)

Hide a layer.

Same as background.visible(layer, false).

Parameters

layerstring | numberLayer name or 1-based index.
EXAMPLE · LUA
background.hide("front")
METHOD

background.rename(layer, name)

Rename a mid/front layer.

The back layer is always named "back" and cannot be renamed.

Parameters

layerstring | numberLayer name or 1-based index.
namestringNew layer name.
EXAMPLE · LUA
background.rename(2, "clouds")
METHOD

background.add(name? | options?) → string

Add a new parallax layer.

Optional name string, or an options table with name plus any background.set fields. Returns the created layer name. You cannot add a second back layer.

Parameters

nameoptionalstring | tableOptional name string or options table.

Returns. string — Created layer name, or empty on failure.

EXAMPLE · LUA
local name = background.add("clouds")
background.add({
  name = "fog",
  image = "Fog",
  tile = "x",
  move = "auto",
  scroll_x = 0.15,
})
METHOD

background.remove(layer) → boolean

Delete a mid/front layer.

The back layer cannot be removed. Returns false if the layer is missing or protected.

Parameters

layerstring | numberLayer name or 1-based index.

Returns. boolean — true if the layer was removed.

EXAMPLE · LUA
background.remove("fog")
METHOD

background.count() → number

How many parallax layers the scene has.

Includes the back layer.

Returns. number — Layer count, or 0 if there is no scene yet.

EXAMPLE · LUA
local n = background.count()
METHOD

background.layers() → table

Layer names in draw order, starting at 1.

Index 1 is always the back layer. Useful with ipairs.

Returns. table — Array-style table of layer names.

EXAMPLE · LUA
for i, name in ipairs(background.layers()) do
  print(i, name)
end

vars

vars

Design variables and built-in HUD fields.

METHOD

vars.get(name) → any

Read a Design variable or built-in HUD field.

Missing custom names return nil. Built-in HUD fields (Player Health, NPC Text, …) and their shortcuts always exist when the play HUD is up.

Parameters

namestringVariable or HUD field name.

Returns. any — The value, or nil.

EXAMPLE · LUA
if vars.get("HasRedKey") then
  scene.load("Treasure Room")
end

local hp = vars.get("health")  -- Player Health
METHOD

vars.has(name) → boolean

true if the name is a built-in HUD field or an existing variable.

Does not create anything.

Parameters

namestringVariable or HUD field name.

Returns. boolean — Whether the name is defined.

EXAMPLE · LUA
if not vars.has("Score") then
  vars.set("Score", 0)
end
METHOD

vars.set(name, value)

Write a variable. Creates a custom variable if it does not exist.

Infers bool / int / float / string from the Lua value. Built-in HUD names update the overlay instead of Design. Cannot invent reserved HUD display names as user variables.

Parameters

namestringVariable or HUD field name.
valueanyValue to store.
EXAMPLE · LUA
vars.set("HasRedKey", true)
vars.set("NPC Text", "Hello!")
vars.set("health", 3)
METHOD

vars.add(name, amount)

Add a number to a numeric variable or HUD field.

Creates a custom numeric variable if needed. Useful for Score and money.

Parameters

namestringVariable or HUD field name.
amountnumberAmount to add (can be negative).
EXAMPLE · LUA
vars.add("Score", 10)
vars.add("money", 5)

ping

ping

Send short messages between scripts after on_update.

METHOD

ping.on(name, handler)

Register a channel listener at the top of the script.

Only allowed while the script chunk loads (not inside on_update). Delivery runs after on_update on the scene step.

Parameters

namestringChannel name.
handlerfunctionfunction(value).
EXAMPLE · LUA
ping.on("door_open", function(msg)
  anim.play("Open")
end)
METHOD

ping.send(name, value?)

Queue a value on a channel for listeners.

Tables are copied with depth/size limits; functions cannot be sent. Delivered after on_update.

Parameters

namestringChannel name.
valueoptionalanyOptional payload.
EXAMPLE · LUA
ping.send("door_open")
ping.send("score", { points = 10 })

scene

scene

Load levels, find tagged objects, snap to the grid, and paint or erase tiles.

METHOD

scene.load(name, options?)

Go to another level by scene name.

Checks an overview scene slot first, then a project scene by name or file stem. Loading the current scene warns and does nothing. keep_state true keeps play-session state; false starts fresh.

Parameters

namestringScene name or overview slot name.
optionsoptionaltableOptional table. keep_state: boolean.
EXAMPLE · LUA
scene.load("Forest 2")
scene.load("Hub", { keep_state = true })
METHOD

scene.restart()

Restart the current level.

Uses the play overlay's restart path. Warns if no overlay exists.

EXAMPLE · LUA
if self.health <= 0 then
  scene.restart()
end
METHOD

scene.game_over(message?)

Show the level's game-over screen.

Same path players and classic Tower Defense use. The optional message is for lifecycle types that display one; some game types ignore it.

Parameters

messageoptionalstringOptional text shown on supported game-over screens.
EXAMPLE · LUA
if self.health <= 0 then
  scene.game_over("Try again!")
end
METHOD

scene.fallen_off() → boolean

true when this object has fallen below the tilemap.

Uses the same margin as stock shooters for fall death. Returns false when there is no tilemap / bounds yet.

Returns. boolean — Whether the object is below the map.

EXAMPLE · LUA
if scene.fallen_off() then
  scene.game_over()
end
METHOD

scene.td_spawning() → boolean

true while a Tower Defense spawner still has monsters left for the current wave.

Use this so a manager does not treat the wave as cleared between spawn gaps on the final wave.

Returns. boolean — Whether any Spawner-tagged object is still releasing monsters.

EXAMPLE · LUA
if not scene.td_spawning() and monster_count == 0 then
  -- wave cleared
end
METHOD

scene.tower_dragging() → boolean

true while a tower is being dragged from the Tower Defense tray.

Zones and managers read this to show build previews without inventing a Design variable. Pair with scene.set_tower_dragging.

Returns. boolean — Whether a tower drag is active.

EXAMPLE · LUA
if scene.tower_dragging() then
  -- show build zones while a tower is dragged from the tray
end
METHOD

scene.set_tower_dragging(on)

Set the Tower Defense tray-drag flag.

Call true when the player starts dragging a tower from the shop tray, and false when the drag ends or is cancelled.

Parameters

onbooleantrue while dragging, false when idle.
EXAMPLE · LUA
scene.set_tower_dragging(true)
-- ... place or cancel ...
scene.set_tower_dragging(false)
PROP

scene.gravity → number

Scene gravity Y acceleration.

Read/write. Same force player Game Gravity writes. Negative pulls down; 0 is zero-g for objects that still have self.gravity. Does nothing if the scene has no gravity force component.

Returns. number — Y acceleration.

EXAMPLE · LUA
scene.gravity = -30
-- pull down

scene.gravity = 0
-- zero-g for objects that still have self.gravity
METHOD

scene.current_name() → string

Display name of the active scene.

Empty when the object is not in a scene.

Returns. string — Scene name, or empty string.

EXAMPLE · LUA
local here = scene.current_name()
METHOD

scene.closest_tag(tag, max_range?) → ok, x, y

Find the nearest other entity with a tag.

Returns ok, x, y. max_range 0 or omitted means unlimited. Excludes self.

Parameters

tagstringTag display name.
max_rangeoptionalnumberOptional max distance. 0 = unlimited.

Returns. boolean, number, number — ok flag, world X, world Y.

EXAMPLE · LUA
local ok, x, y = scene.closest_tag("Monster", 8)
if ok then
  facing = x < self.x and -1 or 1
end
METHOD

scene.tagged(tag) → table

All entities with a tag, as hit handles.

Returned hits support position, tags, props, path queries, and contains. Contact normals are 0 when there was no physics contact.

Parameters

tagstringTag display name.

Returns. table — Array-style table of hit handles.

EXAMPLE · LUA
for _, h in ipairs(scene.tagged("Tower")) do
  -- h.x, h:has_tag(...), h:prop(...)
end
METHOD

scene.tagged_count(tag) → number

How many entities have that tag.

Cheaper than building the full scene.tagged table when you only need a count.

Parameters

tagstringTag display name.

Returns. number — Count.

EXAMPLE · LUA
local n = scene.tagged_count("Monster")
METHOD

scene.tagged_at(tag, index) → hit | nil

One tagged entity by 1-based index.

Pair with scene.tagged_count to iterate without allocating the full list every frame.

Parameters

tagstringTag display name.
indexnumberIndex starting at 1.

Returns. hit | nil — Hit handle, or nil.

EXAMPLE · LUA
local h = scene.tagged_at("Tower", 1)
METHOD

scene.grid(x, y) → gx, gy

Snap a world point to the scene placement grid.

Same grid math the editor and tower placement use.

Parameters

xnumberWorld X.
ynumberWorld Y.

Returns. number, number — Grid-snapped X, grid-snapped Y.

EXAMPLE · LUA
local gx, gy = scene.grid(input.screen())
METHOD

scene.occupied(tag, x, y) → boolean

true if another tagged entity shares that grid cell.

Excludes self. Pass world or already-snapped coordinates; occupancy compares grid cells.

Parameters

tagstringTag display name.
xnumberWorld X.
ynumberWorld Y.

Returns. boolean — Whether the cell is occupied.

EXAMPLE · LUA
local gx, gy = scene.grid(input.screen())
if not scene.occupied("Tower", gx, gy) then
  spawn.at(props.Tower, gx, gy)
end
METHOD

scene.erase_tile_at(x, y) → boolean

Erase a painted tileset cell at a world point.

Uses the same paint sampling as collision.has_light_at. Returns false when the point is empty, out of range, or no tileset owns the cell. For dig-on-contact, prefer hit:erase() in on_collision.

Parameters

xnumberWorld X.
ynumberWorld Y.

Returns. boolean — true if a painted cell was erased.

EXAMPLE · LUA
if scene.erase_tile_at(self.x, self.y) then
  sound.play("Dig")
end
METHOD

scene.paint_tile_at(x, y, light?) → boolean

Paint a tileset cell at a world point.

Same grid math as scene.erase_tile_at and collision.has_light_at. Omit light (or pass 0) to stamp with the last tileset in the scene. Pass light 1–5 to pick a tileset that has that collision light. Returns false if the cell is occupied, no matching tileset exists, or the light is invalid.

Parameters

xnumberWorld X.
ynumberWorld Y.
lightoptionalnumberOptional collision light 1–5. Omit or 0 uses the last tileset.

Returns. boolean — true if a cell was painted.

EXAMPLE · LUA
scene.paint_tile_at(self.x, self.y)
scene.paint_tile_at(self.x + 1, self.y, 1)

tiles

tiles

Query and edit painted tileset cells by world point or grid index.

METHOD

tiles.walkable(x, y) → boolean

true if ground/walk surface is painted and no obstacle.

World-point sample. Same grid as scene.paint_tile_at.

Parameters

xnumber
ynumber

Returns. boolean

EXAMPLE · LUA
if tiles.walkable(self.x, self.y) then end
METHOD

tiles.blocking(x, y) → boolean

true if an obstacle tileset is painted here.

A wall on a floor wins.

Parameters

xnumber
ynumber

Returns. boolean

EXAMPLE · LUA
if tiles.blocking(self.x + 1, self.y) then end
METHOD

tiles.occupied(x, y) → boolean

true if any tileset is painted here.

Includes triggers. Not the same as scene.occupied.

Parameters

xnumber
ynumber

Returns. boolean

EXAMPLE · LUA
if tiles.occupied(self.x, self.y) then end
METHOD

tiles.walkable_cell(col, row) → boolean

walkable for a grid cell.

Same as tiles.walkable, but takes column/row.

Parameters

colnumber
rownumber

Returns. boolean

EXAMPLE · LUA
if tiles.walkable_cell(3, 5) then end
METHOD

tiles.blocking_cell(col, row) → boolean

blocking for a grid cell.

Same as tiles.blocking for column/row.

Parameters

colnumber
rownumber

Returns. boolean

EXAMPLE · LUA
if tiles.blocking_cell(3, 5) then end
METHOD

tiles.occupied_cell(col, row) → boolean

occupied for a grid cell.

Same as tiles.occupied for column/row.

Parameters

colnumber
rownumber

Returns. boolean

EXAMPLE · LUA
if tiles.occupied_cell(3, 5) then end
METHOD

tiles.type(x, y) → string | nil

Winning tileset object name, or nil.

Empty cells return nil.

Parameters

xnumber
ynumber

Returns. string | nil

EXAMPLE · LUA
local name = tiles.type(self.x, self.y)
METHOD

tiles.type_cell(col, row) → string | nil

Winning tileset name for a grid cell.

Empty cells return nil.

Parameters

colnumber
rownumber

Returns. string | nil

EXAMPLE · LUA
local name = tiles.type_cell(3, 5)
METHOD

tiles.role(x, y) → string | nil

Collision role for the winning paint.

Ground, WalkSurface, Obstacle, Trigger, or a custom role. Nil when empty.

Parameters

xnumber
ynumber

Returns. string | nil

EXAMPLE · LUA
local r = tiles.role(self.x, self.y)
METHOD

tiles.role_cell(col, row) → string | nil

Collision role for a grid cell.

Same roles as tiles.role.

Parameters

colnumber
rownumber

Returns. string | nil

EXAMPLE · LUA
local r = tiles.role_cell(3, 5)
METHOD

tiles.slice(x, y) → string | nil

Autotile slice name being drawn.

Example: Tileset_Cap_Left. Nil when empty.

Parameters

xnumber
ynumber

Returns. string | nil

EXAMPLE · LUA
local s = tiles.slice(self.x, self.y)
METHOD

tiles.slice_cell(col, row) → string | nil

Autotile slice for a grid cell.

Nil when empty.

Parameters

colnumber
rownumber

Returns. string | nil

EXAMPLE · LUA
local s = tiles.slice_cell(3, 5)
METHOD

tiles.prop(x, y, name, tileset?) → any

Read a tileset bag property at a world point.

Optional tileset name disambiguates overlapping paints.

Parameters

xnumber
ynumber
namestring
tilesetoptionalstring

Returns. any

EXAMPLE · LUA
local v = tiles.prop(self.x, self.y, "Damage")
METHOD

tiles.prop_cell(col, row, name, tileset?) → any

Read a tileset bag property at a grid cell.

Optional tileset name disambiguates overlapping paints.

Parameters

colnumber
rownumber
namestring
tilesetoptionalstring

Returns. any

EXAMPLE · LUA
local v = tiles.prop_cell(3, 5, "Damage")
METHOD

tiles.cell(x, y) → col, row | nil

Grid column/row under a world point.

Nil when the scene has no tile grid.

Parameters

xnumber
ynumber

Returns. number, number | nil

EXAMPLE · LUA
local c, r = tiles.cell(self.x, self.y)
METHOD

tiles.world(col, row) → x, y | nil

World center of a grid cell.

Nil when out of range.

Parameters

colnumber
rownumber

Returns. number, number | nil

EXAMPLE · LUA
local x, y = tiles.world(3, 5)
METHOD

tiles.extent() → min_col, min_row, max_col, max_row | nil

Inclusive painted bounds.

min col, min row, max col, max row. Nil when nothing is painted.

Returns. number, number, number, number | nil

EXAMPLE · LUA
local x0, y0, x1, y1 = tiles.extent()
METHOD

tiles.count() → number

How many painted cells exist.

Across the active tile grid.

Returns. number

EXAMPLE · LUA
local n = tiles.count()
METHOD

tiles.cells(col0, row0, col1, row1) → table

Painted cells in a rectangle as a table.

Useful for band scans.

Parameters

col0number
row0number
col1number
row1number

Returns. table

EXAMPLE · LUA
local band = tiles.cells(0, 0, 10, 10)
METHOD

tiles.cell_count(col0, row0, col1, row1) → number

Painted cell count in a rectangle.

Does not allocate the full cell list.

Parameters

col0number
row0number
col1number
row1number

Returns. number

EXAMPLE · LUA
local n = tiles.cell_count(0, 0, 10, 10)
METHOD

tiles.cell_at(col0, row0, col1, row1, index) → col, row, walkable, blocking | nil

One painted cell in a rectangle by 1-based index.

Returns col, row, walkable, blocking.

Parameters

col0number
row0number
col1number
row1number
indexnumber

Returns. number, number, boolean, boolean | nil

EXAMPLE · LUA
local c, r, w, b = tiles.cell_at(0, 0, 10, 10, 1)
METHOD

tiles.tally(col0, row0, col1, row1) → walkable, blocking | nil

Walkable and blocking counts in a rectangle.

Returns walkable_count, blocking_count.

Parameters

col0number
row0number
col1number
row1number

Returns. number, number | nil

EXAMPLE · LUA
local walk, block = tiles.tally(0, 0, 10, 10)
METHOD

tiles.set(x, y, which?) → boolean

Paint a cell at a world point.

which is a tileset name or index. Same grid as scene.paint_tile_at.

Parameters

xnumber
ynumber
whichoptionalstring | number

Returns. boolean

EXAMPLE · LUA
tiles.set(self.x, self.y, "Grass")
METHOD

tiles.set_cell(col, row, which?) → boolean

Paint a grid cell.

which is a tileset name or index.

Parameters

colnumber
rownumber
whichoptionalstring | number

Returns. boolean

EXAMPLE · LUA
tiles.set_cell(3, 5, 1)
METHOD

tiles.clear(x, y, tileset?) → boolean

Erase paint at a world point.

Optional tileset name limits which layer is cleared.

Parameters

xnumber
ynumber
tilesetoptionalstring

Returns. boolean

EXAMPLE · LUA
tiles.clear(self.x, self.y)
METHOD

tiles.clear_cell(col, row, tileset?) → boolean

Erase paint at a grid cell.

Optional tileset name limits which layer is cleared.

Parameters

colnumber
rownumber
tilesetoptionalstring

Returns. boolean

EXAMPLE · LUA
tiles.clear_cell(3, 5)
METHOD

tiles.on_change(handler)

Register a callback when painted cells change.

handler(col, row). Register at script top when possible.

Parameters

handlerfunction
EXAMPLE · LUA
tiles.on_change(function(col, row)
  -- painted cell changed
end)

ui

ui

HUD fields, the NPC panel, and screens from the UI editor.

METHOD

ui.hud.get(key) → any

Read a play HUD field.

Same name map as vars.get for built-ins.

Parameters

keystringHUD field name or shortcut.

Returns. any — The field value, or nil.

EXAMPLE · LUA
local hp = ui.hud.get("health")
METHOD

ui.hud.set(key, value)

Write a play HUD field.

Unknown fields warn once. Some fields are read-only.

Parameters

keystringHUD field name or shortcut.
valueanyValue to write.
EXAMPLE · LUA
ui.hud.set("health", self.health)
ui.hud.set("message", "Press Interact")
METHOD

ui.panel.show(name)

Show a named overlay panel.

Unknown panels warn once.

Parameters

namestringPanel id. v1: "npc".
EXAMPLE · LUA
ui.panel.show("npc")
METHOD

ui.panel.hide(name)

Hide a named overlay panel.

Unknown panels warn once.

Parameters

namestringPanel id. v1: "npc".
EXAMPLE · LUA
ui.panel.hide("npc")
METHOD

ui.panel.set(name, options)

Set NPC panel text and portrait.

portrait looks up an animation asset by name.

Parameters

namestringPanel id. v1: "npc".
optionstableTable with text and optional portrait animation name.
EXAMPLE · LUA
ui.panel.set("npc", { text = "Need a key?", portrait = "Mayor" })
METHOD

ui.screen.open(name)

Open a UI-editor screen on the play overlay stack.

Does nothing if that screen is already on top.

Parameters

namestringUI screen name or overview slot name.
EXAMPLE · LUA
if input.pressed("Y") then
  ui.screen.open("Pause")
end
METHOD

ui.screen.close()

Close the top overlay screen.

Warns if there is no screen to close (the HUD root stays).

EXAMPLE · LUA
ui.screen.close()
METHOD

ui.screen.ensure(name) → screen

Find a UI screen by name, creating a blank one if needed.

Creates a real UIScreen through the asset cache, same as New Screen in the editor.

Parameters

namestringUI screen name.

Returns. screen — A screen handle. valid is false on failure.

EXAMPLE · LUA
local pause = ui.screen.ensure("Pause")
METHOD

ui.screen.current() → screen

Handle for the live overlay screen.

This is the HUD / overlay the player sees in play mode.

Returns. screen — A screen handle.

EXAMPLE · LUA
local overlay = ui.screen.current()
overlay:add("text", { name = "prompt", text = "Hello", x = 0.3, y = 0.8, width = 0.4, height = 0.08 })
METHOD

ui.screen.find(name) → screen | nil

Find an existing UI screen by name.

Does not create assets.

Parameters

namestringUI screen name.

Returns. screen | nil — A screen handle, or an invalid handle if missing.

EXAMPLE · LUA
local pause = ui.screen.find("Pause")
METHOD

screen:bake(force?) → boolean

Save this screen's widget tree to the asset.

After ensure/add, call bake so the layout persists. Later bake() calls no-op until bake(true).

Parameters

forceoptionalbooleanOptional. true to rewrite even if already baked.

Returns. boolean — true if a bake was stored.

EXAMPLE · LUA
local s = ui.screen.ensure("Shop")
s:add("Buy", { kind = "button", x = 0.5, y = 0.5 })
s:bake()
PROP

screen.baked → boolean

Whether this screen has a stored baked layout.

Read-only on the screen handle.

Returns. boolean — true after a successful bake.

EXAMPLE · LUA
if not screen.baked then screen:bake() end

widgets

Widgets

The same widget kinds as the UI editor, via handles.

METHOD

screen:add(kind, options?) → widget

Create a widget on this screen or parent.

Kinds: button, inventory_slot, text, image, box, input, joystick, list, grid, health_bar. Same options as the UI editor Add menu. Duplicate names get a _2 suffix. Screen budget is 128 managed widgets (inventory_slot counts as 4).

Parameters

kindstringWidget kind.
optionsoptionaltableLayout and kind-specific properties.

Returns. widget — A widget handle. valid is false on failure.

Notes

  • Common keys: name, x, y, width, height, visible, color, style (0–4).
  • Text: text, font, font_scale, align_h, align_v, wrap.
  • Image: animation, fill (absolute, fill_height, fill_width, stretch, keep_ratio).
  • Button: action, target, option_index, click_sound, hook, pressed_shape.
  • Health bar: value, max, fill_style, damage_color, shake_on_damage.
  • Actions: load_level, open_screen, close_screen, restart_level, pause, consume, advance_dialogue, choose_option, lua.
EXAMPLE · LUA
local title = screen:add("text", {
  name = "title",
  x = 0.25, y = 0.15, width = 0.5, height = 0.12,
  text = "Paused",
  font_scale = 2,
  align_h = "center",
})
METHOD

screen:find(name) → widget

Find a widget by name.

Lua finds widgets by their saved name, which must be unique on the screen.

Parameters

namestringWidget name. Case-insensitive.

Returns. widget — A widget handle. valid is false if missing.

EXAMPLE · LUA
local hp = screen:find("hp")
METHOD

screen:clear()

Remove catalog widgets from the screen.

Never runs on its own. Call this at the top of on_ui_build only if this script owns the whole tree.

EXAMPLE · LUA
function on_ui_build(screen)
  screen:clear()
  screen:add("text", { name = "title", text = "Hi" })
end
METHOD

screen:count() → number

Number of catalog widgets on the screen.

inventory_slot children count toward the screen budget.

Returns. number — Managed widget count.

EXAMPLE · LUA
local n = screen:count()
METHOD

screen:hit(x, y) → widget

Find the catalog widget under overlay UI coordinates.

Pass coordinates from input.ui(), not input.screen(). Returns an invalid handle on miss — check widget.valid.

Parameters

xnumberNormalized UI X (0–1).
ynumberNormalized UI Y (0–1).

Returns. widget — A widget handle. valid is false on miss.

EXAMPLE · LUA
local ux, uy = input.ui()
local w = ui.screen.current():hit(ux, uy)
if w.valid then
  -- inspect w.name / w.kind / w.slot
end
PROP

widget.valid → boolean

true while this widget handle still points at a live widget.

Becomes false after destroy or if hit-testing missed.

Returns. boolean — Whether the handle is valid.

EXAMPLE · LUA
if not widget.valid then return end
PROP

widget.kind → string

Widget kind string for this widget.

Read-only.

Returns. string — Kind such as button or text.

EXAMPLE · LUA
if widget.kind == "button" then ... end
PROP

widget.name → string

Saved name for this widget.

Read/write. This is what screen:find looks up.

Returns. string — Widget name.

EXAMPLE · LUA
local id = widget.name
PROP

widget.slot → string

Inventory slot name when this widget is a slot.

Useful after screen:hit on inventory UIs.

Returns. string — Slot name, or empty.

EXAMPLE · LUA
local slot = widget.slot
METHOD

widget:contains(x, y) → boolean

true if a UI point lies inside this widget's bounds.

Axis-aligned test in overlay space.

Parameters

xnumberNormalized UI X.
ynumberNormalized UI Y.

Returns. boolean — Whether the point is inside.

EXAMPLE · LUA
local ux, uy = input.ui()
if tray:contains(ux, uy) then ... end
METHOD

widget:set(options)

Write several properties at once.

Unknown or invalid keys for this kind warn once and are skipped.

Parameters

optionstableTable of property keys.
EXAMPLE · LUA
prompt:set({ visible = true, text = "Press Interact", color = { 20, 20, 20 } })
METHOD

widget:get(key) → any

Read one property.

Also supports name and kind.

Parameters

keystringProperty key, such as x or text.

Returns. any — The value, or nil.

EXAMPLE · LUA
local x = widget:get("x")
METHOD

widget:bind(channel, source)

Bind a widget channel to a HUD field or Design variable.

Same binding the UI editor connect picker creates. Lookup is case-insensitive. Does not create variables.

Parameters

channelstringtext, visible, or image.
sourcestringHUD display name or variable name.
EXAMPLE · LUA
hp:bind("text", "Player Health")
flag:bind("visible", "HasRedKey")
portrait:bind("image", "NPC Image")
METHOD

widget:unbind(channel)

Remove a bind from a channel.

Leaves the last displayed value in place.

Parameters

channelstringtext, visible, or image.
EXAMPLE · LUA
hp:unbind("text")
METHOD

widget:add(kind, options?) → widget

Create a child widget under this widget.

Same kinds and options as screen:add. Counts against the per-frame add budget outside on_ui_build.

Parameters

kindstringWidget kind.
optionsoptionaltableLayout and kind-specific properties.

Returns. widget — A widget handle. valid is false on failure.

EXAMPLE · LUA
local label = panel:add("text", { name = "label", text = "Hi" })
METHOD

widget:parent(other)

Reparent this widget under another.

Parent cycles warn once and do nothing.

Parameters

otherwidgetParent widget handle.
EXAMPLE · LUA
label:parent(panel)
METHOD

widget:unparent()

Move this widget to the screen root.

Same as Unparent in the editor.

EXAMPLE · LUA
label:unparent()
METHOD

widget:front()

Draw this widget on top of its siblings.

Same as Bring to Front in the editor.

EXAMPLE · LUA
modal:front()
METHOD

widget:back()

Draw this widget behind its siblings.

Same as Send to Back in the editor.

EXAMPLE · LUA
bg:back()
METHOD

widget:duplicate() → widget

Clone this widget as a sibling.

Gets a unique name. Layout is offset slightly.

Returns. widget — Handle for the copy.

EXAMPLE · LUA
local copy = button:duplicate()
METHOD

widget:destroy()

Destroy this widget and its children.

The handle becomes invalid. Same as Delete in the editor.

EXAMPLE · LUA
prompt:destroy()

conversation

conversation

Start a Conversation Arc and move through its lines and choices.

METHOD

conversation.start(arc, options?)

Start a Conversation Arc by display name.

Only one conversation can play at a time. resume continues from the stored cursor for that arc.

Parameters

arcstringArc display name.
optionsoptionaltableOptional table. speaker: self handle. resume: boolean, default true.
EXAMPLE · LUA
conversation.start("MayorQuest", { speaker = self, resume = true })
METHOD

conversation.stop()

Stop the active conversation and hide its panel.

Keeps stored conversation indexes for the play session.

EXAMPLE · LUA
conversation.stop()
METHOD

conversation.advance()

Advance the current dialogue node.

Same as the overlay Advance Dialogue action.

EXAMPLE · LUA
if input.pressed("A") then
  conversation.advance()
end
METHOD

conversation.choose(option)

Pick a reply option.

UI buttons that use choose_option store a 0-based option_index; this Lua call starts at 1.

Parameters

optionnumberOption index starting at 1.
EXAMPLE · LUA
conversation.choose(1)
METHOD

conversation.playing() → boolean

true while a conversation is active.

Use this to freeze movement during dialogue.

Returns. boolean — Whether a conversation is playing.

EXAMPLE · LUA
if conversation.playing() then return end
METHOD

conversation.get_index(arc) → index, node

Read the play-session cursor for an arc.

Progress is not written into the .PGD file.

Parameters

arcstringArc display name.

Returns. number, number — conversation index, node id.

EXAMPLE · LUA
local conv, node = conversation.get_index("MayorQuest")
METHOD

conversation.set_index(arc, index, node)

Write the play-session cursor for an arc.

Use 0 for the unassigned / root node id.

Parameters

arcstringArc display name.
indexnumberConversation index inside the arc.
nodenumberNode id.
EXAMPLE · LUA
conversation.set_index("MayorQuest", 1, 0)
METHOD

conversation.increment_conversation(arc)

Move to the next conversation in the arc and reset the node to root.

For quests that chain several conversations in one arc.

Parameters

arcstringArc display name.
EXAMPLE · LUA
conversation.increment_conversation("MayorQuest")