summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 02:03:45 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commitd95ee38b80b0260c633612bdd3abb414ddd46a23 (patch)
tree93bd64beac4e489b058d09706e341b26958e8756
parent5c306e3dce3535dee1f6670076d537e05abff0d1 (diff)
downloadsketchbook-d95ee38b80b0260c633612bdd3abb414ddd46a23.tar.gz
sketchbook-d95ee38b80b0260c633612bdd3abb414ddd46a23.zip
README: the 9P controls rewritten around the tree; the Build API's cloud9
"Local 9P controls" was a socket path, plan9port `9p` lines and a poll of status for a screenshot. Now it says what a running sketch is: a tree that describes itself (README, commands, made from the tables), how it is found (posted as sketchbook/<name> by a run in a window, --9p NAME or a socket path), `fs VERB PATH` in every executable and the generic host, answering with the sketch closed from the save or the defaults; a table of the files; how the State maps to files (rows of numbers one file, arrays of arrays and of structs directories, drat-meout's notes as the example; a value read as it was at the open); and an agent driving drat-meout: start it, help, a console line, read state, await by reading in a loop, a live click, one read for a screenshot, a refused write in words, help of one file, quit, and a read with it closed. The ctl paragraph says the 4096-byte write, errors as their names and what each open pins; the trace examples use fs. The console bullet says help VERB and set of an array. The Build API lists sb.modules.cloud9. --help's --9p row and usage line say NAME|/SOCKET and fs. Tests: the session in the manual was run against the drat-meout copy, headless, posted under a scratch runtime directory. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
-rw-r--r--README.md104
-rw-r--r--src/host/root.zig6
2 files changed, 80 insertions, 30 deletions
diff --git a/README.md b/README.md
index 58dae6c..406cd49 100644
--- a/README.md
+++ b/README.md
@@ -965,8 +965,10 @@ a talk with a slider, a loop, a choice, two slides and `beside`.
pointer move, a button or key down), so a replay starts from the same
input whatever the live pointer did since. Event times are the session's:
`in.now` does not restart at 0 in a clip.
-- **Console and overlays.** `get`/`set <field path>` (`get` of a vector,
- array or struct shows its values, in memory order), marks, clips,
+- **Console and overlays.** `help` lists the console's verbs and `help
+ VERB` says what one does. `get`/`set <field path>` (`get` of a vector,
+ array or struct shows its values, in memory order; `set` of an array of
+ numbers takes all its values), marks, clips,
sessions (`marks`, `clips` and `sessions` list the last few) and the
memory, scope and frame timing overlays come from the host; unknown lines
go to the sketch. Paths index arrays and vector lanes: `get pos[0]`,
@@ -1185,8 +1187,9 @@ directory), `typst` for scenes with Typst in them, and for `serve`,
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` is exposed for anything else.
+`sb.modules` (`abi`, `sketch`, `host`, `vector`, `scope`, `anim`, and
+`cloud9`, the 9P library, whose `Fsys` lets an app's tests dial its own
+executable as `fs` does), `sb.host_exe` is exposed for anything else.
Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
## Known limits
@@ -1376,22 +1379,71 @@ the runtime loader. The game repo's `scripts/check_scene.zig` demonstrates both.
### Local 9P controls
-Native hosts accept `--9p /absolute/path/game.sock`. The opt-in Unix socket uses
-cloud9, is owner-only (`0600`), refuses existing paths, and is removed on clean
-exit. Four clients can connect; requests run between frames on the host thread.
-The build uses the sibling `../cloud9` checkout.
+A running sketch is a small file tree, served over 9P by cloud9: its
+State as files, a `ctl` that takes the console's words and a script's
+input, its screen as a PNG. The tree describes itself: `README` has a
+line for every file, every verb under `ctl` and every State file under
+`state/`, made from the same tables the console, scripts and `--help`
+read; `commands` lists the verbs alone, the sketch's own last.
+
+A run a person watches posts its tree as `sketchbook/<name>` (the
+socket `$XDG_RUNTIME_DIR/9p/sketchbook/<name>`, owner-only, removed at
+a clean exit); `--9p NAME` posts it under another name, also headless,
+and `--9p /path.sock` listens at a path instead. Every executable built
+with sketchbook, and the generic host after its LIBRARY, takes `fs VERB
+PATH`: cloud9's verbs (`ls read write ask follow stat help complete`)
+on that tree, the server's refusals printed in its words, exit status 1.
+With the sketch closed, `fs` serves the same tree itself, with no
+window, from the save's newest State (the default save, or `--state`'s),
+else from State's declared defaults: `README`, `commands` and `state/`
+answer, and the rest say the sketch is not running.
+
+```
+ctl write a verb a line: ctl's own (screenshot, profile-reset),
+ a script's input verbs (click, key, type...: routed live,
+ no frame of their own), the console's (set, load, pause,
+ step...); any other line goes to the sketch
+status, log name, canvas, mode, GPU, screenshot state; the console's
+ last five lines
+screen.png the next frame: an open waits for it to be drawn
+README the tree, a line a file; commands: the verbs
+state/ the State: a directory per struct and per array, a file
+ per value (state/tracker/songs/3/bpm); a read is the
+ value as `get` shows it, a write is `set` (a jump)
+sketch/ reserved for the sketch's own files, empty
+```
+
+An array of numbers is one file of its values, blank-separated
+(`state/talk/text`, a vector's lanes), written the same way; an array
+of arrays is a directory of such rows; an array of structs a directory
+of indices, so drat-meout's 8x16x16x4 tracker notes are
+`state/tracker/songs/<n>/patterns/<n>/<n>/<n>/pitch`. Optionals and
+unions read as `<N bytes>` and refuse writes. A value is read as it was
+at the open.
+
+Driving a sketch from an agent, here drat-meout:
```sh
-./zig-out/bin/drat-meout --9p /tmp/drat.sock
-printf 'scene street\nget scene\n' | 9p -a unix!/tmp/drat.sock write ctl
-9p -a unix!/tmp/drat.sock read log
-printf 'screenshot\n' | 9p -a unix!/tmp/drat.sock write ctl
-9p -a unix!/tmp/drat.sock read status
-# Once screenshot_pending is false and screenshot_generation has advanced:
-9p -a unix!/tmp/drat.sock read screen.png > /tmp/street.png
-printf 'quit\n' | 9p -a unix!/tmp/drat.sock write ctl
+drat-meout --headless --9p drat-meout & # or just run it: it posts itself
+drat-meout fs help ctl # the verbs, with their arguments
+drat-meout fs write ctl 'scene street' # a console line, or the sketch's
+drat-meout fs read state/scene # .street
+until [ "$(drat-meout fs read state/street/time | cut -d. -f1)" -ge 3 ]; do :; done
+drat-meout fs write ctl 'click 480 300' # input, live
+drat-meout fs read screen.png > street.png # one read: answered when the frame lands
+drat-meout fs write state/street/camera fast # fs: state/street/camera: InvalidValue
+drat-meout fs help state/street/camera # state/street/camera .placeholder .scene
+drat-meout fs write ctl quit
+drat-meout fs read state/scene # closed: from the save
```
+Scripts stay what tests use (a fixed clock, fresh state, `expect`); the
+tree is live, between real frames, and an agent asserts by reading.
+Anything that speaks 9P works too: `9p -a
+unix!$XDG_RUNTIME_DIR/9p/sketchbook/drat-meout read state/scene`.
+Four clients can connect; requests run between frames on the host
+thread. `zig build test-fs` drives a sketch this way.
+
The native host's `timing` command toggles a scrolling graph with average, p90
and p99 in milliseconds. `timing on|off` sets visibility;
`timing frame|work` selects the graph and shows it; `overlay timing` also toggles.
@@ -1418,7 +1470,7 @@ history, oldest first. `outside_work_ns` is saturating `frame_ns - work_ns`, inc
pacing, polling, presentation and cleanup; it is not a hardware GPU duration. Each
open pins the bounded timing history, so subsequent frames or `timing reset`
cannot change a partially read trace. It works without `--profile-gpu`:
-`9p -a unix!/tmp/drat.sock read timing-trace > timing.csv`.
+`drat-meout fs read timing-trace > timing.csv`.
For compositor/video measurements, launch with `--timing-marker`. This opt-in
marker is drawn last, independently of the timing overlay: 80 black/white cells,
@@ -1458,15 +1510,13 @@ header/tables from the vendored XML and translates the header into Zig bindings;
only the generated protocol tables are compiled as C.
-`ctl` accepts complete console command lines (up to 4096 bytes per write),
-including game commands and host `set`, `get`, `pause`, `step`, `seek`, and `quit`.
-Errors return as 9P errors. `log` exposes the console's latest five lines;
-`status` reports canvas size, playback mode, GPU availability and capture state.
-`screenshot` captures the next rendered canvas as PNG; `screen.png` opens fail
-while capture is pending or failed. Each successful open pins its own snapshot,
-so a later capture cannot change a partially read image. Screenshots include
-visible overlays. `zig build test-control` checks the control boundary and
-snapshot lifetime; the same tests belong to the full host suite.
+`ctl` takes up to 4096 bytes a write; an error returns as the 9P error,
+the error's name (`UnknownField`, `InvalidValue`). Each open of
+`screen.png` (and of the traces, `README` and a State file) pins its own
+copy, so a later frame cannot change a partially read one; screenshots
+include visible overlays. `zig build test-control` checks the control
+boundary and snapshot lifetime; the same tests belong to the full host
+suite.
With `--profile-gpu`, `profile` reports tab-separated `label`, `count`, `mean_ms`,
and `worst_ms`, plus a `# frames N` line. `profile-reset` written to `ctl` resets
@@ -1550,4 +1600,4 @@ ordered oldest to newest within each label; sample numbers start at 1 after
reset. Each open pins the trace even if profiling continues or counters reset.
The render path writes a fixed ring; sorting and CSV generation happen only on
inspection. A trace snapshot is limited to 256 KiB and fails if it exceeds that
-limit. Capture it with `9p -a unix!/tmp/drat.sock read profile-trace > trace.csv`.
+limit. Capture it with `drat-meout fs read profile-trace > trace.csv`.
diff --git a/src/host/root.zig b/src/host/root.zig
index 77fd14e..1edd9a4 100644
--- a/src/host/root.zig
+++ b/src/host/root.zig
@@ -105,7 +105,7 @@ pub fn main(init: std.process.Init, linked: ?abi.Sketch) !void {
/// `main` sets what each one means) and prints `--help`.
const Flag = enum { @"9p", state, headless, script, fresh, @"timing-marker", @"profile-gpu", console, define, @"export", fps, frames, size, help };
const flags = std.enums.EnumArray(Flag, struct { arg: []const u8 = "", doc: []const u8 }).init(.{
- .@"9p" = .{ .arg = "SOCKET", .doc = "local 9P controls: ctl, status, log, screen.png" },
+ .@"9p" = .{ .arg = "NAME|/SOCKET", .doc = "the 9P tree (README, ctl, state/, screen.png...), posted as sketchbook/NAME\n(a run in a window posts its own name), or at a socket path" },
.state = .{ .arg = "FILE", .doc = "the save, one file: FILE, or FILE.xitdb for a FILE.state (where a\nstate file from before is imported from, once); default:\n$XDG_DATA_HOME/<name>/<name>.xitdb, sketch.xitdb for --script, --export" },
.headless = .{ .doc = "offscreen video, silent audio, no vsync" },
.script = .{ .arg = "FILE", .doc = "play a script instead of reading devices" },
@@ -125,11 +125,11 @@ const flags = std.enums.EnumArray(Flag, struct { arg: []const u8 = "", doc: []co
const usage = blk: {
@setEvalBranchQuota(100_000);
const pad: [23]u8 = @splat(' ');
- var text: []const u8 = "usage: sketchbook [options] [LIBRARY]\n";
+ var text: []const u8 = "usage: sketchbook [options] [LIBRARY] [fs VERB [PATH [WORDS...]]]\n";
for (std.enums.values(Flag)) |flag| {
const f = flags.get(flag);
const head = " --" ++ @tagName(flag) ++ (if (f.arg.len > 0) " " ++ f.arg else "");
- text = text ++ head ++ pad[head.len..];
+ text = text ++ head ++ pad[@min(head.len, pad.len)..];
var lines = std.mem.splitScalar(u8, f.doc, '\n');
text = text ++ lines.first() ++ "\n";
while (lines.next()) |more| text = text ++ pad ++ more ++ "\n";