diff options
| -rw-r--r-- | README.md | 104 | ||||
| -rw-r--r-- | src/host/root.zig | 6 |
2 files changed, 80 insertions, 30 deletions
@@ -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"; |
