diff options
| author | Gabriel Schneider <[email protected]> | 2026-09-25 23:09:07 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-09-25 23:09:07 -0300 |
| commit | bc8e6eb1bfef0c5e9b3c40fc1e4fd5a1659e2b03 (patch) | |
| tree | 15b20d84512184de3330232e828ef2553020077a | |
| parent | 0b42902ecd169d9c2d5bf4347c939bdb6da78605 (diff) | |
| download | sketchbook-bc8e6eb1bfef0c5e9b3c40fc1e4fd5a1659e2b03.tar.gz sketchbook-bc8e6eb1bfef0c5e9b3c40fc1e4fd5a1659e2b03.zip | |
sketchbook: design for editing regions in source
docs/regions-in-source.md: named regions that remember where they were
written (@src), an overlay to see and drag them, and a host-side patcher that
rewrites the literals with std.zig.Ast, so hot reload shows the edit. Also
scripts clicking regions by name. Not implemented yet.
| -rw-r--r-- | README.md | 6 | ||||
| -rw-r--r-- | docs/regions-in-source.md | 174 |
2 files changed, 180 insertions, 0 deletions
@@ -151,6 +151,12 @@ results, aligned for Vulkan. `sb.modules`, `sb.host_exe` and `sb.probe_exe` are exposed for anything else. Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`. +## Designs + +- [Regions in source](docs/regions-in-source.md): editing layout from the + running sketch by rewriting the number literals in the source (not + implemented yet). + ## The boundary Host and sketch are built by the same `zig build`, so ordinary Zig types cross diff --git a/docs/regions-in-source.md b/docs/regions-in-source.md new file mode 100644 index 0000000..4a5251a --- /dev/null +++ b/docs/regions-in-source.md @@ -0,0 +1,174 @@ +# 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. |
