summaryrefslogtreecommitdiff
path: root/examples/noc/notes/impl-core-host.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
committerGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
commit6933f99ddb2d7103515d26838496309a807bba26 (patch)
tree991c2fe7d4a57957222876e190fa4d16a0fb889c /examples/noc/notes/impl-core-host.md
parent82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff)
downloadsketchbook-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.md166
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.