summaryrefslogtreecommitdiff
path: root/examples/noc/notes/impl-lib-features.md
blob: d3106ad6c399fcec7cffac56aee90b98689b8d81 (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
# Phase 3, lib-features: as shipped

The phase-2 library fixes (rewrite-a/b friction), then stroke joins and
caps, bulk rects and points, data that grows, and a game, each driven by a
new example in `sketches/noc` written from scratch (the Processing port in
`~/05-genizah/noc-2-processing-port` read for behaviour only). Paths are
relative to `lib/sketchbook/` unless they start with `sketches/`.

## API added

```zig
// ---- sk.Clock (src/sketch/clock.zig) ----
pub const Clock = struct {
    hz: f32 = 60,
    owed: i64 = 0,                                  // was f64 seconds; now ns, down to -slack
    count: u64 = 0,
    pub fn steps(c: *Clock, in: *const Input) u32;
    pub fn tick(c: *Clock, dt: u64) u32;            // was dt: f32 seconds; now ns (`e.tickDt()`)
    pub fn stepNs(c: *const Clock) i64;
};

// ---- sk.math (src/math/) ----
pub fn noise(seed: u32, x: f32, y: f32, z: f32) f32;   // same signature, new distribution
pub fn uniform(r: std.Random, lo: f32, hi: f32) f32;   // random(lo, hi)
pub fn randomUnit(r: std.Random) Vec;                  // PVector.random2D()

// ---- sk.draw (src/sketch/draw.zig) ----
pub const Join = enum { miter, round, bevel };
pub const Cap = enum { butt, round, square };
pub const Stroke = struct { width: f32 = 1, join: Join = .miter, cap: Cap = .butt,
    closed: bool = false, miter_limit: f32 = miter_limit };
// Tessellation (L1):
pub fn strokePath(t, gpa, points: []const Vec, style: Stroke, xf: Affine) Error!void;
pub fn fillRect(t, gpa, r: math.Rect, xf: Affine) Error!void;
pub fn strokeRect(t, gpa, r: math.Rect, width: f32, xf: Affine) Error!void;
// strokePolygon / strokePolyline keep their signatures (now strokePath underneath).
// Pen (L2): new fields `join: Join = .miter`, `cap: Cap = .round` (Processing's defaults)
pub fn Pen.outline(p: Pen, closed: bool) Stroke;
pub fn polyline(f: *Frame, points: []const Vec, pen: Pen) void;   // beginShape()/endShape()
pub fn rect(f: *Frame, r: math.Rect, pen: Pen) void;
pub fn point(f: *Frame, at: Vec, pen: Pen) void;                  // a dot `width` across
// line() now honours pen.cap (round, the default, is the old stadium).

// ---- sk.Derived (src/sketch/derived.zig; exported from root.zig by render-features) ----
pub fn Derived(comptime T: type) type;   // { value: T, key: ?u64 = null,
    //   stale(d, key: u64, in: *const Input) bool,  forget(d) }

// ---- abi.Input (render-features' file, asked for and agreed on the board) ----
pub const MouseButton = enum(u16) { left = 1, middle = 2, right = 3, _ };
pub fn mouseHeld(in, button: MouseButton) bool;
pub fn mousePressed(in, button: MouseButton) ?Event;    // first press this frame, with x/y
pub fn mouseReleased(in, button: MouseButton) ?Event;

// ---- host (src/host/fields.zig, script.zig, Console.zig) ----
pub fn fields.formatPath(layout, memory, path, w) !void;  // scalars, or `{ ... }` of everything under a path
// script: `print FIELD` (stderr, no frame); `console get` takes no frame;
// `get`, `print` and a failed `expect` show vectors/arrays/structs as values.
```

## Decisions

- **Clock slack.** Counting integer nanoseconds alone does not fix it: a
  step at 60 Hz is 16 666 667 ns, a frame 16 666 666. Two allowances, both
  an eighth of a step (2 ms at 60 Hz): a tick within it of a whole number
  of steps counts as exactly that many (vsync snapping), and a step is due
  once `owed` is within it (so `owed` may sit a little below 0). With the
  snap, a 60 Hz display steps exactly once a frame; with the early step,
  measured vsync jitter (frames up to 1.5 ms late) still gives 1 a frame
  at 60 Hz and 0,1,0,1 at 30 Hz. A slack as small as the old helper's
  1 µs would not cover jitter, and plain rounding (step at half a step)
  puts the threshold exactly where a 30 Hz clock on a 60 Hz display lands.
  It stays per tick, so N×1 == 1×N; all integer, so replays are bit-equal.
  `owed` changed type, so a saved clock resets `owed` (a fraction of a
  step) on migration; nothing else.
- **Noise.** The same table-free hash-lattice gradient noise, two changes:
  the octave sum is scaled 0.7 instead of 0.5/0.9375 (measured on 200 000
  points: sd 0.109 in 3D, 0.110 in 2D, 0.116 in 1D, against Processing's
  0.108/0.123/0.142; flow_field's grid 0.109 vs 0.111; range ≈ 0.07..0.94,
  no clipping), and each octave is offset by fractions of the golden ratio
  so integer inputs are no longer exactly 0.5. Gradient (Perlin) noise
  rather than Processing's value noise: no visible grid, and the mean is
  0.5 (Processing's is 0.47). New goldens, checked natively and on wasm32.
  flow_field now uses it (`noise(seed, x·0.1, y·0.1, 0)`, the seed from
  `random(10000)` as the book does); its picture has the book's swirls and
  streams (looked at). `src/processing_noise.zig` stays: render-features
  keeps noise_walker on it (design.md decision 3).
- **Scripts/console.** `formatPath` walks every leaf under a path and sorts
  by offset, so `{ .count = 12, .hz = 60 }` is memory order, not
  declaration order (Zig reorders struct fields); good enough to read,
  and stable for a build. Capped at 64 values plus "... N more". Failed
  exact expects already printed the found value (core-host); now vectors
  print too. Only `get` became frameless among console lines: `diff` is
  read-only as well, but the game's console.script counts frames after it.
- **Random in a range: tiny helpers, not a README line.** `uniform(rng, lo,
  hi)` and `randomUnit(rng)` are free functions over `std.Random`: no
  wrapper type, the generator stays std's in State. They replace the two
  most frequent spellings in the ports (`std.math.lerp(lo, hi,
  r.float(f32))` 5× in angular_forces' init; two lerps per random vector).
- **Joins and caps.** Built into the existing stroker, keeping its contract
  (disjoint, positively wound triangles; an outline the web fills to the
  same region): a round join is a fan over the circular segment beyond the
  bevel triangle, a round cap a fan over the half disc beyond the butt
  end, a square cap a butt cap moved out by half a width. Arc points sit
  in the outline in travel order, so the web's path is the same shape.
  `Stroke.closed` sits in the style struct (SVG's `Z`) rather than a
  positional bool. Pen defaults are Processing's (miter, round), so
  `line` is unchanged. A zero-length open path is a dot with round or
  square caps, nothing with butt (SVG).
- **State vs Store for growing data** (README "Data that grows"):
  - Koch and the L-system keep only the **generation** (one byte) in
    State. Their data is a pure function of it: 65 536 segments (1 MiB) at
    Koch generation 8, an 88 940-character sentence at L-system generation
    5, and their tessellations. Putting them in State would copy them into
    every snapshot and seek; a `List` big enough would be 8 × 1 MiB in the
    state file for nothing. Store is wrong too: it is not rewound by a
    seek, so it would need the same key anyway, and it outlives the
    process for no reason. So they live in Session as `sk.Derived`,
    rebuilt when the generation differs (a click, a seek, a step) and on
    the first frame after a reload (new code may derive differently: the
    Koch reload edit flips the peaks, and the picture follows). The
    timeline scripts check it: a screenshot after a step back shows the
    previous generation, after stepping forward again the same picture as
    played.
  - The quadtree's **points** are what `update` changes (a drag adds them),
    so they are a `List(Vec, 4096)` in State (32 KiB). Its **tree** is
    derived, and cheap: rebuilt in `f.scratch` every frame (2000 inserts),
    no cache.
  - Store is for the user's work that is not a function of State.
  The library piece is `sk.Derived` (~25 lines): the key check plus the
  reload rule, which is the part easy to forget.
- **Turtle push/pop** is recursion: `[` calls `walk` with a copy of the
  transform, `]` returns. No stack type needed; `Affine` is the state.
- **Flappy Bird structure.** The book's version only prints "OOPS!" and
  flies on. Added, as a game needs: a round ends on a hit (nothing steps
  while `over`), a click or space starts the next (`newRound` resets
  bird, pipes, score; keeps `best` and the generator), the score counts a
  pipe once the bird is past it. Optional fields are not reflected in
  State, so "which pipe was hit" is `over: bool` + `hit: u8`. Text uses
  `f.print` over a translucent `rect` panel so pipes do not hide it.
- Two book quirks: 5.13 centres y on `width / 2` (the cloud sits on the
  bottom edge), changed to `height / 2`; its root boundary is twice the
  canvas (half-sizes = width, height), kept, since it decides where the
  first split lines fall.

## Examples (sketches/noc, `// phase 3: lib-features` rows)

Lines non-blank, non-comment (as loc-before.txt), against the Processing
port's .pde files counted the same way.

| example | Zig | Processing | drives | notes |
| --- | ---: | ---: | --- | --- |
| path_following (5.8) | 84 | 184 | `polyline`, round joins, translucent thick stroke, no-fill | road = black α55 over white = Processing's gray 200; `expect-pixel` checks 200 at both joins (blended once). Debug geometry computed by one `aim` used by `update` and `draw`. |
| quadtree (5.13) | 101 | 156 | `strokeRect`/`fillRect` in bulk | ~700 outlines + 2000 points in one `shape`; query dots in a second. Debug build: ~6.5 ms a frame headless (3000 frames in 19.5 s). Drag adds points (the book's video version). |
| koch (8.5) | 54 | 58 | growth ×4 a click, `sk.Derived` | one round-joined `strokePath` through all points; generation 5 is the book's picture. |
| lsystem (8.9) | 77 | 64 | growth ×8 a click, turtle push/pop | step halves per generation so the tree keeps the book's size (6 px at 4). |
| flappy_bird (11.1) | 113 | 94 | text, score, round over, restart | +score, best, end of round, restart, text panels over the book. |

Each has `test/<name>.script` (screenshots looked at and compared with the
Processing sketch's picture), `test/<name>.timeline.script` (the template,
with its own input; koch and lsystem add step-back/step-forward
screenshot checks), and a reload edit + `test/<name>.reload.script`
(State kept, screenshots differ): road colour, query square colour, Koch
peaks pointing down (a derivation change, so it checks that `Derived`
rebuilds on reload), L-system angle 25° → 35°, green pipes.

## Tests

- clock.zig: N×1 == 1×N over 600 random ticks plus a stall; 6000 script
  frames at 60 Hz give exactly one step each; vsync with up to 1.5 ms of
  lateness gives 1 a frame at 60 Hz and alternating 0/1 at 30 Hz; a
  dropped frame is 2; 144 Hz on 60 averages 2.4.
- noise.zig: smoothness and range; spread on flow_field's grid over 50
  seeds (sd 0.095..0.13, mean 0.5 ± 0.02); no exact 0.5 at 100 lattice
  points; new goldens (native and wasm32-wasi).
- math: `uniform` range, `randomUnit` length.
- draw.zig: every join × cap × width (2, 12, 30) × transform (identity,
  mirror, place) on the zig-zag, a closed square, and the path-following
  shape at width 40, all through the contract checker (disjoint, positive,
  area equals the subpaths'); stadium area = round-capped segment, square
  cap area, zero-length dots; rect fill/stroke areas, many rects in one.
- derived.zig: stale on key change, after reload, after `forget`.
- fields.zig: `formatPath` for a vector, a lane, a struct, a struct
  element, an array of structs, a long array (cut off), an unknown path.
- test/replay.script: `print`, `console get` of a vector and a struct
  element (checked with `expect-log`), and `expect updates 46` before and
  after: reading takes no frame.
- Existing ports: re-ran all scripts after the Clock and noise changes.
  Every `clock.count` rose by 1 (60 frames now 59 steps after the dt-0
  first tick, not 58) and the positions with it; flow_field's values
  changed with the noise. Only values (and three comments that explained
  the old 58/59 offset) were changed, in 10 ports' scripts. The walkers'
  scripts (noise_walker.reload, random_walk) shifted the same way, one step;
  render-features, who rewrote the walkers this phase, updated them, and the
  new counts are the correct ones.
- All pass at the end: `zig build test` in lib/sketchbook, `zig build e2e`
  in sketches/noc (all examples, the other agents' included), and the
  game's `zig build test e2e`.

## Left

- `diff` in scripts still costs a frame (the game's console.script relies
  on it); `print` covers reading.
- `formatPath` prints memory order; declaration order would need the
  layout to keep it per struct.
- Koch generation 8's segments (0.1 px) are shorter than the 2 px stroke,
  so most joins are the stroker's documented overlapping case: invisible
  in opaque black, would double-blend if translucent on native.
- A Pen-level `strokePath` with dashes, and arcs/ellipses (no example
  needs them yet).
- `Derived` keys are u64: a sketch deriving from many fields hashes them
  itself (`std.hash.Wyhash` over the values, not over padded bytes).