summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/regions-in-source.md174
1 files changed, 174 insertions, 0 deletions
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.