# Regions in source: editing layout from the running sketch Status: design, not implemented. Every clickable or placed rectangle stays a plain number literal in the Zig source. The running sketch knows where each literal is written. Dragging a region in an overlay rewrites those exact numbers in the file; `zig build lib --watch` rebuilds and hot reload shows the result. The code stays the only source of truth, and the editor is a faster way to type numbers. Today, drat-meout's hotspots are numbers in code: the room's in painting pixels (`sourceRect(...)`, scaled by 0.6), the vault, lock, portrait, bag and answers in canvas pixels (`targetRect`, `panel_rect`, `answers`, `digitX(i)`). Draw and hit-test share them, so they agree, but they are invisible without a screenshot, every change is edit-rebuild-look, and the end-to-end scripts click raw pixels (`click 566 416`), which break silently when anything moves. ## 1. Declaring a region A region is a named rect that remembers where it was written: ```zig // vault.exe's Unlock button, in canvas pixels. pub const unlock = ui.Region.at(@src(), "vault.unlock", 394, 396, 344, 40); ``` - `@src()` gives the file, line and column of the `@src()` token: enough to find the four literals that follow it in the same call. - `Region` is a comptime constant (name, rect, source location, coordinate space). Hit testing (`unlock.rect.contains(x, y)`) and drawing read it, so nothing about it changes at runtime: `update` stays deterministic and replays cannot drift. - Drawing reports it: `f.region(unlock)` appends a debug-only command, "this region is on screen now". Only the overlay and scripts read these reports. - Coordinate spaces: the room's hotspots live in painting pixels, so they declare it and the editor converts: ```zig pub const clock = ui.Region.in(@src(), .painting, "nightstand.clock", 330, 440, 414, 270); ``` ## 2. Computed layouts Rows like the vault's digit arrows are not four literals each; they are a formula. Two rules cover them: - **One call site, many instances.** If a loop calls `Region.at(@src(), ...)` once per digit, all four share one set of literals. Dragging any of them moves the shared numbers, and all four follow. The overlay shows them linked. - **Parameters as tweakable scalars.** A single number gets the same treatment as a rect: ```zig const digit_gap = ui.tweak(@src(), "vault.digit_gap", 96); pub fn arrowUp(i: usize) ui.Rect { return .{ .x = digit_x + i * digit_gap, ... }; } ``` The overlay shows the tweakables of whatever region is under the mouse, and dragging adjusts the parameter. The same mechanism covers any number, not only layout: a hex color, a typing speed, an ease. An argument that is not a literal (`digitX(i)`) is locked: the overlay draws that side with a lock mark and will not drag it. ## 3. The editing loop 1. `console overlay regions` (or a key) turns the overlay on and pauses the timeline, so edits never land in the middle of a recording. 2. The overlay draws every reported region: outline, name, and coordinates in the region's own space. Linked instances share a color. 3. Drag the body to move, drag edges or corners to resize, arrow keys to nudge a pixel. Regions snap to a grid and to neighbouring regions' edges; a modifier turns snapping off. 4. While dragging, a ghost outline previews the new rect. The game does not move yet, which keeps game code pure. 5. On release the host rewrites the source (section 4). The watcher rebuilds, and the reloaded library reports the new rect, replacing the ghost about a second later. A later, optional variant could show the real sprites move during the drag: a debug-only override table the host passes in and `Region` consults. That is a truly live preview, but it is more machinery and sidesteps determinism, so it is only worth adding if the ghost feels too slow. ## 4. Rewriting the source In the host, which has access to the files: - `@src().file` is relative to the app's module root; `addRun` passes that root to the host (`--source-root`). - Parse the file with Zig's own parser (`std.zig.Ast`), find the builtin call at that line and column, then its parent call (`Region.at` or `ui.tweak`), then the argument nodes. - Each editable argument must be a single number literal token. Replace only those bytes: `zig fmt` output, comments and spacing all survive. - Before writing, check that the literals in the file still hold the values the running library reported. If they do not (the file was edited since the last build), refuse and say so instead of patching the wrong numbers. - Round to whole pixels (half pixels with a modifier), write the file in one step by replacing it, and keep each write on an undo stack (Ctrl+Z restores the previous text). The VCS snapshots every step too. - In review the change is a number changing on one line. ## 5. Clicking by name The reports carry the names, so scripts and tests stop holding pixels: ``` click vault.unlock # the center of the region, as last reported click-at vault.unlock 0.9 0.5 # a relative point inside it expect-region vault.unlock # it is on screen ``` Unit tests already click through `targetRect`-style functions; those become `region.rect`. ## 6. Where each part lives - **sketchbook**, all generic: `ui.Region` and `ui.tweak` (sketch side), the debug `region` command, the regions overlay (ghost, snapping, undo), the source patcher on `std.zig.Ast`, the `click NAME` script commands, and `--source-root` from the build. - **drat-meout**: replaces `targetRect`/`sourceRect` literals with `Region` declarations, one scene at a time. The vault first, since it mixes literals with a computed row. - **Release and web builds**: reports and source locations compile out outside Debug. On the web the overlay can still show regions, but nothing can be patched, since there are no files. ## 7. Limits and risks - Only literal arguments are editable, by design; anything computed needs its parameters marked with `tweak`. - The call has to keep a recognisable shape. A region whose `@src()` and literals are split across helper functions cannot be patched; the overlay marks it read-only. - Two regions on one line patch fine (the lookup is by column), but a lint suggesting one per line is worth having. - A rebuild error mid-edit (a syntax error elsewhere in the file) leaves the old library running; the overlay shows the watcher's build status. - Every drag is a small commit-sized change to the source. That is the point, but a dragging session is best followed by a squash. ## 8. Order to build it 1. `Region` and the reports, plus a read-only overlay. This alone gives visualization and `click NAME` in scripts. 2. The patcher, for plain literal rects: move and resize. 3. `tweak` scalars, linked instances, and coordinate spaces (the room's painting pixels). 4. Snapping, nudging, undo. 5. Optionally, the live-preview override table. Step 1 is useful on its own: it takes pixel coordinates out of the scripts before any editing exists. ## Alternatives considered - **A `.zon` layout file per scene**, imported at comptime and written back by the overlay: plain data and diffable, but a second source of truth next to the code. - **Tweakable layout structs in `State`**, edited with the console's `set`: instant and no new machinery, but layout ends up in save files until baked back into code. - **An SVG per scene** drawn in Inkscape or Figma and parsed with `vector.svg`: good for odd-shaped hotspots over paintings, weaker for layouts built in code. - **A separate layout editor sketch**: the richest editing, but outside the running game, away from its real context. Source rewriting was chosen because it keeps one source of truth, the code, and needs no new file formats.