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.
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.
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).
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.
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
endWhat your script can do, and what it cannot.
-- available
math string table bit32 coroutine
-- stripped
-- io os package debug
-- require load loadfile dofileOptional functions the host calls. Skip any you do not need.
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.
function on_spawn()
camera.follow()
anim.play("Idle", { loop = true })
endfunction 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.
dt | number | Seconds since the last update. |
function on_update(dt)
local x, y = input.stick()
self.vx = x * props.MoveSpeed
endfunction 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.
hit | hit | Handle for the other collider. |
function on_collision(hit)
if hit:has_tag("Monster") and not self.invulnerable then
self.hurt(1)
sound.play("Hurt")
end
endfunction 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.
who | hit | Hit handle for the interacting entity. |
function on_interact(who)
if who:has_tag("Player") then
conversation.start("MayorQuest", { speaker = self })
end
endfunction 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.
kind | string | Reaction kind, such as anim or sound. |
slot | string | Property slot name that fired. |
function on_reaction(kind, slot)
if kind == "anim" then
-- editor reaction overlays still run in C#
end
endfunction on_conversation_line(arc, index, node)A dialogue line was shown.
Fires when the conversation enters a dialogue node.
arc | string | Display name of the Conversation Arc. |
index | number | Conversation index inside the arc. |
node | number | Dialogue node id. |
function on_conversation_line(arc, index, node)
anim.play("Talk", { loop = true })
endfunction on_conversation_choice(option)A reply option was chosen.
Uses the same numbering as conversation.choose.
option | number | Option index starting at 1. |
function on_conversation_choice(option)
if option == 1 then
vars.set("HelpedMayor", true)
end
endfunction on_conversation_end(arc)The active conversation finished or was stopped.
A good place to restore an idle animation.
arc | string | Display name of the Conversation Arc. |
function on_conversation_end(arc)
anim.play("Idle", { loop = true })
endfunction 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.
id | string | Hook id from the conversation inspector. |
function on_conversation_hook(id)
if id == "give_key" then
vars.set("HasTownKey", true)
end
endfunction 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.
screen | screen | Handle for the current overlay screen. |
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")
endfunction 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.
hook | string | The hook string stored on the button. |
widget | widget | Handle for the clicked widget. |
function on_ui_action(hook, widget)
if hook == "shop.open" then
ui.screen.open("Shop")
end
endfunction 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.
x | number | World X. |
y | number | World Y. |
function on_tap(x, y)
spawn.at(props.Bullet, x, y)
endfunction 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.
function on_inventory_changed()
vars.set("HasKey", inventory.has("Red Key"))
endPico-8 style helpers plus math.mid. No cart memory peek/poke.
rnd(range?) → numberRandom 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.
rangeoptional | number | Optional upper bound. Defaults to 1. |
Returns. number — Random number.
local roll = rnd(10)
local unit = rnd()srand(seed)Reseed the host random number generator.
Affects later rnd and math.random calls in this script.
seed | number | Seed value (floored). |
srand(42)flr(n) → numberFloor a number (Pico-8 style).
Same as math.floor.
n | number | Number to floor. |
Returns. number — math.floor(n).
local tile = flr(self.x)abs(n) → numberAbsolute value (Pico-8 style global).
Same as math.abs.
n | number | Input number. |
Returns. number — Absolute value.
local dist = abs(hit.x - self.x)mid(a, b, c) → numberMedian of three numbers.
Handy for clamping: mid(lo, value, hi).
a | number | First value. |
b | number | Second value. |
c | number | Third value. |
Returns. number — The middle value.
local hp = mid(0, self.health, self.max_health)t() → numberSeconds since this script started.
Advances each script update. Alias of time().
Returns. number — Elapsed seconds.
if t() > 3 then
anim.play("Idle")
endtime() → numberAlias for t().
Same clock as t().
Returns. number — Elapsed seconds.
local elapsed = time()math.mid(a, b, c) → numberMedian 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.
a | number | First value. |
b | number | Second value. |
c | number | Third value. |
Returns. number — The middle value.
local v = math.mid(0, value, 1)math.randomseed(seed)Reseed math.random (same generator as srand).
Alias path for scripts that prefer math.randomseed.
seed | number | Seed value. |
math.randomseed(42)This object's position, velocity, health, lights, and destroy.
self.x → numberWorld 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.
self.x = self.x + 1
local here = self.xself.y → numberWorld 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.
self.y = self.y + 0.5self.vx → numberRigidbody 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.
local x = input.stick()
self.vx = x * props.MoveSpeedself.vy → numberRigidbody velocity Y.
Read/write. Jump by assigning a positive or negative value depending on your gravity direction.
Returns. number — Velocity Y.
if self.grounded and input.pressed("A") then
self.vy = props.JumpPower
endself.gravity → numberHow 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.
self.gravity = 0
-- ignore scene gravity (astronaut)
self.gravity = 1
-- normal weightself.angle → numberZ 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.
local dx, dy = input.stick2()
self.angle = math.atan2(dx, dy)self.grounded → booleanWhether 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).
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
endself.health → numberCurrent hit points.
Read/write. Writing also updates the play HUD health field when one exists.
Returns. number — Current health.
if self.health <= 0 then
anim.play("Die", { loop = false, hold = true })
endself.max_health → numberMaximum hit points.
Read/write. Used by hurt() when clamping health.
Returns. number — Maximum health.
self.health = self.max_healthself.invulnerable → booleantrue while the object cannot take damage (i-frames).
Read-only. Check this before applying contact damage.
Returns. boolean — Whether damage should be ignored.
if hit:has_tag("Monster") and not self.invulnerable then
self.hurt(1)
endself.visible → booleanWhether 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.
self.visible = false
self.show()
self.hide()self.alpha → numberSprite opacity from 0 to 1.
Read/write. Values outside 0–1 clamp and warn once. Does not change visible or collision.
Returns. number — Opacity.
self.alpha = 0.5self.tint → stringSprite RGB tint as #rrggbb.
Read/write. Accepts #rrggbb or #rgb. Does not change alpha.
Returns. string — Tint hex string.
self.tint = "#ff8844"self.show()Show this object's sprite.
Same as self.visible = true.
self.show()self.hide()Hide this object's sprite.
Same as self.visible = false. Collision still works.
self.hide()self.name → stringThis object's display name.
Read-only.
Returns. string — Display name.
local n = self.nameself.tag → stringOne 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.
local t = self.tagself.inventory → inventoryThis 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.
self.inventory.add("Red Key")self.always_update → booleanKeep 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.
function on_spawn()
self.always_update = true
endself.has_light(light) → booleantrue 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.
light | number | Light index from 1 to 5. |
Returns. boolean — Whether this object has that light enabled.
if self.has_light(1) then
-- this object's light 1 is on in the overview
endself.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.
amount | number | Damage to apply. |
self.hurt(1)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.
if self.health <= 0 then
self.destroy()
endObject-overview properties by name. Lua cannot add new ones.
props.Name → number | boolean | string | prefab | anim | sound | nilRead 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.
local speed = props.MoveSpeed
if speed == nil then speed = 8 end
self.vx = speed
spawn.at(props.Bullet, self.x, self.y)props.Name = valueWrite a numeric, bool, or string property.
Cannot create new overview rows. Cannot write scene or UI screen slots. Unknown names warn once.
value | number | boolean | string | Value matching the property type. |
props.MoveSpeed = 12Project prefabs by display name, including reading their properties.
objects.Name → prefab | nilLook 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.
spawn.at(objects.Slime, self.x, self.y)
local cost = objects.Cannon:prop("Cost")prefab.name → stringDisplay name of a prefab handle.
Handles come from objects.Name or props prefab slots.
Returns. string — Prefab display name.
local n = objects.Bullet.nameprefab:prop(name) → anyRead a property from the prefab without spawning it.
Useful for tower costs, ranges, and other authored numbers.
name | string | Property name (display or internal). |
Returns. any — The value, or nil.
local range = objects.Cannon:prop("Range")Play clips from this object's animation slots.
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).
slot | string | anim | Animation slot name or anim handle. |
optionsoptional | table | Optional table of loop, hold, restart, flip_x, flip_y, on_end, set, done. |
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 })anim.stop()Stop the sprite animator on this object.
Does nothing (with a warning) if the object has no animator.
anim.stop()Play clips from this object's sound slots.
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.
slot | string | sound | Sound slot name or sound handle. |
optionsoptional | table | Optional table. loop: boolean. |
sound.play("Jump")
sound.play(props.Music, { loop = true })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.
slot | string | sound | Sound slot name or sound handle. |
sound.stop("Music")sound.stop_all()Stop every sound started by this script host.
Useful when leaving a level or opening a pause screen.
sound.stop_all()sound.set_volume(slot | clip, volume)Set volume for one playing sound.
Volume is typically 0–1.
slot | string | sound | Sound slot name or sound handle. |
volume | number | Volume 0–1. |
sound.set_volume("Music", 0.4)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.
volume | number | Volume 0–1. |
sound.set_volume_all(0.5)Stick, buttons, touch, pinch, and which object is controlled.
input.stick() → x, yLeft 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.
local x, y = input.stick()
self.vx = x * 8
self.vy = y * 8input.stick2() → x, yJoystick 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.
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
endinput.pressed(name) → booleantrue 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.
name | string | Control name. |
Returns. boolean — Whether the control was pressed this frame.
if input.pressed("A") then
self.vy = 10
endinput.held(name) → booleantrue while a control is held down.
Same names as input.pressed.
name | string | Control name. |
Returns. boolean — Whether the control is currently held.
if input.held("B") then
spawn.at(props.Bullet, self.x, self.y)
endinput.released(name) → booleantrue on the frame a control was released.
Same names as input.pressed.
name | string | Control name. |
Returns. boolean — Whether the control was released this frame.
if input.released("Interact") then
vars.set("ShowPrompt", false)
endinput.touch() → held, x, yPrimary 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.
local held, x, y = input.touch()
if held then
self.x = x
self.y = y
endinput.touch_claimed() → booleantrue 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.
if input.touch_claimed() then return endinput.ui_blocking() → booleanAlias for input.touch_claimed.
Same check as input.touch_claimed.
Returns. boolean — Whether UI claimed the pointer.
if input.ui_blocking() then return endinput.screen() → x, yPrimary pointer position in world space.
Same coordinates as input.touch, without the held flag.
Returns. number, number — world X, world Y.
local x, y = input.screen()input.ui() → x, yPrimary 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.
local ux, uy = input.ui()
local w = ui.screen.current():hit(ux, uy)input.pinch() → active, scaleTwo-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.
local active, scale = input.pinch()
if active then
camera.zoom(camera.level() * scale, 0)
endinput.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.
playeroptional | string | table | Optional player name string or options table. |
function on_spawn()
input.possess()
end
input.possess("Hero")
input.possess({ player = "Hero" })input.enabled() → booleanWhether this object currently receives player input.
Possession and set_enabled both affect this.
Returns. boolean — true when stick, buttons, and touch queries can succeed.
if not input.enabled() then return endinput.set_enabled(value)Enable or disable player input for this object.
Disabled objects still exist; stick and button queries return idle values.
value | boolean | true to accept input, false to ignore it. |
input.set_enabled(false)Overlap checks, tags, paths, and the hit handle from on_collision.
collision.overlaps_light(light) → booleantrue 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.
light | number | Light index from 1 to 5. |
Returns. boolean — Whether any overlapping volume has that light.
if collision.overlaps_light(1) then
facing = -facing
endcollision.has_light_at(x, y, light) → booleantrue 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.
x | number | World X. |
y | number | World Y. |
light | number | Light index from 1 to 5. |
Returns. boolean — Whether that painted light is present at the point.
if collision.has_light_at(self.x, self.y - 0.1, 2) then
-- standing on a hazard tile
endcollision.overlaps_tag(tag) → booleantrue 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.
tag | string | Tag display name. |
Returns. boolean — Whether an overlapping entity has the tag.
if collision.overlaps_tag("NPC") then
vars.set("Touching NPC", true)
endhit.is_tile → booleantrue 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.
function on_collision(hit)
if hit.is_tile then return end
endhit.is_trigger → booleantrue if the contact involves a trigger collider.
Trigger volumes still call on_collision.
Returns. boolean — Whether the contact is a trigger.
if hit.is_trigger then
scene.load("Secret Room")
endhit:exists() → booleantrue 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.
if not hit:exists() then return endhit.x → numberWorld X of the other entity.
Also available on hit handles from scene.tagged.
Returns. number — World position X.
local dx = hit.x - self.xhit.y → numberWorld Y of the other entity.
Also available on hit handles from scene.tagged.
Returns. number — World position Y.
local dy = hit.y - self.yhit.nx → numberContact normal X.
Useful for turning around when walking into a wall (hit.nx * facing < 0).
Returns. number — Normal X.
if hit.nx * facing < 0 then
facing = -facing
endhit.ny → numberContact normal Y.
The sign depends on which way is up in your world.
Returns. number — Normal Y.
if hit.ny < 0 then
-- landed on something
endhit:has_light(light) → booleantrue if the other object has that collision light.
Same 1–5 numbering as collision.overlaps_light.
light | number | Light index from 1 to 5. |
Returns. boolean — Whether the other object has the light.
if hit:has_light(3) then
self.hurt(1)
endhit:has_tag(tag) → booleantrue if the other object has that tag.
Same tag rules as collision.overlaps_tag, including stock C# monsters.
tag | string | Tag display name. |
Returns. boolean — Whether the other object has the tag.
if hit:has_tag("Projectile") then
sound.play("Hurt")
endhit.name → stringOther object's display name.
Read-only. Empty when the handle is stale.
Returns. string — Display name.
local n = hit.namehit.tag → stringOne primary tag on the other object.
Read-only. Prefer hit:has_tag to test a specific name.
Returns. string — Primary tag, or empty.
local t = hit.taghit: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.
amount | number | Damage to apply. |
if hit:has_tag("Monster") then
hit:hurt(1)
endhit: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).
amountoptional | number | Optional knockback strength. Defaults to 5. |
if hit:has_tag("Spike") and not self.invulnerable then
self.hurt(1)
hit:knockback(5)
endhit: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.
hit:ride()hit:collect() → booleanCollect 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.
if hit:has_tag("Collectable") then
hit:collect()
vars.add("Score", 1)
endhit: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.
if hit:has_tag("Projectile") then
hit:destroy()
endhit.inventory → inventoryThe other object's inventory.
Stale handles still return an object; its calls no-op.
Returns. inventory — Inventory API for the other object.
hit.inventory.add("Coin")hit:erase() → booleanErase 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.
function on_collision(hit)
if hit.is_tile and hit:has_light(1) then
hit:erase()
end
endhit:prop(name) → anyRead a property on the other object.
NPC templates use names like "Text", "Portrait Icon", and "Interactable".
name | string | Property name (display or internal). |
Returns. any — The value, or nil.
local text = hit:prop("Text")
if text ~= nil then
vars.set("NPC Text", text)
endhit:set_prop(name, value) → booleanWrite a property on the other object.
Same rules as props.Name = value. Returns false when stale, unknown, or read-only.
name | string | Property name. |
value | any | Value to write. |
Returns. boolean — true if the write succeeded.
hit:set_prop("Text", "Thanks!")hit:contains(x, y) → booleantrue 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.
x | number | World X. |
y | number | World Y. |
Returns. boolean — Whether the point is inside the hit.
if hit:contains(self.x, self.y) then
-- standing on this zone / path cell
endhit:path_tile_count() → numberNumber 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.
local n = hit:path_tile_count()hit:path_tile(index) → ok, x, yWorld position of a painted path waypoint.
Returns false when the index is out of range or the hit is not a path.
index | number | Waypoint index starting at 1. |
Returns. boolean, number, number — ok flag, world X, world Y.
local ok, x, y = hit:path_tile(1)
if ok then
self.x = x
self.y = y
endAdd, remove, use, and place items for the player or a pinned object.
inventory.add(item, count?) → booleanAdd 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.
item | string | prefab | Prefab name, objects ref, or stack name. |
countoptional | number | Optional count ≥ 1. |
Returns. boolean — true if anything was added.
inventory.add("Red Key")
inventory.add(objects.Potion, 3)inventory.remove(item, count?) → numberRemove up to count of an item.
Removes as many as possible up to count. Returns the number actually removed.
item | string | prefab | Prefab name, objects ref, or stack name. |
countoptional | number | Optional count. Default 1. |
Returns. number — How many were removed.
local n = inventory.remove("Coin", 2)inventory.has(item) → booleantrue if at least one of that item is held.
True when count for that item is at least 1.
item | string | prefab | Prefab name, objects ref, or stack name. |
Returns. boolean — Whether the item is present.
if inventory.has("Red Key") then scene.load("Treasure") endinventory.count(item) → numberHow many of that item are held.
Returns 0 when the item is not held.
item | string | prefab | Prefab name, objects ref, or stack name. |
Returns. number — Stack count.
local n = inventory.count("Coin")inventory.list() → tableAll stacks as a table of { name, count } entries.
Order matches the inventory UI.
Returns. table — Array-style table.
for _, e in ipairs(inventory.list()) do
-- e.name, e.count
endinventory.clear()Remove every stack.
Refreshes inventory UI when present.
inventory.clear()inventory.use(item) → booleanConsume 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.
item | string | prefab | Prefab name, objects ref, or stack name. |
Returns. boolean — true if one was consumed/removed.
inventory.use("Potion")inventory.place(item, x, y) → hit | nilSpawn one held item into the world and remove it from inventory.
Uses the same spawn budget as spawn.at.
item | string | prefab | Prefab name, objects ref, or stack name. |
x | number | World X. |
y | number | World Y. |
Returns. hit | nil — Hit handle for the spawned object, or nil.
local h = inventory.place("Crate", self.x + 1, self.y)Create a prefab or overview object slot in the scene.
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.
name | string | prefab | Prefab handle, overview slot, or project object name. |
x | number | World X. |
y | number | World Y. |
optionsoptional | table | Optional table. dir_x, dir_y aim projectiles. |
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)One-frame world sprites you redraw each update while they should show.
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.
clip | anim | Anim handle, usually props.SomeSlot. |
x | number | World X. |
y | number | World Y. |
widthoptional | number | Optional world width. Defaults to native size. |
function on_update(dt)
local gx, gy = scene.grid(input.screen())
fx.draw(props.RangeIndicator, gx, gy, props.Range * 2)
endFollow, shake, pan, zoom, fade, and solid background color.
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.
optionsoptional | table | Optional table. side: boolean. player or name: string. |
function on_spawn()
camera.follow()
-- camera.follow({ side = false }) -- top-down
-- camera.follow({ player = "Hero" })
endcamera.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.
camera.stop()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.
playeroptional | string | table | Optional player name string or options table. |
camera.change_player("Hero")
camera.change_player({ player = "Hero", side = false })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 }.
intensityoptional | number | Shake strength. |
durationoptional | number | table | Seconds, or an options table when used alone. |
camera.shake(0.5, 0.4)
camera.shake({ intensity = 0.6, duration = 0.5 })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.
x | number | World X, or ignored when using an options table as the first arg. |
y | number | World Y. |
durationoptional | number | table | Seconds, or an options table. |
camera.pan(10, 0, 1)
camera.pan({ x = 2, y = 0, relative = true })camera.zoom(level, duration? | options?)Animate the camera zoom level.
Accepts level + optional duration, or { level / zoom, duration / time }.
level | number | Target zoom level. |
durationoptional | number | table | Seconds, or an options table. |
camera.zoom(1.5, 0.3)
camera.zoom({ level = 2, duration = 0.5 })camera.level() → numberCurrent camera zoom level.
Useful with input.pinch for multiplicative zoom.
Returns. number — Zoom level, defaulting to 1 when no camera exists.
local z = camera.level()camera.x → numberCamera world X.
Read-only shortcut for the active follow camera position.
Returns. number — World X.
local cx = camera.xcamera.y → numberCamera world Y.
Read-only shortcut for the active follow camera position.
Returns. number — World Y.
local cy = camera.ycamera.pos() → x, yCamera world position as x, y.
Same values as camera.x and camera.y.
Returns. number, number — World X, world Y.
local x, y = camera.pos()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.
x | number | table | World X, or options table. |
yoptional | number | World Y. |
camera.set(10, 0)
camera.set({ x = 10, y = 0 })camera.move(dx, dy | options)Nudge the camera by a world delta.
Accepts dx, dy or { x/dx, y/dy }.
dx | number | table | Delta X, or options table. |
dyoptional | number | Delta Y. |
camera.move(1, 0)camera.following() → booleantrue 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.
if camera.following() then camera.stop() endcamera.bounds() → left, bottom, right, top | nilVisible 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.
local l, b, r, t = camera.bounds()camera.screen_to_world(sx, sy) → x, y | nilConvert overlay / screen coords to world.
Useful with input.ui coordinates.
sx | number | Screen X. |
sy | number | Screen Y. |
Returns. number, number | nil — World X, world Y.
local x, y = camera.screen_to_world(ux, uy)camera.world_to_screen(wx, wy) → x, y | nilConvert world coords to screen / overlay space.
Useful for overlay widgets that track a world object.
wx | number | World X. |
wy | number | World Y. |
Returns. number, number | nil — Screen X, screen Y.
local sx, sy = camera.world_to_screen(self.x, self.y)camera.fade_out(duration? | options?)Fade the screen out.
Default duration is about 0.4s. Accepts a number or { duration / time }.
durationoptional | number | table | Seconds, or an options table. |
camera.fade_out(0.5)camera.fade_in(duration? | options?)Fade the screen back in.
Default duration is about 0.4s. Accepts a number or { duration / time }.
durationoptional | number | table | Seconds, or an options table. |
camera.fade_in()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.
r | number | table | Red, or an options table. |
goptional | number | Green. |
boptional | number | Blue. |
aoptional | number | Optional alpha. |
camera.background(20, 24, 40)
camera.background({ r = 0.1, g = 0.1, b = 0.15 })camera.background_color(r, g, b, a? | options?)Alias for camera.background.
Same arguments and color rules as camera.background.
r | number | table | Red, or an options table. |
goptional | number | Green. |
boptional | number | Blue. |
aoptional | number | Optional alpha. |
camera.background_color(0, 0, 0)Edit scene parallax layers: image, tiling, scroll, tint, and visibility.
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.
layer | string | number | table | Layer name, 1-based index, or options table. |
optionsoptional | table | Optional property table when layer is passed first. |
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 },
})background.get(layer) → table | nilRead 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.
layer | string | number | Layer name or 1-based index. |
Returns. table | nil — Layer table, or nil.
local mid = background.get("mid")
if mid and mid.visible then
background.scroll("mid", mid.scroll_x + 0.01, mid.scroll_y)
endbackground.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.
layer | string | number | Layer name or 1-based index. |
clip | string | anim | boolean | Image name, animation handle, or false. |
background.image("mid", "Mountains")
background.image("front", props.ParallaxArt)
background.image("mid", false) -- clearbackground.texture(layer, clip | false)Alias for background.image.
Same arguments as background.image.
layer | string | number | Layer name or 1-based index. |
clip | string | anim | boolean | Image name, animation handle, or false. |
background.texture("back", "Sky")background.clear_image(layer)Remove the image from a layer.
Same as background.image(layer, false).
layer | string | number | Layer name or 1-based index. |
background.clear_image("mid")background.scale(layer, scale)Set a layer's image scale.
Values below 1 are treated as 1.
layer | string | number | Layer name or 1-based index. |
scale | number | Scale multiplier. |
background.scale("mid", 1.5)background.tile(layer, "none" | "x" | "y" | "xy")Set how a layer's image repeats.
Use "none", "x", "y", or "xy". Unknown modes warn once.
layer | string | number | Layer name or 1-based index. |
mode | string | none, x, y, or xy. |
background.tile("mid", "x")
background.tile("front", "xy")background.tiling(layer, "none" | "x" | "y" | "xy")Alias for background.tile.
Same arguments as background.tile.
layer | string | number | Layer name or 1-based index. |
mode | string | none, x, y, or xy. |
background.tiling("mid", "y")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.
layer | string | number | Layer name or 1-based index. |
r | number | table | Red, or a color table. |
goptional | number | Green. |
boptional | number | Blue. |
aoptional | number | Optional alpha. |
background.color("back", 12, 18, 32)
background.color("back", { r = 0.05, g = 0.07, b = 0.12 })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.
layer | string | number | Layer name or 1-based index. |
r | number | table | Red, or a color table. |
goptional | number | Green. |
boptional | number | Blue. |
aoptional | number | Optional alpha. |
background.tint("mid", 255, 220, 200)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.
layer | string | number | Layer name or 1-based index. |
mode | string | parallax or auto. |
background.move("mid", "parallax")
background.move("clouds", "auto")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.
layer | string | number | Layer name or 1-based index. |
x | number | X factor or speed. |
y | number | Y factor or speed. |
background.scroll("mid", 0.4, 0.1)background.offset(layer, x, y)Nudge a layer's draw position.
World-space offset applied after scroll / parallax.
layer | string | number | Layer name or 1-based index. |
x | number | Offset X. |
y | number | Offset Y. |
background.offset("front", 0, -2)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.
layer | string | number | Layer name or 1-based index. |
on | boolean | true to draw in front of gameplay. |
background.in_front("front", true)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.
layer | string | number | Layer name or 1-based index. |
shownoptional | boolean | Optional boolean when setting. |
Returns. boolean — Whether the layer is visible (when reading).
if background.visible("mid") then
background.visible("mid", false)
endbackground.show(layer)Show a layer.
Same as background.visible(layer, true).
layer | string | number | Layer name or 1-based index. |
background.show("mid")background.hide(layer)Hide a layer.
Same as background.visible(layer, false).
layer | string | number | Layer name or 1-based index. |
background.hide("front")background.rename(layer, name)Rename a mid/front layer.
The back layer is always named "back" and cannot be renamed.
layer | string | number | Layer name or 1-based index. |
name | string | New layer name. |
background.rename(2, "clouds")background.add(name? | options?) → stringAdd 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.
nameoptional | string | table | Optional name string or options table. |
Returns. string — Created layer name, or empty on failure.
local name = background.add("clouds")
background.add({
name = "fog",
image = "Fog",
tile = "x",
move = "auto",
scroll_x = 0.15,
})background.remove(layer) → booleanDelete a mid/front layer.
The back layer cannot be removed. Returns false if the layer is missing or protected.
layer | string | number | Layer name or 1-based index. |
Returns. boolean — true if the layer was removed.
background.remove("fog")background.count() → numberHow many parallax layers the scene has.
Includes the back layer.
Returns. number — Layer count, or 0 if there is no scene yet.
local n = background.count()background.layers() → tableLayer 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.
for i, name in ipairs(background.layers()) do
print(i, name)
endDesign variables and built-in HUD fields.
vars.get(name) → anyRead 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.
name | string | Variable or HUD field name. |
Returns. any — The value, or nil.
if vars.get("HasRedKey") then
scene.load("Treasure Room")
end
local hp = vars.get("health") -- Player Healthvars.has(name) → booleantrue if the name is a built-in HUD field or an existing variable.
Does not create anything.
name | string | Variable or HUD field name. |
Returns. boolean — Whether the name is defined.
if not vars.has("Score") then
vars.set("Score", 0)
endvars.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.
name | string | Variable or HUD field name. |
value | any | Value to store. |
vars.set("HasRedKey", true)
vars.set("NPC Text", "Hello!")
vars.set("health", 3)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.
name | string | Variable or HUD field name. |
amount | number | Amount to add (can be negative). |
vars.add("Score", 10)
vars.add("money", 5)Send short messages between scripts after on_update.
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.
name | string | Channel name. |
handler | function | function(value). |
ping.on("door_open", function(msg)
anim.play("Open")
end)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.
name | string | Channel name. |
valueoptional | any | Optional payload. |
ping.send("door_open")
ping.send("score", { points = 10 })Load levels, find tagged objects, snap to the grid, and paint or erase tiles.
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.
name | string | Scene name or overview slot name. |
optionsoptional | table | Optional table. keep_state: boolean. |
scene.load("Forest 2")
scene.load("Hub", { keep_state = true })scene.restart()Restart the current level.
Uses the play overlay's restart path. Warns if no overlay exists.
if self.health <= 0 then
scene.restart()
endscene.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.
messageoptional | string | Optional text shown on supported game-over screens. |
if self.health <= 0 then
scene.game_over("Try again!")
endscene.fallen_off() → booleantrue 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.
if scene.fallen_off() then
scene.game_over()
endscene.td_spawning() → booleantrue 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.
if not scene.td_spawning() and monster_count == 0 then
-- wave cleared
endscene.tower_dragging() → booleantrue 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.
if scene.tower_dragging() then
-- show build zones while a tower is dragged from the tray
endscene.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.
on | boolean | true while dragging, false when idle. |
scene.set_tower_dragging(true)
-- ... place or cancel ...
scene.set_tower_dragging(false)scene.gravity → numberScene 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.
scene.gravity = -30
-- pull down
scene.gravity = 0
-- zero-g for objects that still have self.gravityscene.current_name() → stringDisplay name of the active scene.
Empty when the object is not in a scene.
Returns. string — Scene name, or empty string.
local here = scene.current_name()scene.closest_tag(tag, max_range?) → ok, x, yFind the nearest other entity with a tag.
Returns ok, x, y. max_range 0 or omitted means unlimited. Excludes self.
tag | string | Tag display name. |
max_rangeoptional | number | Optional max distance. 0 = unlimited. |
Returns. boolean, number, number — ok flag, world X, world Y.
local ok, x, y = scene.closest_tag("Monster", 8)
if ok then
facing = x < self.x and -1 or 1
endscene.tagged(tag) → tableAll 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.
tag | string | Tag display name. |
Returns. table — Array-style table of hit handles.
for _, h in ipairs(scene.tagged("Tower")) do
-- h.x, h:has_tag(...), h:prop(...)
endscene.tagged_count(tag) → numberHow many entities have that tag.
Cheaper than building the full scene.tagged table when you only need a count.
tag | string | Tag display name. |
Returns. number — Count.
local n = scene.tagged_count("Monster")scene.tagged_at(tag, index) → hit | nilOne tagged entity by 1-based index.
Pair with scene.tagged_count to iterate without allocating the full list every frame.
tag | string | Tag display name. |
index | number | Index starting at 1. |
Returns. hit | nil — Hit handle, or nil.
local h = scene.tagged_at("Tower", 1)scene.grid(x, y) → gx, gySnap a world point to the scene placement grid.
Same grid math the editor and tower placement use.
x | number | World X. |
y | number | World Y. |
Returns. number, number — Grid-snapped X, grid-snapped Y.
local gx, gy = scene.grid(input.screen())scene.occupied(tag, x, y) → booleantrue if another tagged entity shares that grid cell.
Excludes self. Pass world or already-snapped coordinates; occupancy compares grid cells.
tag | string | Tag display name. |
x | number | World X. |
y | number | World Y. |
Returns. boolean — Whether the cell is occupied.
local gx, gy = scene.grid(input.screen())
if not scene.occupied("Tower", gx, gy) then
spawn.at(props.Tower, gx, gy)
endscene.erase_tile_at(x, y) → booleanErase 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.
x | number | World X. |
y | number | World Y. |
Returns. boolean — true if a painted cell was erased.
if scene.erase_tile_at(self.x, self.y) then
sound.play("Dig")
endscene.paint_tile_at(x, y, light?) → booleanPaint 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.
x | number | World X. |
y | number | World Y. |
lightoptional | number | Optional collision light 1–5. Omit or 0 uses the last tileset. |
Returns. boolean — true if a cell was painted.
scene.paint_tile_at(self.x, self.y)
scene.paint_tile_at(self.x + 1, self.y, 1)Query and edit painted tileset cells by world point or grid index.
tiles.walkable(x, y) → booleantrue if ground/walk surface is painted and no obstacle.
World-point sample. Same grid as scene.paint_tile_at.
x | number | |
y | number |
Returns. boolean
if tiles.walkable(self.x, self.y) then endtiles.blocking(x, y) → booleantrue if an obstacle tileset is painted here.
A wall on a floor wins.
x | number | |
y | number |
Returns. boolean
if tiles.blocking(self.x + 1, self.y) then endtiles.occupied(x, y) → booleantrue if any tileset is painted here.
Includes triggers. Not the same as scene.occupied.
x | number | |
y | number |
Returns. boolean
if tiles.occupied(self.x, self.y) then endtiles.walkable_cell(col, row) → booleanwalkable for a grid cell.
Same as tiles.walkable, but takes column/row.
col | number | |
row | number |
Returns. boolean
if tiles.walkable_cell(3, 5) then endtiles.blocking_cell(col, row) → booleanblocking for a grid cell.
Same as tiles.blocking for column/row.
col | number | |
row | number |
Returns. boolean
if tiles.blocking_cell(3, 5) then endtiles.occupied_cell(col, row) → booleanoccupied for a grid cell.
Same as tiles.occupied for column/row.
col | number | |
row | number |
Returns. boolean
if tiles.occupied_cell(3, 5) then endtiles.type(x, y) → string | nilWinning tileset object name, or nil.
Empty cells return nil.
x | number | |
y | number |
Returns. string | nil
local name = tiles.type(self.x, self.y)tiles.type_cell(col, row) → string | nilWinning tileset name for a grid cell.
Empty cells return nil.
col | number | |
row | number |
Returns. string | nil
local name = tiles.type_cell(3, 5)tiles.role(x, y) → string | nilCollision role for the winning paint.
Ground, WalkSurface, Obstacle, Trigger, or a custom role. Nil when empty.
x | number | |
y | number |
Returns. string | nil
local r = tiles.role(self.x, self.y)tiles.role_cell(col, row) → string | nilCollision role for a grid cell.
Same roles as tiles.role.
col | number | |
row | number |
Returns. string | nil
local r = tiles.role_cell(3, 5)tiles.slice(x, y) → string | nilAutotile slice name being drawn.
Example: Tileset_Cap_Left. Nil when empty.
x | number | |
y | number |
Returns. string | nil
local s = tiles.slice(self.x, self.y)tiles.slice_cell(col, row) → string | nilAutotile slice for a grid cell.
Nil when empty.
col | number | |
row | number |
Returns. string | nil
local s = tiles.slice_cell(3, 5)tiles.prop(x, y, name, tileset?) → anyRead a tileset bag property at a world point.
Optional tileset name disambiguates overlapping paints.
x | number | |
y | number | |
name | string | |
tilesetoptional | string |
Returns. any
local v = tiles.prop(self.x, self.y, "Damage")tiles.prop_cell(col, row, name, tileset?) → anyRead a tileset bag property at a grid cell.
Optional tileset name disambiguates overlapping paints.
col | number | |
row | number | |
name | string | |
tilesetoptional | string |
Returns. any
local v = tiles.prop_cell(3, 5, "Damage")tiles.cell(x, y) → col, row | nilGrid column/row under a world point.
Nil when the scene has no tile grid.
x | number | |
y | number |
Returns. number, number | nil
local c, r = tiles.cell(self.x, self.y)tiles.world(col, row) → x, y | nilWorld center of a grid cell.
Nil when out of range.
col | number | |
row | number |
Returns. number, number | nil
local x, y = tiles.world(3, 5)tiles.extent() → min_col, min_row, max_col, max_row | nilInclusive painted bounds.
min col, min row, max col, max row. Nil when nothing is painted.
Returns. number, number, number, number | nil
local x0, y0, x1, y1 = tiles.extent()tiles.count() → numberHow many painted cells exist.
Across the active tile grid.
Returns. number
local n = tiles.count()tiles.cells(col0, row0, col1, row1) → tablePainted cells in a rectangle as a table.
Useful for band scans.
col0 | number | |
row0 | number | |
col1 | number | |
row1 | number |
Returns. table
local band = tiles.cells(0, 0, 10, 10)tiles.cell_count(col0, row0, col1, row1) → numberPainted cell count in a rectangle.
Does not allocate the full cell list.
col0 | number | |
row0 | number | |
col1 | number | |
row1 | number |
Returns. number
local n = tiles.cell_count(0, 0, 10, 10)tiles.cell_at(col0, row0, col1, row1, index) → col, row, walkable, blocking | nilOne painted cell in a rectangle by 1-based index.
Returns col, row, walkable, blocking.
col0 | number | |
row0 | number | |
col1 | number | |
row1 | number | |
index | number |
Returns. number, number, boolean, boolean | nil
local c, r, w, b = tiles.cell_at(0, 0, 10, 10, 1)tiles.tally(col0, row0, col1, row1) → walkable, blocking | nilWalkable and blocking counts in a rectangle.
Returns walkable_count, blocking_count.
col0 | number | |
row0 | number | |
col1 | number | |
row1 | number |
Returns. number, number | nil
local walk, block = tiles.tally(0, 0, 10, 10)tiles.set(x, y, which?) → booleanPaint a cell at a world point.
which is a tileset name or index. Same grid as scene.paint_tile_at.
x | number | |
y | number | |
whichoptional | string | number |
Returns. boolean
tiles.set(self.x, self.y, "Grass")tiles.set_cell(col, row, which?) → booleanPaint a grid cell.
which is a tileset name or index.
col | number | |
row | number | |
whichoptional | string | number |
Returns. boolean
tiles.set_cell(3, 5, 1)tiles.clear(x, y, tileset?) → booleanErase paint at a world point.
Optional tileset name limits which layer is cleared.
x | number | |
y | number | |
tilesetoptional | string |
Returns. boolean
tiles.clear(self.x, self.y)tiles.clear_cell(col, row, tileset?) → booleanErase paint at a grid cell.
Optional tileset name limits which layer is cleared.
col | number | |
row | number | |
tilesetoptional | string |
Returns. boolean
tiles.clear_cell(3, 5)tiles.on_change(handler)Register a callback when painted cells change.
handler(col, row). Register at script top when possible.
handler | function |
tiles.on_change(function(col, row)
-- painted cell changed
end)HUD fields, the NPC panel, and screens from the UI editor.
ui.hud.get(key) → anyRead a play HUD field.
Same name map as vars.get for built-ins.
key | string | HUD field name or shortcut. |
Returns. any — The field value, or nil.
local hp = ui.hud.get("health")ui.hud.set(key, value)Write a play HUD field.
Unknown fields warn once. Some fields are read-only.
key | string | HUD field name or shortcut. |
value | any | Value to write. |
ui.hud.set("health", self.health)
ui.hud.set("message", "Press Interact")ui.panel.show(name)Show a named overlay panel.
Unknown panels warn once.
name | string | Panel id. v1: "npc". |
ui.panel.show("npc")ui.panel.hide(name)Hide a named overlay panel.
Unknown panels warn once.
name | string | Panel id. v1: "npc". |
ui.panel.hide("npc")ui.panel.set(name, options)Set NPC panel text and portrait.
portrait looks up an animation asset by name.
name | string | Panel id. v1: "npc". |
options | table | Table with text and optional portrait animation name. |
ui.panel.set("npc", { text = "Need a key?", portrait = "Mayor" })ui.screen.open(name)Open a UI-editor screen on the play overlay stack.
Does nothing if that screen is already on top.
name | string | UI screen name or overview slot name. |
if input.pressed("Y") then
ui.screen.open("Pause")
endui.screen.close()Close the top overlay screen.
Warns if there is no screen to close (the HUD root stays).
ui.screen.close()ui.screen.ensure(name) → screenFind 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.
name | string | UI screen name. |
Returns. screen — A screen handle. valid is false on failure.
local pause = ui.screen.ensure("Pause")ui.screen.current() → screenHandle for the live overlay screen.
This is the HUD / overlay the player sees in play mode.
Returns. screen — A screen handle.
local overlay = ui.screen.current()
overlay:add("text", { name = "prompt", text = "Hello", x = 0.3, y = 0.8, width = 0.4, height = 0.08 })ui.screen.find(name) → screen | nilFind an existing UI screen by name.
Does not create assets.
name | string | UI screen name. |
Returns. screen | nil — A screen handle, or an invalid handle if missing.
local pause = ui.screen.find("Pause")screen:bake(force?) → booleanSave 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).
forceoptional | boolean | Optional. true to rewrite even if already baked. |
Returns. boolean — true if a bake was stored.
local s = ui.screen.ensure("Shop")
s:add("Buy", { kind = "button", x = 0.5, y = 0.5 })
s:bake()screen.baked → booleanWhether this screen has a stored baked layout.
Read-only on the screen handle.
Returns. boolean — true after a successful bake.
if not screen.baked then screen:bake() endThe same widget kinds as the UI editor, via handles.
screen:add(kind, options?) → widgetCreate 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).
kind | string | Widget kind. |
optionsoptional | table | Layout and kind-specific properties. |
Returns. widget — A widget handle. valid is false on failure.
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",
})screen:find(name) → widgetFind a widget by name.
Lua finds widgets by their saved name, which must be unique on the screen.
name | string | Widget name. Case-insensitive. |
Returns. widget — A widget handle. valid is false if missing.
local hp = screen:find("hp")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.
function on_ui_build(screen)
screen:clear()
screen:add("text", { name = "title", text = "Hi" })
endscreen:count() → numberNumber of catalog widgets on the screen.
inventory_slot children count toward the screen budget.
Returns. number — Managed widget count.
local n = screen:count()screen:hit(x, y) → widgetFind the catalog widget under overlay UI coordinates.
Pass coordinates from input.ui(), not input.screen(). Returns an invalid handle on miss — check widget.valid.
x | number | Normalized UI X (0–1). |
y | number | Normalized UI Y (0–1). |
Returns. widget — A widget handle. valid is false on miss.
local ux, uy = input.ui()
local w = ui.screen.current():hit(ux, uy)
if w.valid then
-- inspect w.name / w.kind / w.slot
endwidget.valid → booleantrue 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.
if not widget.valid then return endwidget.kind → stringWidget kind string for this widget.
Read-only.
Returns. string — Kind such as button or text.
if widget.kind == "button" then ... endwidget.name → stringSaved name for this widget.
Read/write. This is what screen:find looks up.
Returns. string — Widget name.
local id = widget.namewidget.slot → stringInventory slot name when this widget is a slot.
Useful after screen:hit on inventory UIs.
Returns. string — Slot name, or empty.
local slot = widget.slotwidget:contains(x, y) → booleantrue if a UI point lies inside this widget's bounds.
Axis-aligned test in overlay space.
x | number | Normalized UI X. |
y | number | Normalized UI Y. |
Returns. boolean — Whether the point is inside.
local ux, uy = input.ui()
if tray:contains(ux, uy) then ... endwidget:set(options)Write several properties at once.
Unknown or invalid keys for this kind warn once and are skipped.
options | table | Table of property keys. |
prompt:set({ visible = true, text = "Press Interact", color = { 20, 20, 20 } })widget:get(key) → anyRead one property.
Also supports name and kind.
key | string | Property key, such as x or text. |
Returns. any — The value, or nil.
local x = widget:get("x")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.
channel | string | text, visible, or image. |
source | string | HUD display name or variable name. |
hp:bind("text", "Player Health")
flag:bind("visible", "HasRedKey")
portrait:bind("image", "NPC Image")widget:unbind(channel)Remove a bind from a channel.
Leaves the last displayed value in place.
channel | string | text, visible, or image. |
hp:unbind("text")widget:add(kind, options?) → widgetCreate a child widget under this widget.
Same kinds and options as screen:add. Counts against the per-frame add budget outside on_ui_build.
kind | string | Widget kind. |
optionsoptional | table | Layout and kind-specific properties. |
Returns. widget — A widget handle. valid is false on failure.
local label = panel:add("text", { name = "label", text = "Hi" })widget:parent(other)Reparent this widget under another.
Parent cycles warn once and do nothing.
other | widget | Parent widget handle. |
label:parent(panel)widget:unparent()Move this widget to the screen root.
Same as Unparent in the editor.
label:unparent()widget:front()Draw this widget on top of its siblings.
Same as Bring to Front in the editor.
modal:front()widget:back()Draw this widget behind its siblings.
Same as Send to Back in the editor.
bg:back()widget:duplicate() → widgetClone this widget as a sibling.
Gets a unique name. Layout is offset slightly.
Returns. widget — Handle for the copy.
local copy = button:duplicate()widget:destroy()Destroy this widget and its children.
The handle becomes invalid. Same as Delete in the editor.
prompt:destroy()Start a Conversation Arc and move through its lines and choices.
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.
arc | string | Arc display name. |
optionsoptional | table | Optional table. speaker: self handle. resume: boolean, default true. |
conversation.start("MayorQuest", { speaker = self, resume = true })conversation.stop()Stop the active conversation and hide its panel.
Keeps stored conversation indexes for the play session.
conversation.stop()conversation.advance()Advance the current dialogue node.
Same as the overlay Advance Dialogue action.
if input.pressed("A") then
conversation.advance()
endconversation.choose(option)Pick a reply option.
UI buttons that use choose_option store a 0-based option_index; this Lua call starts at 1.
option | number | Option index starting at 1. |
conversation.choose(1)conversation.playing() → booleantrue while a conversation is active.
Use this to freeze movement during dialogue.
Returns. boolean — Whether a conversation is playing.
if conversation.playing() then return endconversation.get_index(arc) → index, nodeRead the play-session cursor for an arc.
Progress is not written into the .PGD file.
arc | string | Arc display name. |
Returns. number, number — conversation index, node id.
local conv, node = conversation.get_index("MayorQuest")conversation.set_index(arc, index, node)Write the play-session cursor for an arc.
Use 0 for the unassigned / root node id.
arc | string | Arc display name. |
index | number | Conversation index inside the arc. |
node | number | Node id. |
conversation.set_index("MayorQuest", 1, 0)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.
arc | string | Arc display name. |
conversation.increment_conversation("MayorQuest")