summaryrefslogtreecommitdiff
path: root/examples/noc/notes/design.md
blob: 5762f410d61867f1fac627b0352c83a06c6aaa8c (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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
# sketchbook, iteration 1: design

Merged from the 12 Nature of Code ports (friction-a/b.md), three research
notes, two adversarial critiques (critique-core.md, critique-zig.md), the
shader pass (../../shaders/README.md) and board.md. Nothing here is built
yet; `lib/sketchbook` is untouched.

## Principles (owner)

- The deterministic core stays: State is plain data, `update` sees only
  State and Input and is replayed, `draw` emits commands as data, and both
  hosts run every command.
- The new API is a **layer on top**, Zig-style (`std.posix` under
  `std.Io`). Today's `abi.Command`, `f.emit`, GPU passes, `Input.events`
  and Frame methods stay as they are. The new layer is sketch-library code
  with no hidden state that hands its intermediate data out: a Pen yields
  triangles you can emit yourself or feed to your own GPU pass.
- Build knobs live in `build.zig`, but the critics drew a line: **a build
  option must not change what `update` computes or the state-file
  format** (a `-D` noise flavour or snapshot count makes a recording or a
  state file mean something else). Knobs that pass this test: test
  optimize mode, shader language, web/PWA, tools.

## What the ports showed

- Both porters independently wrote the same ~200-line helper file:
  circles/lines/stroke under a transform through the `vector` module,
  PVector ops, a PRNG in State, Perlin noise, a fixed-capacity list, a
  fixed-step clock. 9 ports need filled/stroked circles, 3 need line
  segments, 2 need convex triangles, 3 need translate·rotate, 4 need alpha.
  Nothing used arcs, blend modes, HSV, image transforms, or randomness in
  `draw`.
- **Three host bugs** surfaced, each found independently by more than
  one agent and confirmed by experiment:
  1. Seek feeds the whole recording to **one** `update`, with mouse/key
     state as of the batch's end. `accel_to_mouse` ends at (581, 311) by
     playback but (350, 195) by `seek end`. Slow-frame playback batches
     too. `in.dt`/`in.now` are wrong during replay (Host.zig:229-246).
  2. Input state is not part of snapshots/recordings: a replay after a
     live mouse move ends at (163, 102) instead of (581, 311).
  3. Arrays are opaque migration leaves: change an element type or a
     capacity and the array resets to `undefined` while its `len` is
     kept, giving garbage elements, or a panic on shrink. The game's
     tracker songs are exposed the same way. Separately, a state file
     the host doesn't recognise is **truncated** on open (memory.zig:129).

## Disagreements, decided

| Question | Decision | Why |
| --- | --- | --- |
| `Command.shape` payload: `triangles` (critic-zig) or `points + ends + indices` (critic-core) | **`{ color, points, ends, indices }`** | Measured: Canvas2D fills a triangle soup 3.6× slower than the outline (1000 circles: 11 vs 3 ms), and seams between separately filled triangles show. The web fills the subpaths as one nonzero path; native passes points+indices straight to `SDL_RenderGeometry`. The library guarantees positive winding and disjoint triangles. |
| `Vec2` struct with methods (research-zig) or `@Vector(2, f32)` | **`@Vector`** + host splits vector lanes into leaves | `+=` stays; one type with the shaders (`vec2`). The real problems (unreadable in console/scripts, Debug's 16-byte layout resetting on `-Doptimize`, padding garbage in `diff`) are fixed in the host by lane leaves and leaf-wise compare. |
| `Rng` wrapper / own PCG32 vs std generator | **`std.Random.Xoshiro256` (concrete, never `DefaultPrng`) in State, plus a build stamp in recordings** | No wrapper earns its lines (`std.math.lerp(lo, hi, r.float(f32))`). The concrete type can't silently change via the `DefaultPrng` alias, and the stamp warns when a recording is played against a different build. Open question below if you want our own algorithm anyway. |
| Clock cap (≤ 8 steps/call) | **Keep the cap, after the per-tick host fix** | With one `update` per tick, the cap depends only on the recorded tick, so it replays identically; it prevents the spiral of death after a stall. Before the host fix every Clock design is wrong. |
| AA fringe on shapes | **No fringe** | It halves 1 px line intensity on the web (128 vs 255). Native shapes are aliased like `rect` today; see open questions. |

## Iteration 1, in order

Each step ships with its tests (details in critique-core §3).

**A. Host behaviour (no API change)**
1. One `update` per tick: playback, seek and step deliver whole frames;
   `in.dt`/`in.now` come from the tick in both live and replay (so they
   match bit for bit); Input is reset and re-seeded on record start and
   snapshot restore. Tests: play-vs-seek-vs-step equal the stop snapshot;
   replay after a live move equals the first replay.
2. Inspection: `@Vector` lanes and array elements become addressable
   leaves (`get/set/expect pos[0]`, `boids.buffer[3].pos[1]`), `diff`
   compares leaf by leaf, and script `expect`/`await` take `~tol`. This
   removes the 8 State fields the ports added only for their tests.
3. Element-wise array migration (copy shared elements field by field,
   enums by name, clamp on shrink), with a reader for today's state
   files. Never truncate an unrecognised file; refuse it instead.
   Fixture: a copy of `drat-meout.state` keeps every value.

**B. The one new host primitive**

4. `Command.shape { color, points: []const [2]f32, ends: []const u32,
   indices: []const u32 }`: one SDL_RenderGeometry call natively, one
   nonzero path fill on the web. Tests on both hosts: overlapping
   translucent circles, a concave polygon, an acute translucent zig-zag
   stroke (no holes, no double blend), a 1 px line, and 5000 circles
   under 16 ms on the web.

**C. The new layer (sketch library; pure, no state of its own)**

5. `sk.math`, one geometry module shared with `vector`:
   `Vec = @Vector(2, f32)`, `scale`, `distance`, `withLength` (setMag),
   `clampLength` (limit), `angle` (heading), `unit` (fromAngle),
   `Affine.place(at, radians)`, `noise(seed, x, y, z)` (table-free, golden
   values equal on native and wasm). The README gets a PVector-name table.
6. `sk.draw`, two levels:
   - L1: `fillCircle`, `strokeCircle`, `fillPolygon`, `strokePolygon`,
     `strokeLine`. Each appends to a caller-owned `sk.draw.Tessellation`
     (points, ends, indices), using a caller-given allocator, with an
     `Affine`.
   - L2: `Pen { fill: ?Color, stroke: ?Color, width, xf }` as plain data,
     where `pen.transformed(m)` is the push. `sk.draw.circle/line/polygon(f,
     …, pen)` tessellate into scratch memory and emit `shape`; on
     out-of-memory they log and drop, like `Frame.emit`. Radius, not
     diameter. One colour type (`abi.Color`, with `Color.gray(v)`).
7. Root: `sk.Clock { hz, owed, count, steps(in) }` and `sk.List(T, cap)`
   with std names (`appendBounded`, `orderedRemove`, `swapRemove`,
   `slice`, `constSlice`), clamped, defaulting to `@splat(.{})` (not
   `zeroes`: enums without a 0 tag).

**D. Parity fixes and tooling**

8. Web image tint keeps RGB (it keeps only alpha today); native MSAA
   passes with `clear = null` load (clearing on first use, since Vulkan
   starts undefined and WebGPU zeroed).
9. Recordings carry the sketch build hash; `play` warns on a mismatch.
10. Build/harness:
    - `addZigShaders` moves into sketchbook's build.zig, with the SPIR-V
      fix-up tool (from sketches/shaders).
    - An e2e optimize option.
    - Concurrent e2e runs get unique store paths.
    - Fix the teardown segfault on the store-busy path (Host.zig:118).
    - Investigate `LeakedSdlMemory` under parallel e2e (−j1 passes 12/12).

**E. Then:** rewrite the 12 ports on the new layer, delete
helpers_a/b.zig, and compare line counts (critic-zig estimates 778→~640
in the ports and 296→~25 in the helpers). At least one port (flocking)
drops to L1/L0 to batch 1000 boids into 2 commands.

## Deferred (no port needs it yet)

Offscreen targets, `jumped`, Layer/Ring for trails (2 ports, both with
workarounds that stay correct after a seek), blend modes (SDL's multiply
differs from Canvas for α<1), colour spaces, image affines, textures in
GPU passes, `Draw.instances` (safe whenever wanted), arcs/ellipses/joins,
input sugar, fallible `draw`, host constants as build options (never as
compile-time file-format constants).

## Open questions for the owner

1. **Native antialiasing.** Canvas2D antialiases shapes; SDL_RenderGeometry
   does not, so native circles look jaggier than the same sketch on the web.
   Accept it for iteration 1, or add an MSAA SDL_GPU pipeline for `shape`
   on the host (no API change)?
2. **RNG.** Concrete std `Xoshiro256` plus the build stamp, or our own
   pinned generator (PCG32) so recordings survive Zig upgrades?
3. **Processing-exact noise.** One sketchbook noise in the library, with
   porter-a's exact Processing `noise()` kept in the noc project for
   faithful ports. Fine?
4. **Order.** A (host fixes) first is safest, since it changes behaviour
   under your existing recordings and the game. Or start with B+C to see
   the ports shrink sooner?

## Decisions taken (owner delegated them)

1. Native shapes ship aliased in iteration 1; antialiasing becomes a phase-3
   feature, driven by the recursive tree (thin lines).
2. RNG: `std.Random.Xoshiro256` used directly in State, plus the build stamp
   on recordings.
3. One table-free noise in the library; porter-a's Processing-exact
   `noise()` stays in the noc project.
4. Order: iteration 1 (host fixes + drawing layer, built in parallel by
   core-host and draw-layer), then rewrite the 12 ports on it, then phase 3.

## Phase 3: new examples that need the deferred features

Each feature is built only together with an example that needs it, and the
example is written from scratch on the new API.

| Example (NoC 2nd ed.) | Feature it drives |
| --- | --- |
| 4.8 Image texture system: smoke | `imageMode(CENTER)`-style placement, image tint alpha on both hosts, Gaussian random (`std.Random.floatNorm`) |
| 4.9 Additive blending | blend modes (`alpha`, `add`), with SDL vs Canvas parity tests |
| 8.6 Recursive tree | recursion over `Pen.transformed`, stroke width from the mouse, native antialiasing for thin lines |
| 8.5 Koch curve | data that grows 4× per click: `List` capacity vs Store-backed growth |
| 8.9 L-system | strings that grow to thousands of characters: State vs Store, turtle push/pop |
| 5.8 Path following | translucent thick polylines with joins (miter/round/bevel), `noFill` shapes |
| 5.13 Quadtree | stroked rects, points, thousands of shapes per frame |
| 5.12 Bin-lattice separation | 2000 boids: batching/instancing performance |
| 11.1 Flappy bird | text, game loop, restart: game-style structure |
| 0.1/0.6 walkers (rewritten again) | offscreen targets + `Input.jumped` for trails, replacing the Session-repaint workaround |

## Acceptance: live reload, per example (owner)

Every example (the 12 rewritten ports, the phase-3 examples, the Book of
Shaders sketch) must hot-reload both its Zig code and its shaders with
State kept. Checked automatically, not by hand:

- `App.addReloadCheck(.{ .script, .edits })` in sketchbook's build.zig
  builds the library twice: as written, and from a copy of the sources
  with textual `edits` applied (`.{ .file, .old, .new }`, failing the
  build if `old` is not found exactly once). It runs the script through
  the generic host with `{v2}` defined as the second build.
- Each example's reload script plays a while, takes a screenshot, checks
  State fields, runs `load {v2}`, checks that the same State values
  carried over, plays on, and takes a second screenshot. A compare step
  asserts the screenshots differ where the edit should show.
- Each example declares one code edit (e.g. a color or a force constant
  in `draw`/`update`). Shader examples also declare one shader edit, in
  Zig and in GLSL.
- Checked once by hand: the file watcher path (`zig build run` with
  `zig build lib --watch`) on one example, editing a Zig shader.

## Acceptance: timeline, per example (owner)

Every example must scrub correctly: pause, go back, replay. Each example
gets a timeline script that:

1. records its own interaction (clicks, drags, keys) for a few seconds,
   then stops and snapshots slot N;
2. `play`s to the end, and the state equals slot N exactly (leaf by leaf,
   no tolerance: this is the determinism claim);
3. `seek`s to the end, and to the middle then plays on: both equal slot N;
4. `step`s back and forward and lands on the same frames;
5. pauses for a while: State does not move (`draw` must not change it);
6. replays after a live mouse move: equals the first replay (critic-core E2);
7. screenshots after a seek and compares with the live screenshot at the same
   point. This catches draw-side caches (trails) that the state check
   cannot see; the walkers' trails must pass it once phase 3 adds targets
   and `Input.jumped`.

Script support (core-host): `expect-snapshot N` (live state equals slot N,
leaf-wise, reporting the first differing leaves) and screenshot equality
(shared compare tool with draw-layer's reload check).

### Phase 3 addition: vector GPU backend draw count (from perf.md)

fix1–3 (pipeline looked up once per pass, redundant state calls skipped,
one vertex binding) are applied in lib/sketchbook. What's left is ~0.6 µs of
driver CPU per draw, and the vector GPU backend issues 2 draws per filled
shape. Cut the draw count: convex single shapes drawn directly (no stencil),
and fills with disjoint bounds batched into one stencil + one cover draw.
Driven by 5.13 Quadtree / 5.12 Bin lattice when drawn through `vector`, and
measured with perf.md's bench.