Working in the editor

The in-engine IDE, the profiler, the gotchas, and why some calls refuse.

Part of the scripting guide · every call, as a reference

14. The in-engine IDE
15. Tips & gotchas
28. Where the frame went: perf.*
29. Options that refuse — and why an error is the kind answer

14. The in-engine IDE

Double-click a .lua in Assets (or use the Inspector's Scripting section) to open it in the Scripting tab — a small but real code editor:

Find & replace — Ctrl+F finds (seeded from your selection), Ctrl+H adds a replace row, Enter / Shift+Enter or F3 / Shift+F3 step through matches (the current one is outlined), Aa toggles match case, and ⌕ all scripts lists every matching line across the whole project. Typing in the find field never yanks focus back into the code.
Line editing — with nothing selected, Ctrl+C / Ctrl+X copy / cut the whole current line. Ctrl+D duplicates, Ctrl+Shift+K deletes, Alt+Up/Down moves the selected lines, Ctrl+/ toggles -- comments over the selection, and Tab / Shift+Tab indent / outdent a multi-line selection. Enter auto-indents (one level deeper after then/do/function).
Navigation — Ctrl+G goes to a line, Ctrl+B (or right-click) jumps to a definition, right-click also finds all references. The Console's double-click-to-source lands here too.
Saving — Ctrl+S saves, Ctrl+Shift+S saves all; closing a tab with unsaved changes asks first, and pressing Play auto-saves open edits so the run always matches what you see.
Completion & docs — the popup opens by itself only after . or :, where you're asking what fields something has; Ctrl+Space summons it anywhere else. ↑/↓ choose, Enter accepts, Esc hides it until the token changes — and Tab always indents, so completion can never eat a keystroke you aimed at your code. It understands member access on any variable — rb.fri offers friction, anim:pl offers play, and params. offers this script's own defaults keys. The highlighted entry shows its doc and a usage example in the popup; hovering an API name in code shows the same. The § Docs page has a search box over the whole guide + API reference, with worked examples under the common entries.
Formatting — Alt+Shift+F (or the ⚏ Format button, or tick on save) re-indents the file by block depth and tidies whitespace. It changes nothing else — no re-flowed expressions, no realigned comments, no moved code — and it's idempotent, so format-on-save can't produce a second diff. --@noformat exempts a file; a line ending in --@keep keeps its own indentation.
Warnings — a ⚠ n warnings strip under the editor expands into a clickable list of the mistakes Lua can't report:
- an undeclared assignment — sped = speed * dt compiles, writes a global, reads nil forever, and says nothing. The warning names it and suggests the local you meant. Globals assigned at file scope are deliberate publications (§8) and are never flagged.
- an unused local — usually a half-finished rename. Prefix with _ to keep it quiet.
- upvalue pressure — on a build whose Lua caps upvalues per function, every file-scope local is one, and you get a warning before the cap that names the fix (group related state into one table). LuaJIT's cap is 60; Luau, which the engine runs by default, has none, so on a stock build this warning does not appear at all.
- a hook that forgot the node — function update(dt) looks right and is wrong: every lifecycle hook is called with the node first (§3), so dt is bound to the node and the first arithmetic on it raises, every frame, before anything visible has happened. From the outside that isn't an error, it's a script that does nothing at all.
--@nolint silences a line; on its own line it silences the file.

Shortcuts


`Ctrl+S`	save	`Ctrl+Shift+S`	save all
`Ctrl+F`	find	`Ctrl+H`	find & replace
`F3` / `Shift+F3`	next / prev match	`Ctrl+G`	go to line
`Ctrl+C` / `Ctrl+X`	copy / cut line	`Ctrl+D`	duplicate line
`Ctrl+Shift+K`	delete line	`Alt+↑` / `Alt+↓`	move line(s)
`Ctrl+/`	toggle comment	`Tab` / `Shift+Tab`	indent / outdent
`Ctrl+B` or `F12`	go to definition	`Shift+F12`	find references
`Alt+Shift+F`	format document	`Ctrl+Space`	suggest
`Ctrl+W`	close tab

The same list lives on the tab's § Docs page.

15. Tips & gotchas

Run, then Play: scripts only execute while the game is playing (F1). Stop restores the scene to its pre-Play state.
Drive bodies by velocity, not position. Setting node.x/y/z on a Rigidbody node fights the physics step; set node.vx/vy/vz instead.
Edges vs. held: use input.pressed / input.clicked for one-shot actions (jump, fire) and input.key / input.button for held movement.
Errors appear at the top of the Scripting tab and in the Console, with the script name + line — double-click to jump to the source.
Hot-reload: just save. The script re-runs in a fresh environment, so avoid relying on state surviving a reload mid-Play.
A loop without an exit stops the script, not the editor. A pass into your scripts may run for 2 seconds (500 ms on a dedicated server, see --script-budget-ms); past that the script that overran is stopped with an error naming the budget, and it is not called again until you edit its file. Everything else keeps running. The scripts share 512 MB between them — a table that only grows hits "not enough memory" in its own call, and the rest of the game goes on.
A path is relative to the project and stays inside it. assets.getFile, assets.getContents, node.model =, a texture, a clip, a scene, a script name on a node: an absolute path or a .. that would leave the project resolves to nothing, and the Console says which rule refused it. assets.getContents lists at most 20 000 files and says so when it stops.

28. Where the frame went: `perf.*`

Until 0.33.0 the engine kept a smoothed FPS number and nothing else. No attribution — not per script, not per subsystem, not per draw. So when a game got slow, the author's only available move was to file an engine ticket. That is not a hypothetical; it happened four times:

filed as	actually was
"a crowded scene is unplayable"	component lookup was a linear scan
"cross-script wiring is slow"	`findScript` was a linear scan
"currently unplayable"	a scatter field asked for 117,000 props
"I can see through unloaded terrain"	mesh priority ignored world distance

Every one cost a round trip through the engine to discover a number the game could have read itself. Three of the four were answerable from a count alone.

function start(node)
  perf.enable(true)
end

function update(node, dt)
  -- The WORST recent frame, not the average. A 40 ms hitch once a second adds
  -- under a millisecond to a 60-frame mean, so the mean hides the thing you are
  -- chasing.
  if perf.worstMs("scripts") > 6 then
    log("slow pass — the worst is " .. perf.slowestScript())
  end
end

The buckets, in frame order: scripts mirror physics terrain scatter particles audio animation models ui render. perf.buckets() returns exactly that list, so a loop over it can never name one that does not exist.

models is what giving a node a model, or spawning a prefab that brings one, costs the frame. The file is read and its images decoded in the background, so this is the upload that follows, plus any import that cannot wait (opening a scene). floptle run has no GPU and loads no models, so there it reads 0; the game, the editor and floptle shot load them.

scripts is the whole of every script pass — the per-instance setup, the reference params, the write flush, and the hooks themselves. mirror is the ECS → Lua sync each pass runs before it calls anything, which is nested inside a pass and subtracted out of scripts so the two do not count it twice. Until 0.84.2 scripts was the hook time alone, which on one shipped game accounted 5.3 ms of a 12.9 ms step and hid an optimisation pass for a release.

Per script, by name

perf.ms("scripts") tells you the pass is expensive. It does not tell you which of your scripts is doing it, which is the actual question — so perf.scripts() returns a row per script most expensive first, and perf.slowestScript() is the one-liner you put in an assertion message.

for _, s in ipairs(perf.scripts()) do
  print(string.format("%-24s %5.2f ms  (worst %5.2f)", s.name, s.ms, s.worstMs))
end

Names are script file names, because that is what you call them.

What the number is, and what it is not. It is a wall clock around the call, so it includes everything that happened while your script was on the CPU — including things that were not your script. A garbage collection, or the operating system taking the core away for a moment, lands on whichever script happened to be running, and shows up as a large worstMs for a script that did nothing unusual.

These are a breakdown of part of perf.ms("scripts"), not all of it: the bucket is the whole pass and these are the time inside a hook. The difference is what the engine spends reaching your hooks, and if it is large the thing to look at is how many scripted nodes the scene has rather than any one script.

Two consequences worth knowing before you go optimising:

A script with no hook for that pass is not listed at all. It used to be, and a stall inside its empty span read as a 12–21 ms "peak" against a file with no update in it.
ms (the average) is the number to act on. A single high worstMs is at least as likely to be a collection as a slow script — look for one that is high consistently, or that moves when you change the script.

If the collector is what you are chasing, start with floptle run --frames 600 --alloc: it says how much Lua heap a frame allocates and which scripts it comes from. Vectors are one source — under exact every vec3 a script builds is an object, so a + b, v:normalized(), node.pos and node.worldPos each allocate, while scalar reads (node.x, v:length(), v:dot(o)) allocate nothing — but they are not always the biggest one: on one shipped game they were 2% of the frame's allocation, and the rest was tables and strings the scripts built themselves. Let the readout name the script before rewriting anything.

Counts

local c = perf.counts()
-- nodes, culled, instances, draws, chunks, props, particles
assert(c.props < 20000, "the forest is asking for too much")

Counts are free to keep, so perf.counts() works even while collection is off.

GPU time

The buckets above are the CPU's side of a frame. The GPU's side is perf.gpu(): the time each render pass took on the player's own GPU, for the last frame it finished timing.

perf.enable(true)
-- …a second later:
local opaque = perf.gpuMs("opaque + lighting")   -- sun shadows are paid for here
if opaque and opaque > 8 then
  local light = find("Lighting"):getcomponent("Light")
  light.shadowSteps = 24
  light.shadowDistance = 20
end

perf.gpu() returns { total = ms, passes = { {name=, ms=}, ... } }, in the order the passes ran. Both answer nil for the first few frames after perf.enable(true), and always on a GPU whose driver cannot time passes, so a governor has to treat nil as "no answer" rather than as zero.

The `mirror` bucket

Scripts read the scene through a copy of it that the engine brings up to date before each pass. Changing a component's value (a camera's fovY, a light's intensity, node.visible, a post-process setting) re-reads only that node, so tweening one every frame is cheap. Spawning and destroying a node add or remove that node alone, so a decal, a casing or a one-shot effect costs about one node's worth. Changing the scene's shape in place rebuilds the whole copy, and that costs time in proportion to the whole scene: renaming, reparenting, retagging and attaching a script count as shape changes. When one happens on every frame for half a second, the Console says so and names the cause.

If mirror is high, check two numbers:

local c = perf.counts()
print(c.mirrorRebuilds, c.mirrorRefreshed)   -- last frame
print(perf.mirrorCause())   -- "the tags changed on 'Crate 4' (node 812) …"

perf.counts().rays and rayMs are last frame's script raycasts and the time they took, inside scripts. A frame that spends milliseconds there is casting more rays than it needs, or casting them one at a time where raycastMany would do.

mirrorRebuilds above zero on every frame means something changes the shape of the scene every frame, and perf.mirrorCause() names the node and what changed. Usually that's a tag toggled per frame, which a field in the script can replace.

Many NPCs: put the far ones to sleep

Every script instance's hooks run every frame, and every awake rigidbody is simulated every tick, whether or not the player is anywhere near it. On one shipped level, 64 placed enemies cost 17 ms of physics and 7 ms of script per tick with all of them thinking. That's more than the whole frame budget.

Past the distance where anyone would notice, stop both:

function fixedUpdate(node, dt)
  if (find("Player").worldPos - node.worldPos):length() > 80 then
    node.vel = vec3()
    node.asleep = true               -- the solver stops simulating the body
    script.sleep{ wakeWithin = 70 }  -- the engine stops calling this script
    return
  end
  -- …think…
end

A sleeping script costs nothing a frame: the engine doesn't call it at all, so it can't check the distance itself. Instead it wakes on its own terms: wakeWithin wakes it when the active camera comes that close, and seconds wakes it after that much game time. A collision or trigger on its node also wakes it, and so does script.wake(node, "enemy") from another script, for instance the one that just shot it.

For NPCs in view but far away, script.setRate(10) runs fixedUpdate ten times a second instead of sixty, handing it the time since its last call.

It is off by default, and reading it while off is an ERROR

A profiler that is itself a frame cost gets turned off, and then it does not exist. So nothing is collected until perf.enable(true) — either from a script, or by opening the editor's ⏱ panel.

But that makes "off" and "free" the same shape, and assert(perf.ms("scripts") < 4) would then pass in a smoke test that measured nothing. So every timing getter raises while collection is off and tells you to call perf.enable(true). Same reasoning as the pin = "topCenter" fix: a wrong answer that looks like a right one is worse than an error.

An unknown bucket name raises too, and names every accepted value.

In the editor

The ⏱ button in the play toolbar opens the same numbers, per bucket and per script, with the worst column coloured. Opening it starts collection; closing it stops — unless a script asked for it, in which case it stays on so a game's own budget check keeps working.

accountedMs() is the buckets added up. It is called accounted and not total because vsync, the OS and the GPU finishing are outside every bucket; a number claiming to be the frame time without being it would be worse than not offering one.

29. Options that refuse — and why an error is the kind answer

Every options table in this engine is closed. A key it does not read is an error, not a shrug:

scatter.create{ asset = "trees/pine.glb", perchunk = 6 }
-- scatter.create: no option called `perchunk` (did you mean `perChunk`?)

node:setCamera{ target = "minimap", width = 0 }
-- node:setCamera: `width = 0` is outside 8 – 4096

audio.play("engine.ogg", { mode = "spacial" })
-- audio.play: `mode = "spacial"` is not a name I know — it takes spatial, 3d,
-- distance, flat, 2d

Every message names three things: the property, the value it got, and what it accepts. Any one of the three missing sends you back to re-reading your own file, which is the part that costs an afternoon.

Why this is worth a breaking change

43% of every bug ever filed against this engine — 32 of 74 — was one shape: the engine answered something it did not understand instead of refusing it.

scatter.create{ collide = true } was parsed, stored, and read by nothing. For two releases. A game asked for solid props and got props you walk through.
pin = "topCenter" meant top-left. Silently. Four HUD elements in one corner and a report that read like a layout bug.
A typo'd perchunk took the default, forever, with nothing to see.
scene.load(name, { addative = true }) destroyed the running scene instead of layering onto it — additive = false is what a misspelling reads as.

Every one of those was found by somebody playing, and each was fixed on its own. The counter-argument — that refusing is a breaking change — was settled the first time: a game that asked for solid props and got props it walked through was worse off than a game that got an error. Silence is not compatibility.

What keeps it true

One list per call, in the code, read by both the check and the write — so a key that is accepted is a key that does something. One shared parser per enum, so the list an error offers is the list the engine acts on. And two tests: one calls every registered options table with a bogus key and fails if it is accepted, the other scans the source and fails when a new options table appears that neither checks its keys nor is excused in writing.

So this does not decay back. That is the actual deliverable — not the 32 fixes, which were already made one at a time.

Navigation Menu

Repository navigation

workflow.md

workflow.md

Working in the editor

Contents

14. The in-engine IDE

Shortcuts

15. Tips & gotchas

28. Where the frame went: `perf.*`

Per script, by name

Counts

GPU time

The `mirror` bucket

Many NPCs: put the far ones to sleep

It is off by default, and reading it while off is an ERROR

In the editor

29. Options that refuse — and why an error is the kind answer

Why this is worth a breaking change

What keeps it true

FilesExpand file tree

workflow.md

Latest commit

History

workflow.md

File metadata and controls

Working in the editor

Contents

14. The in-engine IDE

Shortcuts

15. Tips & gotchas

28. Where the frame went: perf.*

Per script, by name

Counts

GPU time

The mirror bucket

Many NPCs: put the far ones to sleep

It is off by default, and reading it while off is an ERROR

In the editor

29. Options that refuse — and why an error is the kind answer

Why this is worth a breaking change

What keeps it true

28. Where the frame went: `perf.*`

The `mirror` bucket