# Friction log, batch B (porter-b) Six Nature of Code examples ported to sketchbook as it stands, to measure the API, not to make nice ports. Each port runs headless under its script (`zig build e2e`), and I compared each screenshot with what the Processing sketch draws. All six match: same canvas, dynamics and look, except for anti-aliasing details. Line counts are code lines only (no blanks or comments). Processing counts every `.pde` file in the example. Port counts are the sketch file only. Everything the ports share lives in `src/helpers_b.zig`: **177 code lines**, and porter-a reuses its Vec ops, Rng and Pen. | sketch | Processing | port | + helpers used | | --- | ---: | ---: | --- | | the_wave | 18 | 36 | Pen, Canvas, frames60 | | pendulum | 70 | 63 | Pen, Canvas, frames60, Vec ops | | system_of_systems | 68 | 73 | Pen, Canvas, frames60, List, Rng | | flow_field | 133 | 110 | Pen, Canvas, frames60, Noise, Rng, Vec ops | | flocking | 165 | 118 | Pen, Canvas, frames60, List, Rng, Vec ops | | wolfram_ca | 38 | 48 | frames60 (draws with `f.fill` only) | The ports are about as long as the originals *once the helpers exist*. The cost is in the helpers (177 lines, the same again in porter-a's file) and in a handful of rules that are easy to get wrong without any error (the "silent traps" below). --- ## Cross-cutting friction (shows up in every port) ### C1. No shapes: circle, line, polygon, stroke, alpha and transforms all go through `vector` `Frame` draws axis-aligned filled rects, images and 8px text, and nothing else. Every Processing primitive these sketches use (`circle`, `line`, `beginShape/vertex/endShape(CLOSE)`, `stroke`, `strokeWeight`, `fill(g, a)`, `push/translate/rotate/pop`) needs the vector module. Getting there takes: 1. A `vector` import in the project's build.zig, which is not there by default (`sb.app(.{ ..., .imports = &.{.{ .name = "vector", .module = sb.modules.vector }} })`). Porter-a and I both made this edit. 2. A `vector.Drawing.Builder` in `f.scratch`, a `vector.Renderer(.cpu|.gpu)` kept in Session and built lazily on first draw, a `Drawing.Style` per shape, then `finish` → `begin` → `draw` → `present` in that order. 3. An error union on every shape call inside a `void` draw. Every port ends up with a `draw` that only calls `paint` and catches its error: ```zig pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void { paint(s, ss, f) catch |err| f.host.print("draw: {t}", .{err}); } ``` What I wrote (helpers_b.zig `Pen` + `Canvas`, ~50 lines) brings a sketch back to Processing's level: ```zig var pen = ss.canvas.begin(f); pen.stroke = b.gray(0, 255); pen.weight = 2; pen.fill = b.gray(127, 127); try pen.circle(x, y, 48); pen.transform = b.Affine.translate(p[0], p[1]).mul(.rotate(b.heading(v))); try pen.polygon(&.{ .{ 8, 0 }, .{ -8, -4 }, .{ -8, 4 } }); try ss.canvas.show(f, &pen, width, height, b.gray(255, 255)); ``` **Wish:** a `sk.Pen`-like value in the sketch library: style fields, an affine, and shape methods that add triangles to scratch. The host should need only one new command (a triangle shape, as research-love and research-zig propose), with no Session renderer and no Builder ceremony. Out-of-memory in scratch should drop the shape and log once, as `f.emit` already does, so shape calls do not return errors. ### C2. Silent trap: `update` gets batches of ticks, but the input state it sees is from the end of the batch When a recording plays or a seek happens, `Timeline.tick`/`seekCount` feed many frames' events to one `update` (Host.zig:229, timeline.zig:148). `in.mouse_x`, `in.buttons`, `in.held()` and `in.pressed()` describe the end of the batch. A port that does Processing's obvious thing: ```zig pub fn update(s: *State, in: *const sk.Input) void { step(s); // once per update call if (s.dragging) s.angle = angleTo(in.mouse_x, in.mouse_y); } ``` works live and in every script, and is wrong after a seek: it steps once for many frames, and every replayed frame sees the final pointer. A correct port loops over events, steps per tick, and keeps its own copy of the pointer and button state in State: ```zig for (in.events) |e| switch (e.kind) { .mouse_move => s.mouse = .{ e.x, e.y }, // pendulum.zig .mouse_down => s.pressed = true, // flocking.zig (mouseDragged) .mouse_up, .cancel => s.pressed = false, .tick => for (0..b.frames60(&s.clock, e)) |_| step(s), else => {}, }; ``` **Wish:** (a) an iterator `in.frames()` that yields each tick with the events that came before it and the pointer and buttons as of that tick, or at least (b) the held buttons on mouse events (`Event` has x/y but no button mask), and `pressed()`/`held()` variants that take an event index. Better still, make the end-of-batch fields unreachable from `update`, the way `update(*Session)` is already a compile error. ### C3. Frame rate: per tick or 60 Hz? Processing calls `draw()` 60 times a second. Stepping once per tick runs the simulation 2.4× faster on a 144 Hz display. I started with one step per tick and then switched to porter-a's idea, a clock in State that accumulates `tick.x` (dt). I wrote it per event (`frames60(clock, e)`) and not per update (`steps60(clock, in)`), so that pointer events still fall between the frames they came between (C2). The first tick has dt = 0, so 60 script frames make 59 steps. Scripts now `expect frames 59`, which reads as a bug until you know why. **Wish:** `sk.Clock` (plain data, in State) with `steps(e) -> u32` at a fixed rate. Also, the first tick should carry a nominal dt, or the scripts should document that it does not. ### C4. Dynamic collections in State A particle system or a flock needs a list whose length changes. State cannot hold pointers, and Zig 0.15+ removed `std.BoundedArray`. I wrote `List(T, cap)` (`items: [cap]T`, `len: u32`, `append` → bool, `orderedRemove`, `slice`/`view`, 25 lines). The costs: - **Capacity is a guess the original never had to make.** Flocking has 2048 boids, and `mouseDragged` silently stops adding past that. System-of-systems has 32 emitters × 136 particles (one particle a frame living 128 frames). `update` cannot log, so a full list cannot say so. - **Size.** In a Debug build `@Vector(2, f32)` is 16 B (research-zig), so a particle is 48 B. The system_of_systems State is 210 KB, and its state file is **1.77 MB** (live + 7 snapshot slots), most of it empty capacity. The flocking state file is 622 KB. A `Vec2 = extern struct { x, y }` would halve these. - **Migration hazard** (verified by research-zig): adding a field to `Particle` resets the whole `items` leaf to its default (`undefined`) and keeps `len`. Shrinking `cap` keeps a `len` larger than the new capacity. So editing the element type during a hot reload leaves garbage particles. Processing has no equivalent, but this is the main promise of hot reload. - Ordered removal while iterating backwards works as in Java (`Emitter.run`), but you have to remember to index rather than iterate a slice, because `orderedRemove` moves the elements after `i`. **Wish:** `sk.Bounded(T, cap)` in the sketch library with `append` → `error.OutOfMemory` (like `ArrayList.appendBounded`), `items()` clamped to `cap`, and swap/ordered remove. Arrays should also migrate element by element (research-zig's spec), so changing the element type during a reload keeps the elements. ### C5. Randomness and noise This one is easier than expected. `std.Random.DefaultPrng` (Xoshiro256) is plain data (`s: [4]u64`), sits in State, migrates, and replays bit for bit. `random(lo, hi)` is one line. But: - A declared default cannot be random, so Processing's `setup()` becomes `pub fn init(s: *State)` (flow_field, flocking). That is fine, but it means a field's default is `undefined` until `init` runs (`vehicles: [120]Vehicle = undefined`). - There is no `noise()`. I wrote a 4-octave value noise in Processing's style (40 lines), with a 16 KB table built from a seed. Only the seed lives in State, and `flow_field` rebuilds the table on each click (`noiseSeed(random(10000))`). Porter-a's is Processing-exact, with the table built at comptime. See the comparison below. **Wish:** `sk.Rng` (pinned algorithm, `float(lo, hi)`, `int`, `normal`) and a pure `sk.noise(seed, x, y, z)` (hash-based, no table, with a GLSL twin). ### C6. Update-then-draw versus Processing's interleaved update-and-show Processing objects update and draw in one pass (`particle.run()` does `update(); show();`), and `draw()` can draw *before* it mutates. Sketchbook runs every update first and then draws from State, so the "same" frame differs by one step in several places: - the_wave: `angle = startAngle; startAngle += 0.02; draw(angle)`. The port draws `s.start_angle - 0.02`. - system_of_systems: the particle added at the end of the frame is not shown until the next frame, and particles are shown newest first, so the port's draw loop starts at `len - 2` and runs backwards. - pendulum: Processing does `update(); show(); drag();`, so a dragged bob is drawn one frame late. The port shows it at once. None of this can be seen at 60 fps, but each one is a small puzzle when you aim for an exact port. No API change is needed. It is worth one paragraph in the README ("draw sees the state after this frame's update"). ### C7. Testing and measuring - `expect` compares formatted text exactly. Floats are therefore unusable (pendulum cannot assert an angle), and `@Vector` fields print as `<16 bytes>`. Arrays cannot be indexed (`emitters.items[0].particles.len`). Every port gained an integer field only so a script could look at it (`frames`, `fields_made`, `generation`) or asserted only on list lengths. - Headless runs discard `host.log` (Host.zig:558), and `update` gets no clock. To time flocking I added a temporary `host.env` check to `draw`, rebuilt, timed whole script runs with `date` and subtracted a baseline run. **Wish:** `expect FIELD ~VALUE ±TOL`, indexed paths, logs on stderr under `--headless` (or `--log`), and per-phase timings (update, draw, present) from the host, like `--profile-gpu`. - `zig build e2e` is flaky under load. A random 2–8 of the 12 runs fail with `LeakedSdlMemory` (SDL Vulkan allocations) and never with a failed `expect`. My scripts passed 6/6 sequentially and 8/8 in a parallel batch. Also, two concurrent `zig build e2e` runs share state paths and break each other (porter-a). ### C8. Small things - `align` is a keyword, so `boid.align(boids)` became `alignment`. - `@Vector` math has no scalar broadcast: `v * @as(Vec, @splat(s))`. I wrote `scale(v, s)`, plus `mag`, `setMag`, `limit`, `normalize`, `heading`, `fromAngle` and `dist` (30 lines). On the other hand, `p.position += p.velocity` works on vectors without helpers, which is nicer than PVector's `add`. - `std.math.lerp(0, height, (@sin(a) + 1) / 2)` stands in for `map()`. - Colours: `vector.Drawing.Color` is straight RGBA in 0..1 (`@Vector(4, f32)`), but `Frame.fill` takes `0xRRGGBB` or `r,g,b` structs. That is two colour vocabularies in one sketch. I wrote `gray(v, a)` in Processing's 0..255 units. --- ## Per example ### the_wave (Example 3.9): 18 → 36 lines - Translucent stroked circles (`fill(127, 127); stroke(0); strokeWeight(2); circle(x, y, 48)`) need C1. With the Pen it is the same four lines. - The draw-before-mutate offset (C6): `var angle = s.start_angle - 0.02;`. - `map(sin(a), -1, 1, 0, height)` became `std.math.lerp(0, height, (@sin(angle) + 1) / 2)`. - The extra lines are module boilerplate: `name`/`width`/`height`, State, Session holding the Canvas, the `draw`/`paint` split (C1), and the 60 Hz loop. - **Wish:** `f.pen()` returning a Pen that draws straight into the frame. ### pendulum (Example 3.11): 70 → 63 lines - Mouse press, release and drag are handled per event, with the pointer copied into State (C2). Processing's `mousePressed()`/`mouseReleased()` callbacks map well onto `switch (e.kind)`, which reads better than Processing's three global callbacks. - `line` and a stroked `circle` need C1. - The hit test needs the bob position. Processing caches it in `show()`. I derive it from the angle (`State.bob()`), so draw and update agree without storing it. - The script can only assert `dragging` (bool), not where the bob went (C7). I checked the swing by looking at the screenshot. - **Wish:** `in.frames()` (C2). With it, the State would not need a `mouse` field. ### system_of_systems (Example 4.4): 68 → 73 lines - This is the dynamic-collection test (C4): `ArrayList` of `ArrayList` became `List(Emitter, 32)` of `List(Particle, 136)`. Shape and code read the same as Java, but the State is 210 KB (1.77 MB on disk with 8 slots), and the 33rd click does nothing, silently. - Per-particle alpha on fill and stroke (`stroke(0, lifespan)`) works through `Drawing.Style` colours. `lifespan` goes negative before removal, so the alpha needs a clamp (in `gray`). - The draw order matches Processing: newest first, and the particle just added is not shown yet (C6). - The script asserts `emitters.len` but cannot reach a particle count (C7). - **Wish:** `sk.Bounded`, migration by element, and a way for `update` to report "capacity reached" (a counter in State works, but it is one more field per list). ### flow_field (Example 5.4): 133 → 110 lines - `noise()` and `noiseSeed()` are missing (C5). The noise table is rebuilt from a seed on each click. - `PVector[][] field` became `[cols][rows]f32` of angles, 2.3 KB, which is pleasant: a 2D array is plain State, and `for (&ff.field) |*column| for (column) |*angle|` reads well. - The vehicles' rotated triangles are where `Pen.transform` shines: `translate(x, y).mul(.rotate(theta))` replaces `push/translate/rotate/pop` with a value, so nothing can be left pushed. - Acceleration lasts a single step in the original (`acc.mult(0)`), so it is a local, not State: `v.velocity = limit(v.velocity + steer, maxspeed)`. - `key == ' '` became `e.kind == .key_down and e.code == @backingInt(sk.Key.space) and e.flags & sk.Event.repeat == 0`. That is correct, but long. `in.pressed(.space)` exists but is per batch (C2). - **Wish:** `e.isPress(.space)` on `Event` (key down, no repeat), `sk.noise`. ### flocking (Example 5.11): 165 → 118 lines - The flock is a `List(Boid, 2048)` (C4). `mouseDragged` means "move events while the button is down", so `pressed` is tracked in State (C2). - Processing updates boids in place, one after another, so later boids see earlier boids' new positions. The port keeps that: `for (boids) |*boid| boid.run(boids)`, where `boids` is the slice being mutated (Zig allows the alias). - **Frame time** (headless, 600 frames at a constant count, minus a ramp-up baseline, on an RTX 3050 shared with other agents' builds, so ±30 %): | boids, build | total / frame | update | draw (CPU vector) | draw (GPU vector, helpers_a `showGpu`) | | --- | ---: | ---: | ---: | ---: | | 120, Debug | ~3–4 ms | — | — | ~8.7 ms total | | 1000, Debug | 37–76 ms | ~18 ms | ~20–58 ms | ~56 ms total | | 1000, ReleaseFast | 8.7–11.6 ms | ~4.6 ms | ~4–7 ms | ~9.1 ms total | Update (O(n²), three neighbour loops) is fine. Drawing 1000 triangles costs as much as the whole simulation, because each one is flattened, stroked into polygons and rasterized one at a time (CPU), or turned into two stencil-and-cover draws (GPU). The 921 KB `f.pixels` upload per frame is small next to that. e2e runs Debug, where 1000 boids is about 15 fps. - **Wish:** a batched triangle command. Boids are 3 vertices each, and a path renderer with exact coverage is the wrong tool for them. ### wolfram_ca (Example 7.1): 38 → 48 lines - The only port that needs nothing beyond `f.fill`: black squares on white. - Processing never clears: `background(255)` runs once in `setup()`, and each `draw()` paints one more row. Sketchbook draws every frame from State, so State keeps the whole history, `[33][64]u1` (2 KB). Here that is *better*. It is small, it replays and seeks for free, and it removes the need for a persistent canvas. (Porter-a's noise_walker shows the case where it is not small.) - `noLoop()` becomes "stop stepping when `generation == max_rows`". It is explicit and fine. - The stroke of `square()` adds half a pixel all round, drawn as a rect inflated by 0.5. A rect API with a stroke would remove that. - The rule lookup through a string (`Integer.parseInt("" + a + b + c, 2)`) became `@as(u3, left) << 2 | @as(u3, me) << 1 | right`, which reads better. - **Wish:** none needed. Optionally `f.stroke(rect, color, width)`. --- ## helpers_a vs helpers_b Porter-a reused my Vec ops, `Rng` and `Pen`, and added `steps60`, an exact `noise()`, `showGpu` and `Trail`. | piece | helpers_a | helpers_b | better, and why | | --- | --- | --- | --- | | frame stepping | `steps60(clock, in) u32`, per update, f64 clock | `frames60(clock, e) u32`, per tick event, f32 clock | **B's shape**, A's idea. Per event, the pointer events in a replayed batch stay between the right frames (C2); per update, they all land before the first frame. Both fix the 144 Hz speed-up. | | noise | Processing-exact: java.util.Random table at comptime, 0 B in State, 3D | Xoshiro table built from a seed in State at call time, 2D, 16 KB per rebuild | **A** for fidelity and cost. **B** only where the seed changes at runtime (flow_field's click). Both lose to a hash noise `noise(seed, x, y, z)`, which needs no table and can have a GLSL twin. | | redrawn layer | `showGpu`: GPU vector renderer (8× MSAA), transparent over `f.clear` | `Canvas`: CPU vector renderer, `f.pixels` upload, background inside | **Neither clearly.** Measured on flocking (table above), the GPU path is no faster: slower in Debug (56 vs ~37 ms at 1000 boids), similar in ReleaseFast (9.1 vs 8.7–11.6 ms total), because tessellation is on the CPU either way and the GPU path issues two draws per shape. The CPU one is simpler, runs anywhere (wasm too: flocking's web build works unchanged), and is pixel-identical here (GPU screenshot = CPU screenshot). GPU MSAA edges look slightly softer. Choosing at runtime means duplicating the call site for two renderer types (vecanim does this). | | persistent layer | `Trail`: CPU renderer never cleared, plus a "steps drawn" counter to repaint after a seek | none (wolfram keeps its history in State instead) | Different problems. State history is right when it is small (wolfram, 2 KB). `Trail` is needed when it is not, and its counter guess is what `Input.jumped` would replace. A GPU trail is impossible today: an MSAA pass always clears (gpu.zig:213). | | bounded list | none (fixed arrays) | `List(T, cap)` | Neither is enough until arrays migrate element by element (C4). | What the two files show together: both porters, working independently, wrote the same ~200 lines (Vec ops, Rng, noise, Pen, a stepping clock). That is the size of the missing layer. --- ## Easier than in Processing - **Determinism for free** once the RNG is in State. The same script gives pixel-identical screenshots run after run, and on CPU and GPU renderers. A seek or a replay re-runs flocking exactly, which Processing cannot do. - **Scripts as tests.** `--fresh` + `click`/`down`/`move`/`key` + `expect` + `screenshot` gave every port a regression test in 5–15 lines. The pendulum drag, the flocking drag-add count and the flow-field toggle are all checked without a window. - **Transforms as values.** `pen.transform = translate(..).mul(.rotate(..))` cannot leak a `push()` without its `pop()`. - **Event switch over callbacks.** `switch (e.kind)` in `update` keeps `mousePressed`/`keyPressed`/`mouseDragged` together, in order, and replayable. - **2D arrays and fixed-size grids** (flow field, CA history) are plain State, inspectable with the probe, and they hot-reload. - **The web build worked unchanged** with the CPU renderer (1 MB wasm). --- ## Ranked: the most impactful gaps across batch B 1. **No shape drawing in `Frame` (C1).** Five of six ports needed the vector module: a build.zig import, a Builder, a Renderer in Session, a `try` on every shape, and an explicit present. ~70 helper lines, and 1000 triangles cost as much as the whole flocking simulation. Wanted: a Pen layer in the sketch library over one triangle-batch command. 2. **Batched ticks with end-of-batch input (C2).** A silent trap: ports that read `in.mouse_x` or step once per `update` pass every live test and every script, and break only on seek or replay. Wanted: `in.frames()` per-tick iteration, buttons on mouse events, and the end-of-batch fields kept out of `update`. 3. **Dynamic collections (C4).** No bounded list type, guessed capacities, silent drops, 1.77 MB state files from empty capacity, and garbage after a reload that changes the element type. Wanted: `sk.Bounded(T, cap)` plus array migration by element. 4. **No fixed-rate clock (C3).** Stepping per tick makes the simulation's speed depend on the display. Both porters wrote the same accumulator. Wanted: `sk.Clock` in State. 5. **Scripts cannot see floats, vectors or array elements, and headless runs hide logs and timings (C7).** Every port grew observability-only fields, and profiling meant external stopwatches. Wanted: tolerant `expect`, indexed paths, stderr logs and per-phase timing. 6. **No random/noise in the library (C5).** The Rng in State works well. Noise is 40–60 lines that every noise sketch rewrites. Wanted: `sk.Rng` and a pure `sk.noise(seed, x, y, z)`. 7. **Vector math vocabulary (C8).** `@Vector` has no scalar broadcast, no `limit`/`setMag`/`heading`, and it is 16 B in Debug State. Wanted: small `sk.v2` functions, and an extern `Vec2` for storage. 8. **Two colour vocabularies (C8).** `0xRRGGBB` for `Frame`, straight 0..1 `@Vector(4, f32)` for `vector`. Wanted: one `sk.Color` that both accept, with Processing-style `gray(v, a)`/`rgb(r, g, b, a)` constructors. Not a gap, but worth documenting: update-then-draw shifts Processing ports by one step in places (C6), and the first tick's dt is 0 (C3).