You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Reserve the names the engine supplies to a live script
MoonLive scripts now read `width`, `height`, `depth`, `x`, `y`, `z` and `t` as system
variables the engine hands them, instead of each module secretly pasting declarations on
top of the script and hiding them from the UI. An effect is told the size of the layer it
draws into, so it can no longer claim a different one; a layout keeps naming its own size,
because it is what defines the grid in the first place.
Performance: desktop 139 us/tick (7194 fps), esp32 2151 us/tick (464 fps).
Core
- SysVar/SysVarTable beside BuiltinTable, same shape and lookup: a host registers the names
it defines, the compiler resolves them before locals and controls. `t` was a hardcoded
identifier check; it is now an ordinary table entry, so there is one resolution path.
- Reserved: a control declaration or a `for` variable reusing a system name fails with
"name is a system variable". Those are the only two places a script can introduce a name.
- The controls arena is split - script controls below kMaxCtrls, system variables above -
so adding a control, which renumbers every control offset, cannot move a slot a binding
cached a pointer to.
- controlSlot() was bounded by controlCount_, so every system-variable write landed on a
null pointer and was silently dropped. Bounded by the arena now.
- A nested loop reusing the enclosing loop's variable emitted a program that never
returned - a watchdog reset from a script a user can type. Refused at compile time.
Pre-existing, found by review.
- kCodeCap lived as four independent literals whose comments warned they must agree; one
core constant now, which each backend derives its buffer from.
Light domain
- Each binding supplies only what it writes: a layout gets the clock, an effect adds the
grid, a modifier adds the coordinate. Supplying a name is what reserves it, so `x` and
`y` stay usable as loop counters where nothing hands out a coordinate, and a layout
asking for `width` is an error rather than a silent zero that places no lights.
- sin/cos over math16, and turn(n) - one revolution split n ways. A full turn is 65536, one
past the largest number a script can write, so a circle cannot be spelled without it.
- Layout scripts name their own controls (cols/rows/radius); ring.mlv added, which places
24 lights in an 11x11 box - the case where light count and grid size differ.
- The script-size constant and its rationale were copy-pasted into three bindings; one
kMaxScriptBytes now.
Tests
- Reserved names, per-binding supply, and the nested-loop hang are each pinned. The script
sweep compiles every .mlv against its own binding's table, so a script cannot read a name
its module never writes and still pass.
Docs/CI
- MIGRATING entry: a persisted layout script declaring `width` no longer compiles and its
fixture goes dark until edited. MoonLiveEffect.md documents system variables and the call
vocabulary, which had no home before.
- Backlog: a scripted modifier cannot reshape the grid yet - system variables are read-only,
so modifyLogicalSize needs a writable kind plus a read-back.
Reviews
- 👾 Reviewer, 11 findings: 8 fixed (the nested-loop hang, the two design findings above,
four stale/duplicated comments, the SysVarTable cap). 1 skipped - folding SysVarTable's
lookup into a shared template is a refactor beyond this change, and the Reviewer's own
conclusion was that two types are correct. 2 were no-defect (arena sizing, reserved-name
coverage), both re-verified here.
- 🐇 CodeRabbit, 5 findings: 2 fixed in the monitor (a SHA mismatch no longer decodes a
backtrace against the wrong ELF; an unreadable ELF degrades to raw addresses instead of
ending the session), 1 doc fence tagged. 3 skipped: they describe patching a code buffer
that lowerToBytes discards on overflow before it is ever copied out, and an out-of-bounds
label index that newLabel() makes unreachable.
Known limits
- lines.mlv does not compile on Xtensa: fill plus two loops exceeds the S3 register budget.
It runs on S31 and desktop. Verified against the real backend; every other shipped script
compiles on all three.
- Flash on esp32s31 reads +92 KB against a baseline built before this branch's Ethernet
work, so most of that is not this change; the comparable S3 figure is +1.8 KB.
Flash: esp32 1762368, esp32s3-n16r8 1752128, esp32s31 2024672, desktop 1137800.
Tests: 1322 cases.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: docs/MIGRATING.md
+17Lines changed: 17 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,6 +20,23 @@ projectMM ships **no migration code**: the persistence layer is robust by defaul
20
20
21
21
## Unreleased (`next-iteration`)
22
22
23
+
### MoonLive: a script can no longer declare a name the engine supplies (2026-08-10)
24
+
25
+
`t` (elapsed milliseconds), `width`/`height`/`depth` (the logical grid) and `x`/`y`/`z` (the light a modifier is transforming) are now **system variables** the engine supplies, so a script cannot declare one. Previously each binding faked them by prepending hidden declarations to the script, which meant an effect could declare its own `width` and quietly disagree with the layer it was drawing into.
26
+
27
+
Each module supplies only the names it writes, so what is reserved depends on the module: a layout gets `t` alone, an effect adds the grid, a modifier adds the coordinate. **`x` and `y` remain usable as loop counters in a layout or an effect.**
28
+
29
+
**Action: *update a file*, for scripted layouts only.**
30
+
31
+
A **layout** is the one script that legitimately used those names for its own controls: it *defines* where lights are, so it has no grid to be handed. A persisted layout script declaring `uint8_t width = 16;` now fails to compile with `name is a system variable`, and the layout places no lights — the fixture is **dark** until the script is edited.
32
+
33
+
| What | Why | What to do |
34
+
|---|---|---|
35
+
| A scripted layout declaring `width`/`height`| The name is what the layout is defining, so the declaration is a compile error and no lights are placed | Edit the script's `source` control, renaming its own controls (the shipped `grid.mlv` uses `cols`/`rows`) |
36
+
| A scripted **modifier** using `x`, `y` or `z` as a loop variable | A modifier IS handed a coordinate under those names, so they cannot also be counters there | Rename the loop variable to something the modifier is not handed (`i`, `n`) |
37
+
38
+
Effects and modifiers need no change: they were already being handed these values, just through a preamble instead of by name. The error names the clash, and the module shows it on its card, so a broken script says why rather than failing silently.
39
+
23
40
### The `Layers` container is renamed to `Effects` (2026-08-08)
24
41
25
42
The three top-level light containers are now **Layouts, Effects, Drivers** — L.E.D. The old name sat one character from its own child (`Layers` holding `Layer`s) and read as a near-twin of `Layouts`, which is the pair a newcomer actually has to tell apart. The tree is unchanged in shape: `Effects` → `Layer`s → effects and modifiers.
Copy file name to clipboardExpand all lines: docs/backlog/backlog-light.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -284,6 +284,8 @@ The LED-driver increments **shipped**: increment 1 (RMT/WS2812B single-strand on
284
284
285
285
**Why it waits.** It is fourteen effects' worth of change across audio-reactive and simulation families, each needing its own judgement about whether to clear, fade, or seed differently — not a mechanical sweep. `unit_Effects_gridsweep.cpp` already measures it (`afterFirst`) and asserts only the settled frame, so the number is visible without blocking.
286
286
287
+
-**A scripted modifier that reshapes the grid** (2026-08-10). `ModifierBase::modifyLogicalSize` lets a modifier change the logical `width`/`height`/`depth` — a Multiply kaleidoscope grows the grid, a crop shrinks it — and a compiled modifier uses it. A SCRIPTED one cannot: system variables are read-only, so `MoonLiveModifier` writes the box in and never reads it back. Needs a writable system variable — the binding reads the slots after the script returns and reports the result through `modifyLogicalSize` — which is a new `SysVarKind` (or a mutable flag on `SysVar`) plus the read-back, not a new builtin. Until then a scripted modifier can fold coordinates but not resize the grid they live in.
288
+
287
289
-**Drain MoonLive's `print()` through a queue** (2026-08-09). `print(v)` writes to serial directly, and an EFFECT script runs on the render tick — so a print inside one blocks the frame for as long as the UART takes. The burst cap bounds it (a handful of writes per compile, then a compare and a return), but bounded is not free, and `tick()` is annotated `MM_NONBLOCKING`.
288
290
289
291
**What it costs when it comes:** a small preallocated record queue the built-in writes into, drained from a housekeeping path through the existing platform output seam. The budget and the burst-spent message stay as they are; only where the bytes are written moves. Worth doing when a script is left with a print in it on a real fixture, which is the case the cap exists for.
Measured at `32ed3f66`. Generated by [`moondeck/check/repo_health.py`](../../moondeck/check/repo_health.py) on every KPI-gate run. **Do not edit by hand.**
3
+
Measured at `4806046b`. Generated by [`moondeck/check/repo_health.py`](../../moondeck/check/repo_health.py) on every KPI-gate run. **Do not edit by hand.**
4
4
5
5
Current state only; the trend is this file's git history (`git log -p docs/metrics/repo-health.md`). Nothing here fails a build: the numbers make growth visible, the judgment stays human.
Copy file name to clipboardExpand all lines: docs/moonmodules/light/MoonLiveEffect.md
+39Lines changed: 39 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,6 +27,45 @@ The functions are **not built into the compiler** — `setRGB`, `fill`, `random1
27
27
28
28
Declaring the variable is what **creates** the control: `uint8_t <name> = <default>;` becomes a `<name>` slider (default `<default>`, range `0..255`). The trailing `// @control <min>..<max>` only **adjusts that control's range**; it's optional. A declared name used in a statement reads the control's **current** value. Editing a control's slider does **not** recompile — the value lands in the engine's control-values arena and the next render tick reads it (the live-edit guarantee, the *no-reboot* principle). Editing the `source` recompiles and re-derives the control set; a control kept across the edit keeps its slider value, a removed control's saved value drops. Stage 1 is `uint8` only.
29
29
30
+
### System variables — what the engine hands a script
31
+
32
+
Some names are **reserved**: the engine defines them, the script only reads them, and a declaration that reuses one is a compile error (`name is a system variable`). Each module supplies the names it actually writes, so a name a script cannot be given is simply unknown there rather than silently reading 0.
33
+
34
+
| name | what it is | layout | effect | modifier |
35
+
|---|---|:-:|:-:|:-:|
36
+
| `t` | elapsed milliseconds — the clock an animation is written against | ✓ | ✓ | ✓ |
37
+
| `width`, `height`, `depth` | the **logical grid** the script renders into | | ✓ | ✓ |
38
+
| `x`, `y`, `z` | the light being transformed | | | ✓ |
39
+
40
+
Supplying a name is also what reserves it, so the tight lists are what leave `x` and `y` usable as ordinary loop counters in a layout or an effect — neither is handed a coordinate.
41
+
42
+
`width`/`height`/`depth` are the Layer's own dimensions, derived from the layouts and the modifier chain. An effect is *told* its canvas rather than declaring it: a size restated as a control is a second answer that can disagree with the first, and a script that sets `width` to 16 on an 8×8 panel draws off the edge. A [layout](MoonLiveLayout.md) is upstream of that grid — it is what the dimensions are derived *from* — so it is not given them at all, and names its own controls instead (`cols`, `rows`).
43
+
44
+
Reserving is what makes the guarantee hold: without it a declaration would silently shadow the value the engine handed in, and the script would disagree with its layer with no error anywhere.
45
+
46
+
### The vocabulary — what a script can call
47
+
48
+
Registered by the light domain, not built into the compiler (the core owns only the grammar and a generic call/inline mechanism), so the list is one edit in `MoonLiveBuiltins_light.h`.
49
+
50
+
| call | does |
51
+
|---|---|
52
+
| `setRGB(index, r, g, b)` | write one light |
53
+
| `setXYZ(index, x, y, z)` | write one position (a [modifier](MoonLiveModifier.md)) |
54
+
| `fill(r, g, b)` | write every light |
55
+
| `addLight(x, y, z)` | place the next light (a [layout](MoonLiveLayout.md)) |
56
+
| `random16(n)` | a value in `[0, n)` |
57
+
| `mod(a, b)` | `a % b` — the wrap a cyclic animation needs |
58
+
| `beat(bpm, t)` | a `0..65535` sawtooth at `bpm` |
59
+
| `beatsin(bpm, t, high)` | a sine `0..high` at `bpm` |
60
+
| `scale(value, n)` | a `0..65535` value onto `0..n` — lands a wave on an axis |
61
+
| `sin(angle)`, `cos(angle)` | the circle; one turn is `0..65535`, result biased to `0..65535` centred at 32768 |
62
+
| `turn(n)` | one revolution split `n` ways — the angle step for placing `n` points on a circle |
63
+
| `print(v)` | log a value and return it ([what it costs](../../../moonlive/README.md#debugging-print)) |
64
+
65
+
`sin`/`cos` return an **unsigned** wave, so a coordinate comes from scaling by the full span and not by half of it: `scale(cos(a), radius * 2 + 1)` sweeps a whole axis, where scaling by `radius` alone would only ever reach one side of centre.
66
+
67
+
`turn(n)` exists because a full revolution is 65536 — one past the largest number a script can write — and the grammar has no division. Without it, placing `n` points evenly on a circle is not expressible.
68
+
30
69
### Wire contract — control declaration
31
70
32
71
The controls are **derived from `source`** (one per declared `uint8` control; the optional `@control` annotation only refines a control's range), then **surfaced in `/api/state`** — the device JSON view the integrator consumes — as regular `uint8` controls alongside `source`. So an integrator sees and writes them exactly like any other control — e.g. `POST /api/control` with `{"module": "ML", "control": "speed", "value": 80}`; they're fully present in the device JSON, just authored in the script rather than fixed in the module. The script's `\n` line breaks are standard JSON string escapes the device decodes, so a multi-line `source` round-trips.
Copy file name to clipboardExpand all lines: docs/moonmodules/light/MoonLiveLayout.md
+23-11Lines changed: 23 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,40 +11,52 @@ A [layout](layouts.md) is the one part of the pipeline that differs for every ph
11
11
The script places every light itself, with a loop. That is the difference from a scripted modifier: the Layer calls a modifier once per light, so its script transforms a single coordinate — a layout has no such per-light call to ride on.
12
12
13
13
``c
14
-
uint8_t width = 16; // @control 1..64
15
-
uint8_t height = 16; // @control 1..64
14
+
uint8_t cols = 16; // @control 1..64
15
+
uint8_t rows = 16; // @control 1..64
16
16
17
-
for (yy = 0; yy < height; yy = yy + 1) {
18
-
for (xx = 0; xx < width; xx = xx + 1) {
19
-
addLight(xx, yy, 0);
17
+
for (y = 0; y < rows; y = y + 1) {
18
+
for (x = 0; x < cols; x = x + 1) {
19
+
addLight(x, y, 0);
20
20
}
21
21
}
22
22
``
23
23
24
24
That is the default: a plain grid, one light per cell. `addLight(x, y, z)` places the next light along the strand — no index, because the order the script calls it in *is* the strand order.
25
25
26
-
The `width` and `height` lines are the script's own controls, not something the module hands it. A layout is never told how big it is: the pipeline works out the bounding box from the coordinates the layouts actually place, so a size passed in from outside would be a second answer that could disagree with the first.
26
+
The `cols` and `rows` lines are the script's own controls, not something the module hands it. A layout is never told how big it is: the pipeline works out the bounding box from the coordinates the layouts actually place, so a size passed in from outside would be a second answer that could disagree with the first.
27
+
28
+
They are named `cols`/`rows` because `width`, `height` and `depth` are [system variables](MoonLiveEffect.md#system-variables--what-the-engine-hands-a-script) — the logical grid the Layer hands an effect or a modifier. A layout is upstream of that grid, so it names its own controls.
27
29
28
30
A few shapes that are one line here and a new class otherwise:
29
31
30
32
``c
31
33
// a strand that runs right to left
32
-
for (i = 0; i < width; i = i + 1) { addLight(width - 1 - i, 0, 0); }
34
+
for (i = 0; i < cols; i = i + 1) { addLight(cols - 1 - i, 0, 0); }
33
35
34
36
// a diagonal
35
-
for (i = 0; i < width; i = i + 1) { addLight(i, i, 0); }
37
+
for (i = 0; i < cols; i = i + 1) { addLight(i, i, 0); }
36
38
37
39
// two rows, stacked
38
-
for (i = 0; i < width; i = i + 1) { addLight(i, 0, 0); addLight(i, 1, 0); }
40
+
for (i = 0; i < cols; i = i + 1) { addLight(i, 0, 0); addLight(i, 1, 0); }
41
+
42
+
// a circle: lights and grid cells are not the same number
A script reads whatever it declares. `uint8_t width = 16; // @control 1..64` becomes a real slider in the UI, and the loop reads it — which is how a panel gets resized without editing code.
53
+
A script reads whatever it declares. `uint8_t cols = 16; // @control 1..64` becomes a real slider in the UI, and the loop reads it — which is how a panel gets resized without editing code.
54
+
55
+
It also reads `t`, the elapsed milliseconds, which is a [system variable](MoonLiveEffect.md#system-variables--what-the-engine-hands-a-script) rather than a control — the only one a layout is given. `width`/`height`/`depth` name the grid a layout is *defining*, so asking for one is a compile error rather than a silent zero; `x` and `y` are free to use as loop counters.
44
56
45
57
### Seeing inside a script
46
58
47
-
`print(v)` logs a value and returns it, so it wraps any part of an expression: `addLight(print(xx), yy, 0)`.
59
+
`print(v)` logs a value and returns it, so it wraps any part of an expression: `addLight(print(x), y, 0)`.
48
60
It is for debugging and comes back out again — [what print costs](../../../moonlive/README.md#debugging-print).
Copy file name to clipboardExpand all lines: docs/moonmodules/light/MoonLiveModifier.md
+1-4Lines changed: 1 addition & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,10 +21,7 @@ setXYZ(0, (width - 1 - x) * 2, y, z); // mirror, then stretch
21
21
22
22
### What a script can read
23
23
24
-
| name | is |
25
-
|---|---|
26
-
|`x`, `y`, `z`| the position of the light being folded |
27
-
|`width`, `height`, `depth`| the box that position lives in |
24
+
`x`, `y`, `z` (the light being folded) and `width`, `height`, `depth` (the box it lives in) are [system variables](MoonLiveEffect.md#system-variables--what-the-engine-hands-a-script) — the engine writes them per call, and a script cannot declare a name that shadows one.
28
25
29
26
`width` matters more than it looks. A mirror written against a fixed `255` sends every light of a 16-wide grid far outside the grid, the Layer discards each one as out of bounds, and the fixture goes black — with no error anywhere, because the script itself ran perfectly.
Copy file name to clipboardExpand all lines: moondeck/MoonDeck.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -956,7 +956,7 @@ Reads serial at 115200 baud. Output streams to MoonDeck's log and is saved to `e
956
956
957
957
**Panic backtraces are decoded.** A crash prints `Backtrace: 0x4038456d:0x3fcae310 …`, which says nothing on its own; with `--firmware` each address is resolved against that build's ELF and the function, file and line print underneath:
958
958
959
-
```
959
+
```text
960
960
Guru Meditation Error: Core 0 panic'ed (LoadProhibited)
0 commit comments