summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 00:45:31 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commite699ffe4182f66e28180ea2d91ab1fb8c408d49e (patch)
tree0577374fb6164ef214cd727b662a23498ad547eb /README.md
parenta1ae80096bd69ee7d92ea9e4564e960d8553395e (diff)
downloadsketchbook-e699ffe4182f66e28180ea2d91ab1fb8c408d49e.tar.gz
sketchbook-e699ffe4182f66e28180ea2d91ab1fb8c408d49e.zip
Delete the Store; State is checked against the 64 MiB a save holds
A sketch's data is State: flat bytes, what grows has its capacity in its type. The Store, a heap in a file mapped at 0x2000_0000_0000 with 64 GiB reserved, its power-of-two allocator, its root adopt and migration, and its test, are gone from memory.zig; so are Context.store and store_root, Info.store, Memory.store, the Store declaration's glue, Init.store, Frame.store and Console.store, the web host's store in wasm memory, the host's StoreFile wiring and `<state>.store` file, the `.store` suffix in moving an old state into .sketchbook/, the build's tests' `rm` of it, and layout.check's `pointers` flag (State is the one checked memory now). Its one real user, micscope, moved off it in the change before. Old `.state.store` files are not read, converted or deleted, and stay ignored by .gitignore. A sketch that still declares a Store gets no error for the declaration: nothing reads it, and a `*Store` parameter is a compile error (no argument of that type). layout.of(T, .state) refuses a State bigger than layout.max_state, 64 MiB, one constant: "State is N bytes, and a save holds at most 64 MiB: lower a capacity (an array, an sk.List), or keep what need not be saved in Session." The pointer-hash gap the spec found (a Store pointer's element type changing kept the old bytes) is gone with the only persisted memory that held pointers. README: no Store row, allocator row, migration paragraph, file bullet or known limits; draw and command lose their store parameter; State's row says 64 MiB at most; data that grows and is the user's work goes in a List in State or, bigger than a save, in files the sketch appends to. Tests: zig build test, 166/166 steps (the store's unit test gone; new: a 65-MiB State fails to compile with the message above, by expect_errors). micscope, spheres, noc's e2e and drat-meout's test unchanged and green. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'README.md')
-rw-r--r--README.md55
1 files changed, 21 insertions, 34 deletions
diff --git a/README.md b/README.md
index 5b262d3..7691d85 100644
--- a/README.md
+++ b/README.md
@@ -44,24 +44,23 @@ 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 and no host handles (compile errors). |
+| `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). |
| `Session` | This process: survives reloads, never saved. Caches, image and buffer handles, playback cursors. |
-| `Store` | On disk, at the same address in every run: survives reloads and restarts. Big data that is not replayed (a recording, a document). May point into itself; no host handles. |
| `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 |
| `update(state, input)` | **Deterministic**: the host replays recorded input through it |
-| `draw(state, session, store, frame)` | Pictures and sound, as commands; may change Session and Store |
-| `command(state, session, store, console, line) !bool` | Console lines the host does not know |
+| `draw(state, session, frame)` | Pictures and sound, as commands; may change Session |
+| `command(state, session, console, line) !bool` | Console lines the host does not know |
| `commands` | Console completions |
Functions take the parameters they name, matched by type and in any order:
-`draw(s: *const State, f: *sk.Frame)` and `draw(s: *const State, store:
-*Store, ss: *Session, f: *sk.Frame)` both work. `update` can only ask for
+`draw(s: *const State, f: *sk.Frame)` and `draw(f: *sk.Frame, ss: *Session,
+s: *const State)` both work. `update` can only ask for
`State` and `Input`; asking for more is a compile error, since a replay could
not reproduce it.
-`setup` receives `*sk.Init` with `host`, `session`, and `store` allocators;
-it may also request Session, Store, or Host directly. It gets no State, Input,
+`setup` receives `*sk.Init` with `host` and the `session` allocator; it may
+also request Session or Host directly. It gets no State, Input,
or Frame. Load assets and create/upload GPU buffers there, then use those
resources in `draw`. `try init.host.writeBuffer(buffer, offset, bytes)` submits
a copy immediately; the source bytes may be released when it returns. WebGPU
@@ -82,14 +81,11 @@ Memory comes by lifetime, one allocator each:
| --- | --- | --- |
| `f.scratch` | this frame | all at once, after the frame is drawn |
| `f.session` | this process | one allocation at a time; the rest when Session's layout changes, along with the images and buffers the session made |
-| `f.store` | on disk, `<state>.store` | one allocation at a time; `--fresh` empties it |
-A Store layout change migrates field by field like State: unchanged fields,
-pointers included, keep their values, since the store never moves.
-`command` gets the session and store allocators on its `Console`.
+`command` gets the session allocator on its `Console`.
-`update` sees only State, so when a key should do something to Session or
-Store, State carries a request: `seek: sk.Request(f32)`, sent with
+`update` sees only State, so when a key should do something to Session,
+State carries a request: `seek: sk.Request(f32)`, sent with
`s.seek.send(0.5)`. Session keeps an `sk.Handled`, and `draw` runs
`if (ss.seek.take(s.seek)) |to| ...` once per request. A fresh Session
counts earlier requests as handled, so nothing re-fires after a restart.
@@ -131,7 +127,7 @@ State.
`decodeSound`, `newSound`, `samples`, `readFile`, `appendFile`, `env`, `log`, `textSize`). Commands may be built
from locals: the methods copy what they keep (text, GPU descriptions,
uniforms) into scratch. Bulk data (vertices, samples, pixels, uploads) is
-not copied and must outlive the frame: scratch, session or store memory.
+not copied and must outlive the frame: scratch or session memory.
`f.text(x, y, scale, bytes, color)` draws one line from its top left
corner; scale 1 is a 13 px monospace face (8 px a character on a 16 px
@@ -168,8 +164,8 @@ move. The web host ignores `raster`.
dialog; the answer comes back as the console line `open <path>`, so it
reaches the sketch's `command` like anything typed there. `f.run(line)`
does the same with any line, after the frame: `draw` cannot write State,
-so this is how it tells State something only it learns (how many takes a
-Store holds, say).
+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
@@ -375,9 +371,8 @@ 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. Store is not
-kept in keyframes or replayed, so what is in it does not follow a seek. Three
-cases, by who needs the data:
+it holds what `update` changes, at a size fixed in its type, 64 MiB at most.
+Three cases, by who needs the data:
- `update` needs it: a `List` in State, sized for the worst case (the
quadtree's 4096 points, 32 KiB; flocking's 2048 boids).
@@ -391,7 +386,8 @@ cases, by who needs the data:
may derive it differently. A cheap derivation needs no cache at all:
the quadtree builds its tree in `f.scratch` every frame.
- It is the user's work, not a function of State (a recording, a
- document): Store.
+ document): a `List` in State, or, bigger than a save, files of the
+ sketch's own (`appendFile`), named from State, as micscope's takes are.
The timeline then needs nothing more: a seek changes the key like an
update does (`examples/noc`: `koch`, `lsystem`, `quadtree`).
@@ -781,17 +777,12 @@ a talk with a slider, a loop, a choice, two slides and `beside`.
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.
-- **Store file.** `<name>.state.store` is a heap mapped at a fixed address
- (`0x2000_0000_0000`, 64 GiB reserved), grown in place, locked to one
- process. Power-of-two size classes with free lists in the file.
- Keyframes, marks and replays do not cover it (only `draw` and `command`
- change it).
- **Where files go.** `zig build run`, `probe` and `export` keep a sketch's
- files in `.sketchbook/`: `<name>.state`, `<name>.state.store` and
- `<name>.xitdb`. The host makes the directory with a `.gitignore` of `*`,
+ 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 and store an older build kept in the project's root;
+ 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
@@ -1103,17 +1094,13 @@ Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
`f.openFile` answers with a line of any length.
- Every upload, compute dispatch and GPU pass is its own command buffer and
submit. Fine at a handful per frame; batch them per frame if that grows.
-- The store is not crash-safe: a crash in the middle of an allocation can
- leave it inconsistent, and `--fresh` starts it over.
-- Handles inside Store containers (`std.ArrayList(sk.Image)`) are not caught
- at compile time: the check does not follow pointers.
- Native antialiasing resolves coverage per sample within a run of
shapes, the canvas per shape, so where two shapes' edges meet the web
can show a faint seam native does not. `fill` rects and images are
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.
-- On the web: nothing persists (Store lasts as long as the page) and no
+- 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
`newSound`), and so are groups' gains; `decodeSound` gives `.none`, and