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
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
|
# Research: Zig std and sketchbook internals, for imperative creative coding
Scope: what sketchbook should add or change so Nature of Code style sketches
are easy to write while staying Zig-ish (explicit, no hidden globals, explicit
allocators, std idioms). This covers Zig 0.17 std and sketchbook's own
internals. Processing/p5 and LÖVE/raylib API surveys, and shaders in depth,
are covered elsewhere.
Paths below are relative to `lib/sketchbook/` unless they start with `src/`
of the game (`../../src/...`) or `sketches/noc/`.
Experiments were run in a scratch dir against the real `src/abi.zig`,
`src/layout.zig` and `src/host/memory.zig`, using zig 0.17.0. They are marked
**[verified]**.
---
## 0. The strongest evidence: the NoC ports already hit every gap
`sketches/noc/src/helpers_a.zig` and `helpers_b.zig` were written separately by
two port batches. Both re-implement the same missing pieces:
| Gap | helpers_a | helpers_b | Game (`../../src`) |
| --- | --- | --- | --- |
| PVector ops on `@Vector(2,f32)` | `setMag`, `limit`, `splat` (:32-40) | `mag`, `dist`, `scale`, `normalize`, `setMag`, `limit`, `heading`, `fromAngle` (:210-234) | — |
| `random(lo, hi)` over a State PRNG | `range` (:42) | `random` (:240) | — |
| `noise()` | Processing's exact table at comptime (:50-129) | table rebuilt from a seed (:279-336) | — |
| Pointer-free list for State | — | `List(T, cap)` (:247-273) | `dialogue.State.offered`+`count`, `Choice.text`+`len`, `room.Layout.items`+`len`, `tracker.Song.order`+`order_len` |
| Circles/lines/polygons with fill+stroke | `Pen` over `vector.Drawing.Builder`, GPU renderer (:146-193) | `Pen` + `Canvas` over CPU renderer (:350-399) | `ui.outline` = 4 fills (`ui.zig:20`); the cursor tail is 96 one-pixel-ish rects (`ui.zig:88-105`) |
| Transform (push/translate/rotate/pop) | `Style.transform: Affine` | `Pen.transform: Affine` (:356) | — |
| Fixed 60 Hz step | `steps60` (:17-27) | absent: batch B steps per frame, so speed depends on refresh rate | `dialogue.end(dt, ...)` uses tick dt |
| `map()` | `map` (:132) | — | — |
| draw returning errors | — | every sketch wraps: `paint(...) catch \|err\| f.host.print(...)` (`flocking.zig:130`, `system_of_systems.zig:68`, `flow_field.zig:102`, `the_wave.zig:26`) | — |
| No-`background()` trails | — | — | `random_walk.zig` keeps a `StaticBitSet(640*360)` in State and re-uploads 900 KB of pixels every frame (:19, :48-53) |
Every proposal below is something at least one of these files had to build by
hand.
---
## 1. Variable numbers of entities in State
### What layout reflection does today
`src/layout.zig:41-57` flattens *structs* into dotted leaves; everything else,
arrays included, is **one leaf** (`:50-53`, `leaf()` at `:59-78` gives arrays
kind `.array`). The leaf hash is the structural signature (`:116-147`): an
array's signature is `[N]` ++ the element's full signature, and a struct's
signature includes every field name, offset and type.
Migration (`src/host/memory.zig:95-111`) copies a leaf only if
`before.hash == leaf.hash and before.size == leaf.size`; otherwise the leaf
keeps the new default. Enums are remapped by tag name (`:113-120`); nothing
else is.
### What that means for particle lists [verified]
Prototype: `List(P, cap) = struct { buffer: [cap]P, len: u32 }`, migrated with
the real `memory.migrate`:
| Edit while running | Result |
| --- | --- |
| Add a field to `P` | `buffer` reset (every particle zeroed), `len` **kept** (10 zombie particles at the origin) |
| Capacity 64 → 128 | `buffer` reset, `len` kept |
| Capacity 64 → 4 | `buffer` reset, `len = 10` kept, so `buffer[0..len]` is **out of bounds** (`helpers_b.List.slice` at :254 would panic) |
| Same with a struct-of-arrays list (one `[cap]F` per field) | adding a field keeps every other column (`kept=3 reset=1`), with no host change |
The game has the same hazard, and worse: `tracker.State.songs: [8]Song`
(`../../src/tracker.zig:56`) is one leaf. Adding any field to `Song` (a `swing`
byte, say) on hot reload **erases every song the player composed**.
### std 0.17 situation
- `std.BoundedArray` is gone: removed in `196e36bbb2` ("std: remove
BoundedArray … handled by ArrayListUnmanaged via the '...Bounded' method
variants"). The idiom now is `std.ArrayList(T).initBuffer(&buf)` plus
`appendBounded`, `addOneBounded`, `insertBounded`, … which return
`error.OutOfMemory` when full (`/usr/lib/zig/std/array_list.zig:681`,
`:1046`, `:1425`).
- `ArrayList` holds a slice (`items: Slice`, `:647`) and `MultiArrayList` holds
`bytes: [*]u8` (`multi_array_list.zig:26`): neither can live in State.
`layout.check` rejects them at compile time, which is right.
- `initBuffer` is fine for *locals* in `update`/`draw` (`room.Layout` could be
one), but State needs its own pointer-free type.
### Proposal: `sk.List(T, capacity)` (and `sk.Ring`)
Mirror std naming so it reads like `ArrayList`'s bounded API, and clamp the
length so a capacity shrink can never index out of bounds.
```zig
// src/sketch/list.zig
pub fn List(comptime T: type, comptime capacity: u32) type {
return struct {
const Self = @This();
pub const Elem = T;
pub const cap = capacity;
/// Zeroed, not undefined: state files and snapshots stay comparable.
buffer: [capacity]T = @splat(std.mem.zeroes(T)),
len: u32 = 0,
pub const empty: Self = .{};
/// Live elements. Clamped: after a capacity shrink `len` may exceed `cap`.
pub fn items(l: *Self) []T { return l.buffer[0..@min(l.len, capacity)]; }
pub fn constItems(l: *const Self) []const T { return l.buffer[0..@min(l.len, capacity)]; }
/// Same contract as `ArrayList.appendBounded`.
pub fn append(l: *Self, item: T) error{OutOfMemory}!void;
pub fn addOne(l: *Self) error{OutOfMemory}!*T;
pub fn swapRemove(l: *Self, i: usize) T; // O(1), for particles
pub fn orderedRemove(l: *Self, i: usize) T; // keeps draw order
pub fn clear(l: *Self) void;
pub fn full(l: *const Self) bool;
};
}
/// Fixed-size history: `push` overwrites the oldest. For trails, recent
/// events, and "what happened since the last draw" (see section 5).
pub fn Ring(comptime T: type, comptime capacity: u32) type {
return struct {
buffer: [capacity]T = @splat(std.mem.zeroes(T)),
/// Items ever pushed: a sequence number that also survives wrap-around.
pushed: u64 = 0,
pub fn push(r: *@This(), item: T) void;
pub fn latest(r: *const @This(), n: usize) Iterator; // newest n, oldest first
pub fn since(r: *const @This(), seq: u64) Iterator; // pushed after `seq`
};
}
```
Usage (NoC 4.2, particle system):
```zig
pub const State = struct {
rng: std.Random.DefaultPrng = .init(4),
particles: sk.List(Particle, 512) = .empty,
};
// update, per fixed step
s.particles.append(.spawn(s.rng.random(), origin)) catch {}; // full: drop, like a capped emitter
var i: usize = 0;
while (i < s.particles.items().len) {
const p = &s.particles.items()[i];
p.step();
if (p.dead()) _ = s.particles.swapRemove(i) else i += 1;
}
```
Optional `sk.Soa(T, cap)` with `items(.pos)` (the `MultiArrayList` API shape)
gives per-field migration for free. The prototype needs one fix: use each
field's own default for its column (`attrs.defaultValue(F)`), not `zeroes`.
Without that, a new `mass: f32 = 1` column came back as 0 [verified]. SoA
reads worse for NoC code, so it is a niche tool, not the default.
**Cost:** `List` + `Ring` + tests: about 150 lines, half a day. No host change.
### Proposal: element-wise array migration in the host
Make the reflected layout understand repetition, so arrays of structs migrate
field by field and element by element, and arrays whose element type is
unchanged keep their common prefix.
1. `abi.Field` (`src/abi.zig:561`) gains `count: u32 = 1, stride: u32 = 0,
elem_hash: u64 = 0`.
2. `layout.flatten` (`src/layout.zig:41`): for `[N]S` where `S` is a
non-packed struct, recurse into `S` with the path `name[]` and emit leaves
with `count = N, stride = @sizeOf(S)`, so you get `particles.buffer[].pos.x`.
For arrays of scalars or enums, emit one leaf with `elem_hash` = hash of
the child. Nested arrays of structs (tracker `Song.patterns`) can either
multiply into up to three `(count, stride)` dimensions, or stop at one
level and rely on rule 3 for the inner arrays.
3. `memory.migrate` (`src/host/memory.zig:95`):
- a repeated leaf copies `min(old.count, new.count)` elements at their strides;
- an array leaf whose hash differs but whose `elem_hash` matches copies the
common prefix (capacity change);
- enum elements get `remapEnum` per element.
4. `StoredField` (`memory.zig:40`) gets the new fields; bump `file_magic` to
`SKETCH02` (`memory.zig:23`), and treat old files as foreign, which is the
existing path for a missing layout.
5. `fields.zig` (`format`/`set`, `:7-50`) and `web.zig` `sk_field`/`sk_tag`
(`:321-358`) accept an index in the path: `particles.buffer[3].pos.x`. Then
console `get`/`set`, script `expect`/`await`, the probe and
`window.sketch.field()` can all address individual entities.
6. The memory overlay (`host/overlay.zig:18`) shows one row per leaf, so a
repeated leaf stays one row (`particles.buffer[].pos.x ×512`).
With that change, adding `mass` to `Particle` keeps every position and
velocity, a capacity change keeps the first `min` particles, and the tracker
songs survive a new `Song` field.
**Cost:** about 230 lines including tests (layout 40, abi 5, memory 50,
fields 40, web 15, overlay 10, tests 70). About 1 day. `abi.hash` changes
automatically (`abi.zig:635`).
---
## 2. Deterministic randomness and noise
### PRNG in State: already works [verified]
```zig
pub const State = struct { rng: std.Random.DefaultPrng = .init(42) };
```
- `DefaultPrng = Xoshiro256` (`/usr/lib/zig/std/Random.zig:13`), whose state
is `s: [4]u64` (`Random/Xoshiro256.zig:9`): no pointers, so
`layout.check` accepts it.
- `.init(42)` works as a field default: `seed` runs SplitMix64 at comptime.
- Reflection gives one leaf, `rng.s` (kind `.array`, 32 bytes). It migrates
byte for byte as long as the generator type does not change.
- `std.Random` (the interface from `.random()`) holds a pointer and a
function pointer. Putting it in State is a compile error, which is correct:
take it locally.
- **Determinism across hosts [verified]:** a checksum over 20k values of
`float(f32)`, `floatNorm(f32)` (ziggurat tables), `@sin` and the noise below
was identical (`514686fd`) in native Debug (self-hosted backend), native
ReleaseFast (LLVM), wasm32 Debug and wasm32 ReleaseSmall. Recordings and
web replays agree.
- Smaller alternatives if size matters: `SplitMix64` (8 B), `Pcg` (16 B),
`Xoroshiro128` (16 B), `Sfc64` (32 B). `Isaac64` (about 4 KB) and `ChaCha`
are overkill.
- `std.Io` has randomness too (`Io.zig:1-14`). That is exactly what `update`
must not use: it is a nondeterministic source. Sketches should never be
handed an `Io` in `update`; the existing `call` dispatcher
(`src/sketch/root.zig:235-269`) already rejects unknown parameter types.
### Proposal: don't wrap the PRNG; add free functions over `std.Random`
Wrapping std's generator would duplicate its whole API. The Zig-ish move is to
keep `std.Random` as the interface and add the handful of creative-coding
draws as free functions:
```zig
// src/sketch/random.zig: every function takes the std interface
pub fn range(r: std.Random, lo: f32, hi: f32) f32; // p5 random(lo, hi)
pub fn gaussian(r: std.Random, mean: f32, sd: f32) f32; // randomGaussian, via floatNorm
pub fn chance(r: std.Random, p: f32) bool;
pub fn unit(r: std.Random) sk.Vec2; // PVector.random2D
pub fn inRect(r: std.Random, rect: anytype) sk.Vec2;
pub fn pick(r: std.Random, comptime T: type, items: []const T) T;
/// Monte Carlo / "accept-reject" (NoC 0.5).
pub fn acceptReject(r: std.Random, comptime f: fn (f32) f32) f32;
/// A generator for entity `i`, independent of how many numbers others drew:
/// edits that add a draw elsewhere don't reshuffle this entity.
pub fn stream(seed: u64, i: u64) std.Random.DefaultPrng; // .init(std.hash.int(seed ^ i *% K))
```
```zig
// update
const r = s.rng.random();
for (0..n) |_| try s.walkers.append(.{ .pos = sk.random.inRect(r, bounds), .step = sk.random.gaussian(r, 0, 2) });
```
**Where the seed comes from:**
- a fixed default (reproducible art);
- `init(s, host)` with `s.rng = .init(host.clock())`. Init is not replayed,
and the seed is saved with the state, so replays still match;
- a console `set rng.s ...` (works today).
**Randomness in `draw`** (p5 sketches often call `random()` there): `draw`
cannot write State. Use a local `std.Random.DefaultPrng.init(seed ^ in.frame)`,
or the stateless `sk.noise.hash01(seed, i)`.
**Cost:** about 60 lines, a couple of hours.
### Proposal: `sk.noise`, pure functions of seed and coordinates
Two flavours, both with no mutable globals:
```zig
// src/sketch/noise.zig
/// Gradient noise, about -1..1, a pure function: lattice corners hashed with
/// `std.hash.int` and `seed`. No permutation table, so the seed can be a
/// runtime State field.
pub fn perlin2(seed: u32, x: f32, y: f32) f32;
pub fn perlin3(seed: u32, x: f32, y: f32, z: f32) f32; // flow fields animated by z = t
pub const Fbm = struct { octaves: u4 = 4, falloff: f32 = 0.5, lacunarity: f32 = 2 };
/// p5's noise(x, y): 0..1, octaves summed.
pub fn fbm2(seed: u32, x: f32, y: f32, o: Fbm) f32;
pub fn fbm3(seed: u32, x: f32, y: f32, z: f32, o: Fbm) f32;
pub fn hash01(seed: u32, i: u32) f32; // stable "random" per index, for draw
/// Processing's own noise() (PApplet), for ports checked against reference
/// images: 4096 floats from java.util.Random's LCG. Build it where the seed
/// is known: at comptime for a constant seed (helpers_a.zig:52), or in
/// Session/on the stack from a State seed (helpers_b.zig:285). Not in State:
/// it is derived data (16 KiB).
pub const Classic = struct {
table: [4096]f32,
pub fn init(seed: u64) Classic;
pub fn get(n: *const Classic, x: f32, y: f32, z: f32) f32;
};
```
A 40-line `perlin2`/`fbm2` prototype passed range, smoothness and
seed-sensitivity tests, and gave the same bits on native and wasm [verified]
(range about -0.75..0.70, which is typical for 2D Perlin). Simplex/OpenSimplex2
can come later; Perlin covers NoC chapter 0 and the flow-field examples.
**Cost:** about 200 lines including Classic and tests, half a day.
---
## 3. Math vocabulary: `Vec2` struct vs `@Vector(2, f32)` vs duck typing
### What exists
- `src/sketch/shape.zig` duck-types points: anything with `x`/`y`, or 2+
element vectors or arrays (`:9-22`). Helpers return the caller's type
(`Out`, `:52-60`).
- `src/sketch/tween.zig:8-33` `lerp` works on floats, vectors, arrays and
structs (it splats `t` for vectors). `progress` (`:65`) is inverse-lerp
clamped, and `ease.*` (`:72`) are the easing curves.
- `src/vector/geom.zig:6-34` already uses `Vec = @Vector(2, f32)` with free
functions `dot`, `cross`, `length`, `normalize`, `perp`, `mix`, `splat`, plus
a full `Affine` (`:36-97`). That is the obvious seed of `sk.math`.
- `std.math` has `lerp` (with `@mulAdd`, where `t` must match the vector type,
so it needs a splat; `math.zig:1382`), `clamp` (scalars and vectors, `:526`),
`wrap` to `[-r, r)` (`:443`), `degreesToRadians`/`radiansToDegrees`
(`:268`, `:303`), `tau`, `atan2`, `hypot`. It has **no** `remap`/`map`,
`smoothstep`, `fract`, `sign`, or angle normalization to `[0, tau)`.
### `@Vector` findings [verified]
- Operators work for vector with vector: `pos += vel; vel += acc;`. Scalar
with vector does **not**: `v * 2` is "mixed scalar and vector operands".
You need `v * @as(Vec, @splat(k))`, or `v *= @splat(k)` where the result
type is known. Both batches wrote `scale(v, s)` for exactly this reason
(`helpers_b.zig:216`).
- No `.x`/`.y`: you write `p[0]`/`p[1]`, which is what `flocking.zig:43-46`
has to do.
- **Layout differs by backend:** `@sizeOf/@alignOf(@Vector(2, f32))` is
**16/16 on x86_64 with the self-hosted backend (Debug)**, and 8/8 with LLVM
(`-fllvm`, ReleaseFast), on wasm32 and on aarch64. So:
- in Debug, every `Vec2` in State takes double the space;
- switching `-Doptimize` changes the size, so `migrate` resets every vector
leaf (`memory.zig:102` checks size) and every array-of-structs containing
one (the signature includes offsets).
- Reflection treats a vector as an opaque leaf (`layout.zig:66`, kind
`.bytes`). `fields.zig` prints `<16 bytes>` (`:22`) and refuses `set`
(`:47`). So `get mover.pos`, `set mover.pos.x 100` and a script's
`expect mover.pos.x 320` are all impossible with `@Vector` state today.
### Proposal
1. **`sk.Vec2 = extern struct { x: f32 = 0, y: f32 = 0 }`** as the type to
*store*. It is 8 bytes everywhere, flattens to `pos.x`/`pos.y` float
leaves (console, scripts, probe and overlay all work), and `shape.zig`
already accepts it. Its methods follow PVector, so NoC translates line for
line, left to right:
```zig
pub const Vec2 = extern struct {
x: f32 = 0, y: f32 = 0,
pub const zero: Vec2 = .{};
pub fn xy(x: f32, y: f32) Vec2;
pub fn add(a: Vec2, b: Vec2) Vec2; pub fn sub(a: Vec2, b: Vec2) Vec2;
pub fn scale(a: Vec2, k: f32) Vec2; pub fn div(a: Vec2, k: f32) Vec2;
pub fn mul(a: Vec2, b: Vec2) Vec2; // component-wise
pub fn dot(a: Vec2, b: Vec2) f32; pub fn cross(a: Vec2, b: Vec2) f32;
pub fn len(a: Vec2) f32; pub fn lenSq(a: Vec2) f32;
pub fn dist(a: Vec2, b: Vec2) f32;
pub fn normalize(a: Vec2) Vec2; // zero stays zero
pub fn withLen(a: Vec2, m: f32) Vec2; // setMag
pub fn limit(a: Vec2, max: f32) Vec2;
pub fn heading(a: Vec2) f32; pub fn fromAngle(rad: f32) Vec2;
pub fn rotate(a: Vec2, rad: f32) Vec2; pub fn perp(a: Vec2) Vec2;
pub fn lerp(a: Vec2, b: Vec2, t: f32) Vec2;
pub fn simd(a: Vec2) @Vector(2, f32); pub fn of(v: @Vector(2, f32)) Vec2;
};
```
```zig
// NoC 1.10, accelerating toward the mouse
const dir = sk.Vec2.xy(in.mouse_x, in.mouse_y).sub(m.pos).withLen(0.2);
m.vel = m.vel.add(dir).limit(m.top_speed);
m.pos = m.pos.add(m.vel);
```
Compare `b.limit(b.setMag(b.scale(sum, 1 / count), maxspeed) - self.velocity, maxforce)`
(`flocking.zig:77`).
2. **Keep `@Vector` as the compute type**, for anyone who prefers operators:
`sk.math` free functions take `anytype` and follow geom's `@Vector`
versions, so `pos += vel` code works without conversions. For hot loops
over thousands of entities, `simd()`/`of()` convert at the edges.
3. **Teach `layout.flatten` to split `@Vector(N, T)` leaves into `name[0..N]`
scalar leaves.** That is about 10 lines, and makes `@Vector` state
inspectable even for sketches that choose it. The backend size difference
remains, so document "prefer `sk.Vec2` in State".
4. **`sk.math`** (scalars; lift `geom.Affine` as `sk.Affine` with
`.identity`, `.translate`, `.rotate`, `.scale`, `.mul`, `.apply`):
```zig
/// p5 map(): ranges as pairs so the five floats can't be misordered.
pub fn remap(v: f32, from: [2]f32, to: [2]f32) f32;
pub fn remapClamped(v: f32, from: [2]f32, to: [2]f32) f32;
pub fn smoothstep(e0: f32, e1: f32, x: f32) f32;
pub fn fract(x: f32) f32;
pub fn angle(rad: f32) f32; // normalized to [0, tau)
pub fn approach(cur: f32, target: f32, max_step: f32) f32;
```
```zig
const y = sk.math.remap(@sin(angle), .{ -1, 1 }, .{ 0, height });
```
Re-export rather than duplicate: `sk.math.clamp = std.math.clamp`, and
`lerp` stays `tween.lerp` (it already splats).
**Cost:** Vec2 + `sk.math` + Affine lift is about 250 lines with tests, about
1 day. Vector leaf flattening: 1 hour.
---
## 4. Drawing vocabulary: circles, lines, polylines, polygons, transforms
### What the hosts can do now
- Commands (`src/abi.zig:225-300`): `clear`, `rect`, `image`, `text`, `clip`,
plus GPU/compute.
- **Native:** `src/host/gfx.zig:112-148` executes 2D commands on an
`SDL_Renderer` created on the SDL_GPU device (`Host.zig:110-116`; it falls
back to any renderer without a GPU). The vendored SDL 3.4 has
`SDL_RenderGeometry` / `SDL_RenderGeometryRaw` (colored triangles, optional
texture), `SDL_RenderLines` (1 px only), and `SDL_RenderTextureAffine`
(an image under an arbitrary affine transform), all in
`zig-pkg/sdl-*/include/SDL3/SDL_render.h:2331, 2458, 2491`. The SDL renderer
has **no MSAA**, so anything not axis-aligned is aliased unless the geometry
carries its own feathered fringe (ImGui/NanoVG style).
- **Web:** `web/host.js:441-485` draws into a 2D canvas, which has native
antialiased `moveTo/lineTo/arc/ellipse/fill/stroke/setTransform`. It has no
per-vertex colour: Canvas2D cannot shade triangles.
- **GPU passes** (`abi.gpu.Pass`) run on SDL_GPU and WebGPU alike. That is
what the vector module uses.
### Options and costs
**A. Shape commands, rasterized natively by each host (recommended).** Add
one command, `path`, and let each host draw it its own way:
```zig
// abi.Command
/// A polyline or polygon in canvas coordinates, filled and/or stroked.
/// `points` is bulk data: scratch, session or store memory.
path: struct {
points: []const Vec2, // extern {x, y}
closed: bool = true,
fill: ?Color = null,
stroke: ?Color = null,
width: f32 = 1,
join: enum(u8) { miter, bevel, round } = .miter,
cap: enum(u8) { butt, round, square } = .round,
},
```
- **Web:** a `canvas.path(ptr, len, closed, fill_rgba, stroke_rgba, width, join, cap)`
import reads a `Float32Array` view of wasm memory, then does
`beginPath`/`moveTo`/`lineTo`/`fill`/`stroke`. That is about 25 lines of JS
plus 5 in `web.zig` (`submit`, `:175-211`). It is exact and antialiased.
- **Native:** tessellate in Zig, then call `SDL_RenderGeometry`:
- fill: a fan for convex shapes, ear clipping for simple concave ones;
- stroke: per-segment quads plus miter/bevel/round joins and caps;
- a 1 px alpha fringe, so edges are antialiased like canvas.
Shared Zig, about 300 lines (fill, stroke, fringe, tests). It can reuse
`vector/geom.zig` and the join math in `vector/Polygons.zig:153-335`.
`gfx.draw` (`gfx.zig:112`) needs an arena parameter for vertices
(`Host.zig:303` and `:316` pass `frame_arena`). Converting to `SDL_Vertex`
(float colour, `SDL_render.h:89-94`) is one loop. About 40 lines in
gfx.zig. Known gap: translucent strokes double-blend where joint triangles
overlap (ImGui has the same); canvas does not.
- **Frame helpers** (`src/sketch/root.zig`, next to `fill` at `:77`) build
points in scratch:
```zig
pub const Style = struct {
fill: ?Color = null,
stroke: ?Color = null,
width: f32 = 1,
join: ... = .miter,
cap: ... = .round,
};
pub fn line(f: *Frame, a: anytype, b: anytype, style: Style) void;
pub fn polyline(f: *Frame, points: []const Vec2, style: Style) void;
pub fn polygon(f: *Frame, points: []const Vec2, style: Style) void;
pub fn circle(f: *Frame, center: anytype, radius: f32, style: Style) void; // n from radius
pub fn ellipse(f: *Frame, center: anytype, rx: f32, ry: f32, style: Style) void;
pub fn arc(f: *Frame, center: anytype, r: f32, from: f32, to: f32, style: Style) void;
pub fn strokeRect(f: *Frame, r: anytype, color: anytype, width: f32) void; // replaces ui.outline
```
- **Transform:** a plain field on the Frame value the sketch already holds.
It is not a hidden global, and push/pop is `defer`:
```zig
pub const Frame = struct { ..., transform: Affine = .identity, ... };
for (s.boids.constItems()) |b| {
const saved = f.transform;
defer f.transform = saved;
f.transform = f.transform.mul(.translate(b.pos.x, b.pos.y)).mul(.rotate(b.vel.heading()));
f.polygon(&.{ .xy(6, 0), .xy(-6, -3), .xy(-6, 3) }, ink);
}
```
Helpers apply `transform` to points on the CPU before emitting. A rotated
`fill` becomes a `path`. `image` gets an optional affine: native
`SDL_RenderTextureAffine` (origin, right, down = the matrix columns,
`SDL_render.h:2331`); web `ctx.save(); ctx.transform(a,b,c,d,e,f);
drawImage; ctx.restore()`. About 15 lines per host. `clip` and `text` take
translation and scale only.
- **Scale:** 2048 boids is 2048 `path` commands. That is cheap on canvas, and
native batches inside SDL. No JSON, unlike GPU passes on the web.
- **Total cost for A:** abi 20 lines, Frame helpers + Style + transform 150,
tessellator 300, gfx 40, web.zig 10, host.js 40, e2e screenshots. **About
2 days.**
**B. Sketch-side tessellation into a `triangles` command.** Native is easy
(`SDL_RenderGeometry`, about 30 lines). The web cannot do per-vertex colour
in Canvas2D, and filling triangle by triangle leaves antialiasing seams. Only
worth adding *later* for meshes (native exact; web approximates with
flat-colour paths), not as the shape primitive.
**C. Tessellate into a library-owned GPU pass** (one MSAA draw of all shapes,
with shaders built like `vector`'s). The look is identical on both hosts
(SDL_GPU / WebGPU MSAA), and trails come almost free (section 5). But it
requires a GPU (no WebGPU in insecure contexts or on Firefox Linux), draws
into a separate image so ordering with `rect`/`text` means layers, and needs a
shader build step in the sketch library. **About 3 days.** A good second
backend for heavy particle counts, not the first.
**D. The vector module, as the NoC helpers do now.**
- `Renderer(.gpu)` emits 2 draws per fill and 2 per stroke (`vector/Gpu.zig:63-80`):
4 draws per stroked, filled boid, so 8k draws for 2048 boids, each
serialised to JSON on the web (`web.zig:231-280`).
- `Renderer(.cpu)` re-rasterizes and re-uploads the whole canvas every frame
(`vector/root.zig:118-123`).
Both are right for SVG and manim-style work, but heavyweight as the default
`circle()`.
**Recommendation:** A now; C later as an opt-in "many shapes" backend.
---
## 5. Persistence of the frame (trails, no `background()`)
### Facts
- **Native** clears the window every frame (`Host.zig:285-287`) and presents a
swapchain whose old contents are undefined. Nothing persists without an
offscreen target.
- **Web:** the 2D canvas keeps its pixels between frames unless the sketch
clears or `fit()` resizes (`host.js:21-31`). So web "persists" by accident,
and the hosts disagree.
- **GPU passes with `.clear = null`** keep the image's previous contents
(`abi.zig:440`):
- Web honours that even with MSAA: the msaa attachment is stored and loaded
(`host.js:221-235`).
- **Native does not when `samples > 1`:** `gpu.zig:214` forces `LOADOP_CLEAR`
for multisampled passes. That is a host divergence. The fix is
`SDL_GPU_STOREOP_RESOLVE_AND_STORE` and `LOADOP_LOAD` on the msaa texture
when `clear == null` (about 5 lines).
- `random_walk.zig` works around all this by keeping a 28 KB bitset in State
and re-uploading 900 KB of RGBA every frame (`:19`, `:48-53`). That is
deterministic but heavy.
- When paused, `draw` still runs every frame (`Host.frame`, `:228-242`).
Naive accumulation therefore keeps adding the same shapes while paused, and
after a seek the accumulated picture belongs to another timeline.
### Proposal: `target` command + `sk.Layer`
```zig
// abi.Command
/// Commands after this draw into `image` (from Host.newImage), or the canvas again with null.
target: ?Image,
```
- **Native:** `SDL_SetRenderTarget(renderer, texture)`. Restore to
`self.offscreen` when headless (`Host.zig:524-535`), else NULL. Reset the
clip rect on every switch. `Images.new` (`gfx.zig:44-48`) must create
`SDL_TEXTUREACCESS_TARGET` textures (or add `newCanvas`). Verify that
`SDL_UpdateTexture` (`.pixels`) still works on target textures, and how
logical presentation and render scale apply per target in SDL 3.4: a
10-line experiment. `.clear` calls `sk_text_begin_frame` (`gfx.zig:115`),
which flushes first (`vendor/text.c:105-113`), so it is safe. Text density
inside a target needs checking (`text.c:115`).
- **Web:** `newImage` already makes a 2D canvas per image (`host.js:427-431`).
`target(id)` switches the `ctx` the canvas imports draw with (make it
`let`). Identity transform for image canvases, `fit()`'s scale for the main
one. About 15 lines.
- Make sure `.image` of the *current* target is refused, since you can't
sample what you're drawing.
```zig
/// Session: an accumulating picture. A presentation cache, not state: it
/// restarts after a seek, a replay or a reload, and adds nothing while paused.
pub const Layer = struct {
image: Image = .none,
w: u32 = 0, h: u32 = 0,
/// The state step drawn last.
drawn: u64 = 0,
/// Starts drawing into the layer; false when `step` has not moved on.
/// Clears on first use, on size change, and when `step` went backwards.
pub fn begin(l: *Layer, f: *Frame, step: u64, clear: Color) bool;
/// Back to the canvas, and shows the layer at `dst`.
pub fn end(l: *Layer, f: *Frame, dst: anytype) void;
};
```
```zig
// NoC 0.1 random walk, without a bitset in State:
pub const State = struct {
walker: sk.Vec2 = .xy(320, 180),
rng: std.Random.DefaultPrng = .init(1),
clock: sk.Clock = .{},
/// Every position since the last draw could have missed: steps are
/// fixed-rate, frames are not.
recent: sk.Ring(sk.Vec2, 64) = .{},
};
pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void {
if (ss.trail.begin(f, s.recent.pushed, .white)) {
var it = s.recent.since(ss.trail.drawn);
while (it.next()) |p| f.fill(.{ .x = p.x, .y = p.y, .w = 1, .h = 1 }, .black);
}
ss.trail.end(f, .{ .x = 0, .y = 0, .w = 640, .h = 360 });
}
```
`Ring.since` is what makes it exact: at 30 Hz display and a 60 Hz step,
every step is still drawn. For p5's `background(0, 12)` fading trails, draw a
translucent full-canvas `fill` into the layer first. Known 8-bit residue: the
fade never reaches pure black. Document it.
For pictures that must be exact under seek (sand piles, CA history), keep the
data in State (bitset or `List`) as `random_walk` does. The Layer is the cheap
answer for everything else.
**Cost:** abi 3 lines, gfx/Host 30, web 20, Layer + Ring 80, native MSAA load
fix 5. **About 1 day.**
---
## 6. What to lift from the game and the NoC helpers
| Where | What | Lift as |
| --- | --- | --- |
| `helpers_a.zig:17-27` (both batches needed it; B is frame-rate dependent without it) | 60 Hz fixed step from tick dt, clock in State | `sk.Clock = struct { carry: f64 = 0, steps: u64 = 0, pub fn advance(c: *Clock, in: *const Input, hz: f32) u32 }`, used as `for (0..s.clock.advance(in, 60)) \|_\| step(s);` |
| `flocking.zig:128-135` and three more | `paint(...) catch \|err\| f.host.print(...)` wrappers | Let `draw`/`init`/`update` return `!void`. In `Glue` (`root.zig:282-292`): if the return type is an error union, log `"{name}: {t}"` through `host.print`. About 8 lines. Frame drawing methods stay infallible (they already log OOM, `root.zig:65-67`). |
| `ui.zig:16-18` | `rect(x, y, w, h)` constructor | decl literal `sk.Rect.xywh(x, y, w, h)`, so `.xywh(...)` where the type is known |
| `ui.zig:20-25` | outline as 4 fills | `f.strokeRect` / `path` with `stroke` |
| `ui.zig:88-105` | tail as 96 rects | `f.polyline(points, .{ .stroke = pink, .width = 3 })` |
| `ui.zig:30-35`, used by computer/lock/inventory/portrait/dialogue | press-and-release-on-same-target click | `sk.Press(Target)`: `pressed: T = none`, `fn click(p, target, e) bool`. Every scene's `pressed: Target = .none` + `ui.clicked` call becomes one field and one method. |
| `ui.zig:37-64` | beveled button | stays game-side (it's a look), but motivates `sk.Press` |
| `dialogue.zig:38-50`, `Choice` `:26-34`, `room.zig:75-92`, `tracker.zig:30` | `[N]T` + `len` everywhere, `[N]u8` text + `len` | `sk.List(T, N)`; `sk.List(u8, N)` with `appendSlice`/`set(text)` for bounded strings |
| `assets.zig:150-243`, `sounds.zig:69-104` | lazily loaded catalogue keyed by a comptime-generated enum, in Session | `sk.Images(Id)` / `sk.Sounds(Id)` over `std.EnumArray(Id, Image)` plus a `loaded` bitset, with `get(host, id)` and `check(host) usize`. `std.EnumArray` is the std idiom here. |
| `sounds.zig:50-67` | per-bank serial counters + active bits to retrigger voices | a `sk.Cue` (serial: u16, `fire()`) in State, taken by `f.voice(.{ .serial = s.cue.serial, ... })`; this generalises `sk.Request` (`request.zig:11`) |
| `ui.zig:68-84` | damped follower advanced per event | an example, not library (NoC chapter 3 springs cover it) |
| `room.zig:69-71` | rect scaled from source-image pixels | `sk.shape.scale(r, k)` next to `inset`/`offset` (`shape.zig:126-135`) |
| `flocking.zig:131-134` | timing draw with `host.clock()` + env flag | host overlay `overlay timing`: the host already knows each draw's duration |
### API-shape proposals from std conventions
- **Decl literals:** `.empty` for containers (`List`), `.init(seed)` for
things that need arguments (PRNG, `Classic`), `.zero`/`.identity` for values
(`Vec2`, `Affine`), and `Color.gray(v)`, `.rgb()`, `.hsv()`, `.hex()`
constructors. These only work where the parameter is *typed*. With
`anytype` (`shape.color`, `shape.zig:94`), `f.clear(.gray(51))` fails to
compile ("not a function") [verified]. Two cheap fixes:
1. `shape.color` maps an enum literal to a `Color` declaration
(`@field(Color, @tagName(c))`), so `f.clear(.black)` works [verified];
2. new APIs take `Style`/`Color` typed (`Style.fill: ?Color`), so
`.{ .fill = .gray(127) }` works.
- **Options structs** with defaults, as std does
(`std.ArrayList.initCapacity` aside, see `Io.Dir.OpenOptions`):
`f.image(img, dst, options: anytype)` (`root.zig:81`) is the only `anytype`
options parameter left. Type it as `struct { src: ?Rect = null, tint: Color = .white, transform: ?Affine = null }`
for ZLS completion and better errors, as `audio`/`pixels`/`download`
already are (`:113-157`).
- **Errors:** container ops return `error.OutOfMemory` like the `*Bounded`
ArrayList methods, so `try`/`catch {}` reads the same as std.
- **std.Io:** don't hand sketches an `Io`. `Host` (`abi.zig:445-531`) is
already the explicit capability object, it covers what sketches need
(files, clock, env), and the web has no `Io` implementation. Keep `Io` out
of `update` above all: its randomness and clock are nondeterministic.
- **SPIR-V (brief):** 0.17 has `std.spirv` (builtins as `addrspace(.input)`
externs, `spirv.zig:1-25`), `callconv(.spirv_vertex/.spirv_fragment/.spirv_kernel)`
(`lang.zig:382-384`) and `@SpirvType`. The interest for this design is
that a Zig shader could share `sk.Vec2`/vertex structs directly with option
C's shape pipeline. But web still needs WGSL via naga, which the GLSL path
already does. Left to the shader research.
---
## Cross-check against the other research (board.md)
- **research-love P2 `Command.shape`** (one colour, pre-transformed triangles
that don't overlap, plus an optional alpha fringe; the web fills them as
one nonzero path): **I adopt it in place of my `path` command (option A).**
- Tessellation stays in the hot-reloadable library, both hosts get the same
geometry, and the host side is about 30 lines each. gfx.draw needs an
arena parameter (`Host.zig:303,316`). One fill per shape on the web has
no seams.
- Risk to test: strip-tessellated strokes fold back on the inner side of
acute joins. The flipped, opposite-winding triangles cancel under nonzero
on the web (a hole) and double-blend natively. Compute inner-join points,
falling back to bevel when the miter passes the segment ends, and add a
translucent zig-zag e2e screenshot on both hosts.
- My section 4 frame helpers (`line/polygon/circle/...`, `Style`,
`f.transform` with `defer`) still hold; research-love's `Pen` value
(`translated()` returns a copy) is the same idea. Either works; the Pen
copy needs no `defer`.
- **research-love P4 `sk.Rng{ s: [4]u32 }` integer-only**, and research-p5's
"pin the PRNG": agree on owning the generator, because a std release could
change `DefaultPrng` or `Random.float` under saved recordings. Float parity
is *not* the reason: std floats already match bit for bit across hosts
(section 2). Two corrections:
1. the `s` array is not visible to `get`/`set` today (`fields.zig:22,47`)
until arrays become indexed leaves (section 1);
2. noise needs a `seed` parameter (`simplex2(x, y)` has none), because
flow_field reseeds on click (`flow_field.zig:91`).
- **research-love P10 `sk.Bounded` and `sk.v2` over `@Vector`**:
- `Bounded` = my `List`: same migration hazard (verified), so it needs
element-wise migration and clamped `items()`.
- `sk.v2` is fine as compute functions, but don't recommend `@Vector`
*storage* in State: it is 16 B in Debug on x86_64 and opaque to
get/set/expect. Store `extern Vec2`, or at least split vector leaves into
`[0]`/`[1]`.
- **research-love P6 targets + `Input.jumped`**: adopt `jumped` in place of
my step-went-backwards heuristic. Keep the two extra rules from section 5:
no accumulation while paused, and `Ring.since` for skipped steps.
- **Coordinator: element-wise migration is the real gap**: confirmed by
running the real `memory.migrate` (section 1).
- **Owner: knobs in build.zig.** These host constants are hardcoded today:
- `slot_count = 8` and `header_len = 64 KiB` (`memory.zig:21-22`);
- `store_base` and `store_reserve = 64 GiB` (`:318-320`);
- the web event queue `[1024]Event` (`web.zig:74`);
- `keep_frames = 300` and `staging_size = 4 MiB` (`gpu.zig:13,108`);
- and a `use_llvm` choice for Debug sketch libs, which fixes `@Vector`'s
layout.
These belong in `sketchbook.init(b, .{ ... })` (`build.zig:202`) as a
generated options module. Algorithm choices (noise flavour, PRNG) stay as
explicit calls in code, not build-global modes.
---
## Ranked proposals
| # | Proposal | Cost | Removes |
| --- | --- | --- | --- |
| 1 | `Command.shape` (research-love P2; replaces my `path`) + lib tessellator + `f.line/polyline/polygon/circle/ellipse/arc/strokeRect` / Pen + `Style` + transform + image affine | ~2 days | both `Pen`s, the vector-module dependency for basic shapes, `ui.outline`, the 96-rect tail |
| 2 | `sk.List(T, cap)` (clamped `items()`, std bounded naming) + `sk.Ring` | ½ day | helpers_b List, every `[N]T + len` in the game |
| 3 | Element-wise array migration (repeat leaves, prefix copy, indexed paths) | ~1 day | particle wipes and zombie `len` on reload; protects tracker songs |
| 4 | `sk.Vec2` extern struct with PVector methods + `sk.math` (`remap` with ranges, `smoothstep`, `fract`, `angle`) + `sk.Affine` lifted from `vector.geom`; flatten `@Vector` leaves | ~1 day | both batches' PVector helpers, `p[0]` indexing, uninspectable vector state, backend-dependent 16-byte vectors |
| 5 | Randomness: own pinned generator (`sk.Rng`, research-love P4, Xoshiro/PCG with our own `float`), or `std.Random.Xoshiro256` by concrete name, never the `DefaultPrng` alias; free helpers `range/gaussian/unit/pick/stream` | 2 h | `range`/`random` helpers |
| 5b | Build options for hardcoded host constants (snapshot slots, header size, store reserve, web event queue, gpu cache/staging, Debug backend) | ½ day | owner's "knobs in build.zig" |
| 6 | `sk.noise`: table-free `perlin2/3`, `fbm` with options, `hash01`, Processing-exact `Classic` | ½ day | both noise ports |
| 7 | `target` command + `sk.Layer` (+ native MSAA `clear = null` fix) | ~1 day | random_walk's bitset + full re-upload; host divergence |
| 8 | `sk.Clock` fixed step | 1 h | `steps60`; batch B's refresh-rate-dependent speed |
| 9 | Fallible `draw`/`update`/`init` logged by Glue; typed options; decl-literal colours (`.black`, `.gray(v)`) | 2 h | four `paint` wrappers; `anytype` papercuts |
| 10 | Game lifts: `sk.Press(T)`, `sk.Images(Id)`/`Sounds(Id)` over `std.EnumArray`, `sk.Cue` | ½ day | per-scene click bookkeeping, asset library boilerplate |
|