summaryrefslogtreecommitdiff
path: root/docs/regions-in-source.md
blob: 4a5251a8429e5ab03634f74a305fd46b924e347c (plain) (blame)
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.