summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 01:32:18 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit62ab82af9da007a8ff04677943809cf541b1e420 (patch)
tree9e0da7051fcf606860ada1d2202f14a768d21182
parent8bf10e316178755b8710e27c807dbf9b6a1d37a8 (diff)
downloadsketchbook-62ab82af9da007a8ff04677943809cf541b1e420.tar.gz
sketchbook-62ab82af9da007a8ff04677943809cf541b1e420.zip
README: one thing a sketch keeps, in one file; what a crash loses; the cap
The manual described a mapped state file, a sessions database beside it, a probe, private files for scripted runs and exits that compact past 64 MiB. Now, in The host: "The save" replaces "State file" (one thing, State, in one file, `<name>.xitdb`; the present restored and replayed at start; keyframes as pages and what they cost, measured; layout migration as before; an old `<name>.state` imported once and left as it was); "Where files go" lists `<name>.xitdb` and the files a sketch appends to, `--state x.state` and `x.xitdb` naming one save; "Sessions" says every run is one, `record` decides how much history is kept (a build that does not record keeps the present and the marks, the last minute of input at most while it runs, none after), a crash loses under a second and the next run starts from the last committed frame; a new paragraph, "The cap": 64 MiB, State half, history dropped oldest first and the file compacted to three quarters (about 170 ms in Debug), the present, marks and clips never dropped, a new mark refused with how to make room. The State row and "Data that grows" say 32 MiB; the appendFile paragraph names `<stem>.<name>` beside the save; scripts and exports save nothing; the Build API loses `probe`, `addProbe` and `probe_exe`; Known limits gains the hash pass's cost. layout.zig's note on what State may hold says where it is saved; micscope's README names its takes `micscope.take-<id>.f32`. Tests: zig build test, 168/168 steps. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
-rw-r--r--README.md146
-rw-r--r--examples/micscope/README.md2
-rw-r--r--src/layout.zig7
3 files changed, 92 insertions, 63 deletions
diff --git a/README.md b/README.md
index b59c3a3..9665fc1 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ An app is an ordinary module. Every declaration is optional:
| Declaration | Meaning |
| --- | --- |
| `name`, `width`, `height` | Window title and initial canvas |
-| `State` | Saved to a file, kept in every session's keyframes and marks, replayed: what `update` changes. No pointers, no host handles, and at most 64 MiB (compile errors). |
+| `State` | The one thing a sketch keeps: what `update` changes, saved in one file with its history, replayed. No pointers, no host handles, and at most 32 MiB, half of a save (compile errors). |
| `Session` | This process: survives reloads, never saved. Caches, image and buffer handles, playback cursors. |
| `init(state, host)` | Seed brand-new state, after the declared defaults |
| `setup(session, init) !void` | Initialize resources once per fresh Session, including startup with restored State |
@@ -168,8 +168,8 @@ so this is how it tells State something only it learns (which of its
files are already written, say).
`f.host.appendFile(name, bytes)` appends to a file of the sketch's own,
-`<state>.<name>` beside its state file (in `.sketchbook/` under `zig build
-run`), creating it, and returns its path for `readFile` ("" when nothing
+`<stem>.<name>` beside its save `<stem>.xitdb` (in `.sketchbook/` under
+`zig build run`), creating it, and returns its path for `readFile` ("" when nothing
was written, and always on the web). Only `draw` and `command` can call it,
and a write is not replayed, like sound. `readFile` maps a file once, so
what is appended afterwards is not in what it returned.
@@ -373,7 +373,7 @@ after a reload that shrinks it. The default buffer is the element's own
defaults, never `std.mem.zeroes` (an enum may have no 0).
**Data that grows.** State is kept in keyframes, replayed and migrated, so
-it holds what `update` changes, at a size fixed in its type, 64 MiB at most.
+it holds what `update` changes, at a size fixed in its type, 32 MiB at most.
Three cases, by who needs the data:
- `update` needs it: a `List` in State, sized for the worst case (the
@@ -766,32 +766,40 @@ a talk with a slider, a loop, a choice, two slides and `beside`.
and shaders), and a save that touches several files may build more than
once. The cache grows with each start of the watch (65 MB for a game),
not with edits.
-- **State file.** `<name>.state` holds the live State, shared via
- `MAP_SHARED`, so the file is up to date as it changes. Its header carries
- the reflected layout, so a layout change migrates it field by field, with
- enums matched by tag name, and `sketchbook-probe` can print any sketch's
- state. Arrays and vectors migrate element by element: the elements both
- layouts have, each field by field, so an element type can gain a field
- and a capacity can grow (new elements take their defaults) or shrink (the
- rest is dropped; a count field such as `sk.List`'s `len` is kept, and
- `List` clamps it where it is read). An array whose type is unchanged is
- copied whole. Files from before element leaves (`SKETCH01`) are read and
- rewritten, and the snapshot slots of files from before sessions become
- marks `1` to `7` in a run that records; a file that is not a state file
- is refused, never truncated.
-- **Where files go.** `zig build run`, `probe` and `export` keep a sketch's
- files in `.sketchbook/`: `<name>.state`, `<name>.xitdb` and the
- `<name>.state.<file>` it appends to. The host makes the directory with a `.gitignore` of `*`,
- so neither git nor jj takes in a database that grows (the jj snapshot a
- build makes would commit one while it is under a megabyte), and moves in,
- once, the state an older build kept in the project's root;
- when both exist, nothing moves and the host says which is used. Without
- `--state`, a run keeps them in `$XDG_DATA_HOME/<name>/`
- (`~/.local/share/<name>/` without it), which is where a shipped game's
- go; a script or an export uses `sketch.state` in the working directory.
-- **Sessions.** Every run of a build that records is a session in
- `<name>.xitdb`, one xitdb database per sketch beside its state file: an
- append-only log of the events live `update` was fed, in whole frames, and
+- **The save.** A sketch keeps one thing, State, in one file, its save:
+ `<name>.xitdb`, an xitdb database. Live State is process memory; the save
+ holds the present, its newest keyframe and the frames logged after it,
+ which a run restores and replays through `update` (played by another
+ build, the keyframe alone, and the run says how many frames it left),
+ so a run starts where the last stopped; and the history before it
+ (Sessions, below). `--fresh` starts from defaults and leaves the save as
+ it is. A keyframe is State in 4 KiB pages and writes only the pages that
+ changed since the keyframe before it, an all-zero page nothing: about 5
+ KB a keyframe for drat-meout's 20 KiB State, 10 KB for a 4 MiB State
+ edited once a minute. Each stretch carries the reflected layout, so a
+ keyframe from an older layout migrates field by field, with enums
+ matched by tag name, and so does live State at a reload. Arrays and
+ vectors migrate element by element: the elements both layouts have, each
+ field by field, so an element type can gain a field and a capacity can
+ grow (new elements take their defaults) or shrink (the rest is dropped; a
+ count field such as `sk.List`'s `len` is kept, and `List` clamps it where
+ it is read). An array whose type is unchanged is copied whole. A state
+ file from before (`<name>.state` beside the save, any of its formats) is
+ imported into a new save once: its State the present, its snapshot slots
+ marks `1` to `7`; the file is left as it was and not read again, and one
+ that is not a state file is said and left.
+- **Where files go.** `zig build run` and `export` keep a sketch's files in
+ `.sketchbook/`: `<name>.xitdb` and the `<name>.<file>` it appends to. The
+ host makes the directory with a `.gitignore` of `*`, so neither git nor
+ jj takes in a save that grows (the jj snapshot a build makes would commit
+ one while it is under a megabyte), and moves in, once, the `<name>.state`
+ an older build kept in the project's root; when both exist, nothing moves
+ and the host says which is used. Without `--state`, a run keeps them in
+ `$XDG_DATA_HOME/<name>/` (`~/.local/share/<name>/` without it), which is
+ where a shipped game's go; a script or an export uses `sketch.xitdb` in
+ the working directory. `--state x.xitdb` and `--state x.state` both name
+ the save `x.xitdb`.
+- **Sessions.** Every run is a session in the save: an append-only log of the events live `update` was fed, in whole frames, and
keyframes, the State at the start, every minute while it changes, at
every jump (`load`, `set`, `reset`, a seek, a sketch command), before and
after a reload, at every mark and at exit. Each stretch of a session
@@ -799,34 +807,53 @@ a talk with a slider, a loop, a choice, two slides and `beside`.
was built from: the repository's revision (`jj:<commit> <change>`, else
`git:<sha>`, `+dirty` with uncommitted changes, read once per `zig
build`), Zig's version, the backend and the mode. Nothing in it is ever
- overwritten; marks and clips are names pointing into it.
+ overwritten, only dropped, oldest first, at the cap (below); marks and
+ clips are names pointing into it.
- `App.Options.record` decides who records, at build time: null, the
- default, means Debug builds. A playtest build of a release opts in with
- one line, `.record = b.option(bool, "record", "collect sessions in a
- release build")`. A script from `--fresh` state records in memory (time
- travel works, nothing touches the disk; it stops at 256 MiB, ten hours or
- more of play, keeping what it has), a script without `--fresh` to the
- file, an export nothing. A build that does not record has no marks or
- clips, and the console says so. The console's status line ends with
- `rec file`, `rec memory` or `rec off`, and `sessions` says where.
+ `App.Options.record` decides how much of it the save keeps, at build
+ time: null, the default, means Debug builds keep all of it, up to the
+ cap below. A build that does not record keeps the present and the marks
+ (and clips) only: at every keyframe it drops the frames and keyframes
+ before it, and at exit it compacts the file, so while it runs the disk
+ holds at most the last minute of input, and after, none. A playtest
+ build of a release opts in with one line, `.record = b.option(bool,
+ "record", "collect sessions in a release build")`. A script from
+ `--fresh` state records in memory (time travel works, nothing touches
+ the disk; it stops at 256 MiB, ten hours or more of play, keeping what
+ it has), a script without `--fresh` to the file, an export nothing, and
+ an export has no marks or clips, as the console says. The console's
+ status line ends with `rec file`, `rec memory` or `rec off`, and
+ `sessions` says where.
A commit is a second of play (of event time, so a script commits on the
same frames every run), and is made at once for a reload, a mark, a
clip's start or end, an export and exit; only a mark and exit are synced
to disk. A crash (a panic, `kill -9`) loses the frames not yet committed,
- under a second: the session lists as `(crashed)`, and a clip it left
- open ends where the session does. A power loss loses what the kernel had
+ under a second (15 of 255 in the kill test): the next run starts from the
+ last committed frame's State, the session lists as `(crashed)`, and a
+ clip it left open ends where the session does. A power loss loses what the kernel had
not written back (30 s past the last sync, by default); the torn end is
mended at the next start, the file opened at its last whole commit, and
a file still unreadable is renamed to `<path>.broken.<seconds>`, never
- deleted, and a new one begun. Live State is in the state file either way.
+ deleted, and a new one begun.
- A minute of drat-meout's play is 268 KB with the pointer moving every
- frame (16 MB an hour), 164 KB idle (86 KB of ticks, the rest keyframes).
- Every commit leaves the nodes it copied behind, about a kilobyte; a clean
- exit compacts the file once it is past twice what its sessions hold plus
- 64 MiB. Nothing is compressed or forgotten yet.
+ A minute of drat-meout's play was 268 KB with the pointer moving every
+ frame (16 MB an hour), 164 KB idle (86 KB of ticks, the rest keyframes,
+ then whole States; a keyframe is about 5 KB now).
+
+ **The cap.** A save is at most 64 MiB, and State half of that, so
+ history has room. A commit that leaves the file past it drops history
+ oldest first, keyframes' pages and the frames logged with them, and
+ compacts the file to three quarters of the cap: a hitch of about 170 ms
+ for a 48 MiB file in a Debug build, once every 16 MiB of history. The
+ present is never dropped, nor the keyframe of the newest mark of each
+ name, nor the newest clip of each name and its frames. What was dropped
+ says so when it is asked for (`load #K`, `play session N`). A mark of a
+ new name needs room for a whole State: when marks fill the save it is
+ refused, saying how to make room, by saving over a mark's name (the
+ older one then goes with history) or starting another save (`--state`).
+ Every commit leaves the nodes it copied behind, about a kilobyte, which
+ the compaction removes too.
Playtests: `export-session [S] FILE` writes session S (this run's when
none is given) with its marks and clips to a database of its own, for a
@@ -893,10 +920,9 @@ a talk with a slider, a loop, a choice, two slides and `beside`.
`expect`, or a console line that errors (a sketch command returning an
error included), fails the script. Headless always means offscreen, even
with `SDL_VIDEO_DRIVER` set, and GPU work still runs, into a texture. A
- scripted `--fresh` run works on files of its own (`<state>.<pid>`, and
- `<state>.<pid>.<name>` for those it appends to), renamed to the given
- `--state` at exit, so two builds running the same script at once do not
- share them; its sessions are in memory.
+ scripted `--fresh` run saves nothing: its sessions are in memory, and the
+ files it appends to are `<stem>.<pid>.<name>`, removed at exit, so two
+ builds running the same script at once do not share them.
- **Export.** `--export DIR` plays the sketch headless, from fresh state,
and saves every frame as `DIR/000000.png`, `000001.png`, ...;
`--export -` writes them to stdout instead, as raw RGBA:
@@ -916,8 +942,8 @@ a talk with a slider, a loop, a choice, two slides and `beside`.
hides its controls, plays through and quits. `--size WxH` is the room
for the canvas (`in.window_width`/`height`, and the first canvas): a
sketch that sets its canvas to the room exports at any size. An export
- keeps state files of its own and removes them, so it can run beside a
- player. `--export` plays no script. In a release build on an RTX 3050,
+ saves nothing, and the files it appends to are its own, removed at exit,
+ so it can run beside a player. `--export` plays no script. In a release build on an RTX 3050,
an `anim` scene takes 6 ms a frame as raw RGBA and 21 as PNG at
1920x1080, 19 and 73 at 3840x2160; with ffmpeg encoding x264 from the
pipe, 11 and 41. The PNG encoder is the slow part: pipe, when the frames
@@ -980,7 +1006,7 @@ pub fn build(b: *std.Build) void {
}
```
-`addSteps` installs the executable and adds `run`, `lib`, `probe`,
+`addSteps` installs the executable and adds `run`, `lib`,
`export` (`zig build export -- frames --size 1920x1080`: what follows `--`
is `--export`'s directory, or `-`, then its options), `e2e` and
`test`, and with `.web = .{}` also `web` (the page into `zig-out/web`) and
@@ -999,7 +1025,6 @@ and returns plain `std.Build` objects:
| `app.addRun(lib, .{})` | the generic host running the installed library, its files in `.sketchbook/` |
| `app.addScript(exe_or_lib, file, .{})` | a headless, fresh-state scripted run, of the executable or of the library through the host (so the script can `reload` it) |
| `app.addExport(exe, .{ .fps, .frames, .size })` | a headless export of the executable's frames, as PNGs in `.frames`, a directory of the cache |
-| `app.addProbe(state)` | the probe on a state file |
| `app.addTest(.{})` | tests with the app importable as `app` |
| `app.addReloadCheck(.{ .script, .edits })` | a check that the app hot-reloads with State kept (below) |
@@ -1009,8 +1034,8 @@ for sketches whose per-pixel loops crawl in Debug; null (the default) is
`optimize`. Only Zig code changes mode (the host's and the app's), so it
costs one more compile, not SDL's. A `b.option` makes it a `-D` flag.
-`sb.app(.{ ..., .record = true })` records sessions in every mode (see
-The host); null, the default, records in Debug builds only.
+`sb.app(.{ ..., .record = true })` keeps history in every mode (see
+The host); null, the default, in Debug builds only.
**Hot reload, checked.** `addReloadCheck` builds the app's library as
written, and again from a copy of its sources with textual edits applied,
@@ -1087,7 +1112,7 @@ and Pillow (the renderers against resvg), `ffmpeg` if there is one, and,
for `zig build test-web`, Chrome.
`sb.modules` (`abi`, `sketch`, `host`, `vector`, `scope`, `anim`),
-`sb.host_exe` and `sb.probe_exe` are exposed for anything else.
+`sb.host_exe` is exposed for anything else.
Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
## Known limits
@@ -1102,6 +1127,9 @@ Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
antialiased natively only inside a target. Without a GPU renderer,
native draws aliased. A stroke that overlaps itself blends twice
natively where it overlaps, once on the web.
+- A keyframe hashes all of State to find the pages that changed: about 70
+ ms for 32 MiB in a Debug build, 3 ms in ReleaseFast, once a minute while
+ State changes and at every jump.
- On the web: nothing persists and no
sessions are recorded, and multisampling is 4× at most. Every voice is
silent there, whatever its sound (loaded, decoded or made with
diff --git a/examples/micscope/README.md b/examples/micscope/README.md
index e917bf0..875ebdf 100644
--- a/examples/micscope/README.md
+++ b/examples/micscope/README.md
@@ -149,7 +149,7 @@ browser has accepted its self-signed certificate (miniserve prints the
addresses as QR codes, for phones).
Each take is a file of its samples (mono 32-bit floats at the host's
-rate), `micscope.state.take-<id>.f32` beside the state (in `.sketchbook/`
+rate), `micscope.take-<id>.f32` beside the save (in `.sketchbook/`
under `zig build run`), written as it records (`Host.appendFile`). State
lists the takes, so they are still there after a restart. A take starts
its file empty (`Host.writeFile`). A deleted take's file stays: a seek
diff --git a/src/layout.zig b/src/layout.zig
index b3c6520..c585d71 100644
--- a/src/layout.zig
+++ b/src/layout.zig
@@ -13,9 +13,10 @@
//! against a leaf's pattern at lookup time.
//!
//! What each kind of sketch memory may hold:
-//! - State is saved to disk and snapshotted: no pointers, and no host
-//! handles (images, sounds, buffers), which only mean something in the
-//! process that made them.
+//! - State is saved, the one thing a sketch keeps, in keyframes of its
+//! save: no pointers, and no host handles (images, sounds, buffers),
+//! which only mean something in the process that made them; at most
+//! `max_state` bytes.
//! - Session lives in this process: anything, as long as pointers go into
//! memory the host owns (its heaps, mapped files), never into the sketch
//! library, which a reload unmaps.