diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-16 21:28:20 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-16 21:28:20 -0300 |
| commit | 6933f99ddb2d7103515d26838496309a807bba26 (patch) | |
| tree | 991c2fe7d4a57957222876e190fa4d16a0fb889c /examples/noc/notes/impl-core-host.md | |
| parent | 82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff) | |
| download | sketchbook-6933f99ddb2d7103515d26838496309a807bba26.tar.gz sketchbook-6933f99ddb2d7103515d26838496309a807bba26.zip | |
Move standalone sketches into sketchbook examples
Diffstat (limited to 'examples/noc/notes/impl-core-host.md')
| -rw-r--r-- | examples/noc/notes/impl-core-host.md | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/examples/noc/notes/impl-core-host.md b/examples/noc/notes/impl-core-host.md new file mode 100644 index 0000000..b83ae8a --- /dev/null +++ b/examples/noc/notes/impl-core-host.md @@ -0,0 +1,166 @@ +# Iteration 1, host half (core-host) + +Design.md section A, items 9 and 10 (host side), and the owner's +"Acceptance: timeline" script support. Paths below are relative to +`lib/sketchbook/` unless they start with `sketches/`. + +## What changed + +**One `update` per frame** (src/host/Host.zig, timeline.zig). +- A frame is the events up to and including a `tick`. `Host.update` cuts + whatever it is given (`timeline.frames`) and calls the sketch once per + frame; events after the last tick are never fed. +- `Timeline.tick` (playback), `seekCount`, `seekTime` and `step` only ever + stop between frames. `step N` now moves N *frames* (it used to move N + input events, skipping ticks); `seek <ms>` lands on the last frame whose + tick is due. +- `in.now`/`in.dt` in `update` come from the frame's tick: `now` is the + tick's time, `dt` is `Event.tickDt()` (the tick's f32 seconds, rounded to + ns). Live uses the same path, so live and replay give the same bits (E4). + While recording, the frame is captured *before* `update`, and capture + rewrites the times to recorded ones, so live update sees exactly the + bytes a replay will (consequence: `in.now` in `update` restarts near 0 + when recording starts; nothing in the game or the ports reads it there). +- Input reset (E2): any snapshot restore (`play`, `seek`, `step`, console + `load`, `record`) sets `Timeline.restored`; `Host.runLine` then clears + `mouse_*`, `buttons`, `keys`. On `record`, the input held before the + reset is prepended to the first frame as events: a `mouse_move` (if the + pointer is not at 0,0), a `mouse_down` per held button, a `key_down` per + held key. The recording format is unchanged; a sketch sees those events + once, when recording starts. +- `abi.Event.tick(time, dt)` / `tickDt()`; the web host uses them too + (src/sketch/web.zig `frame`), so `in.dt` agrees on both hosts. + +**Inspection** (src/layout.zig, memory.zig, fields.zig, script.zig, +Console.zig, probe.zig, overlay.zig, web.zig). +- `layout.flatten` makes arrays and byte-sized-lane vectors into element + leaves with `[]` in the path, one leaf per element *field*, not per + element: `boids.buffer[].pos[]` with `dims = {(64, 24), (2, 4)}` (count, + stride, outermost first; `abi.Field.rank/dims`). Each array also stays as + a whole leaf (kind `array`) for migration. + Decision: indices are resolved at lookup (`abi.layout.match/resolve`, + `Layout.find`), not stored. Storing every element would put e.g. the + game's `tracker.songs` (8 songs x 16 patterns x 16 rows x 4 notes x 2 + fields = 16k leaves) into a 64 KiB header and slow every lookup; strided + leaves cost one row per field of the element type. +- Syntax is the Zig one: `pos[0]`, `boids.buffer[3].pos[1]`, `grid[2][1]`. + `get`/`set`/`expect`/`await`/`sk_field`/`sk_tag` all accept it. Vectors + of bool or odd-width ints stay one opaque leaf. +- `memory.compare` (behind `Bank.compare`, console `diff`, + `expect-snapshot`) compares leaf by leaf, element by element, so padding + never differs (E3). `diff` names the first differing leaf. +- `expect F V ~T` / `await F V ~T`: numeric comparison within T. The field + is looked up again every frame, so it works across a `load`. + +**Migration** (memory.zig). +- Element-wise: for every new leaf with an old leaf of the same pattern + path, the index tuples both have (min count per dimension) are copied: + bytes when the element type hash is equal, enums by tag name otherwise. + Shrink drops the tail, growth keeps the new defaults, scalar arrays keep + their common prefix, `[2]f32` <-> `@Vector(2, f32)` carry over lane by + lane. An array whose whole type is unchanged is copied in one piece and + its element leaves skipped. +- `List` clamp: agreed with draw-layer that `sk.List` accessors clamp `len` + to the capacity; migration keeps `len` as it was. +- File format: `SKETCH02` (StoredField grows to 40 bytes with `rank` and a + `dims` offset into the string table). `SKETCH01` files are read: their + arrays are whole leaves, which migrate whenever the array type is + unchanged (so `tracker.songs` survives). An unchanged layout on a v1 + file just rewrites the header. Any other file is refused with + `NotAStateFile` / `CorruptStateFile`, untouched (E11). The store's + layout header follows the same scheme (`SKSTORE2`, reads `SKSTORE1`); a + `.store` that is not a store is refused unless `--fresh`. +- Checked by hand on a copy of `drat-meout.state` with today's game: "kept + 72 fields, reset 4" (4 fields added since the file was written), songs + byte-identical, probe prints `tracker.songs[].bpm [8] ... 156 168`. + +**Recording stamp** (timeline.zig, Host.zig, Console.zig). `Host.build` is +a hash of the library file (or `/proc/self/exe` when linked), recomputed on +each load; `record` stores it in `Recording.reserved` (old recordings read +as 0, unknown, no warning); `play` (and a seek/step that starts playback) +logs "Warning: recorded by another build of the sketch; the replay may +differ." A hash of the file, so a draw-only edit also warns: it is a +warning. + +**Harness** (root.zig, Host.zig, build.zig). +- Scripted `--fresh` runs work on `<state>.<pid>` (+ `.inputs`, `.store`), + renamed to the given `--state` at exit. Two `zig build e2e` at once share + the Run step's output path, which caused "store is open in another + process". Verified: two concurrent noc `e2e` builds pass. +- Segfault: `Host.init` registered the renderer's `errdefer` before the GPU + device's, so on an error (store busy) the device was destroyed first and + `SDL_DestroyRenderer` used it. Swapped; the store-busy path now exits + with `StoreInUse`. +- `LeakedSdlMemory` under parallel e2e: not ours. Every leak trace is + `VULKAN_INTERNAL_AllocateMemory` (SDL 3.4.18, SDL_gpu_vulkan.c ~1866): + when `vkAllocateMemory` fails it frees `freeRegions` and the allocation + but not `usedRegions` and `memoryLock`, then falls back to another memory + type and carries on. With 12+ headless Vulkan devices, some heap runs out + and the fallback path runs. Fix: build.zig compiles that file from a copy + with the two frees added (`fixSdlVulkanAllocationLeak`, via draw-layer's + `tools/reload_edit.zig`). Before: 3 of 3 parallel noc runs failed; after: + 6 of 6 passed (incl. two concurrent builds, 24 processes). Worth sending + upstream. + +**Script commands** (script.zig): `expect-snapshot N` (prints up to 5 +differing leaves with both values), `expect-log`/`expect-no-log TEXT`, +`expect-same-screenshot A B [MAX [X Y W H]]`, +`expect-different-screenshot A B [X Y W H]`, `expect-pixel FILE X Y R G B +A [TOL]` (the last three also for draw-layer's reload checks). + +## Timeline template + +`sketches/noc/test/accel_to_mouse.timeline.script`, wired into noc's `e2e` +through the `timelines` list in `sketches/noc/build.zig`. It records +pointer input, then checks play-to-end, pause, seek end, seek middle and +play on, step from the start and back and forth, replay after a live move +(each `expect-snapshot 2`), and play-end vs seek-end screenshots. With +`Host.update` temporarily switched back to one call per batch it fails +(`position[0]: live 327.02, snapshot 2 340.14`); with the fix it passes. + +## Tests + +- layout.zig: element leaves and dims; vector lanes and nested array + elements resolve by index, out-of-range and malformed paths do not. +- fields.zig: get/set/match through indexed paths (lanes, struct + elements, enums). +- memory.zig: element-wise migration (field added to an element, enum per + element by name, shrink, regrow, scalar prefix, `[2]f32` to `@Vector`, + `[2][3]` to `[3][2]`); `[8]Song` gaining a field keeps every song; + unchanged arrays copy whole; leaf-wise compare ignores every padding byte + and names `list[1].d`; a non-state file (short and long) is refused and + left byte-identical; `test/fixtures/drat-meout-v1.state-fixture` (a copy + of the game's file) reopens with every byte, gets a v2 header, then + migrates to a changed layout keeping every other leaf. +- timeline.zig: playback at 1 ms steps never yields a partial frame; + seek-time between input and tick, seek end, step back/forward land on + frame boundaries; a cut-off trailing frame is never fed; the stamp is + stored; live and recorded ticks give the same dt (E4 values). +- test/replay.script (new `zig build test` step, sketch test/replay.zig): + button held before `record` (seeded), shift held mid-recording, clicks, + pointer chasing; `expect` with indices and `~`; then play to end, pause, + seek end, seek start + step 1000, step -7/+7, seek 200 + play on, `diff`, + and replay after a live move and press, each `expect-snapshot 2`. The + sum of `in.dt` is in State, so live dt == replayed dt is checked too. +- test/reload.script: recording made by v1 plays without the warning; + after `load {v2}` the same recording warns; `expect streak 7 ~0.5` right + after the load. +- Passing: `zig build test` (lib/sketchbook), the game's `zig build test + e2e`, `sketches/noc` and `sketches/shaders` `zig build e2e` (parallel, + several times). No noc script needed new expected values. + +## Deferred / notes + +- Migration does not clamp a `List`'s `len` (the host does not know + which field is a count); `get boids.len` can read more than the + capacity after a shrink. A `pub const sketchbook_list = true` marker + would let it; not needed while accessors clamp. +- v1 files: an array whose element type changed resets (v1 headers do not + describe elements). After the first write everything is element-wise. +- Seeded record-start events are visible to the sketch (a held button + arrives as a `mouse_down` on the first recorded frame). +- Fields no event carries (`width`, `window_*`, `console`, `frame`) still + reach `update` and do not replay; documented in the README, not narrowed. +- The memory overlay lists arrays as wholes (`<N bytes>`), not elements. +- The build stamp hashes the whole file; a narrower identity (State + layout + `update`'s code) would avoid warnings on draw-only edits. |
