1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
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.
|