@looop-games/cli 0.1.35 → 0.1.36

package/CHANGELOG.md

@@ -14,6 +14,17 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.36] - 2026-09-04
+
+### Added
+
+- **`looop dev` keeps the sessions you play.** As you play, the room hands the dev server each slice of the recording and it lands under your game's `.looop/replays/`. Watch one back by adding `?replay=<id>` to the game's URL — the id is printed to the console when the session starts. Nothing leaves your machine, and nothing is kept when the room is not a dev room.
+- **`?replay=last`** — the newest recording, resolved by the dev server, so watching the session you just played does not start with copying an id.
+- **Old recordings are swept, so a game folder stops growing forever.** When `looop dev` starts it keeps the newest **20 recordings** and up to **200 MB** per game, whichever runs out first — roughly an hour of play for a busy game — and removes the oldest past that, saying on the way up how many went. To protect one, hit **keep** on its row in the toolbox's Sessions panel; a kept recording is never swept. (It still counts toward the caps: keeping means "don't delete this", not "don't charge me for it".)
+- **`looop replay export` — a session you played, as a table you can query.** A recording holds what you PRESSED, not what happened: no position, no speed, no score is in it anywhere. So this replays the session through your own game, reads the world at every tick, and writes it down as Parquet — one row per tick per entity, one column per declared field, plus a second table of every input you sent. Running the game costs a few seconds once; every question you ask afterwards is free, in SQL, with DuckDB or pandas or anything else that reads Parquet. Measured on a real 27-second session: 279,367 rows x 443 columns in 10 seconds, 3.9 MB on disk, and a query answered in 0.02 s. Numbers come back bit-for-bit as the simulation held them. `npx looop replay export --help` for the schema, or `shared/docs/replay-export.md`.
+- **`looop replay export` tells you when the table will not be the session you played — before it spends the time building it.** A recording holds what you pressed, not what happened, so the numbers come from running your current code on old inputs. The export now compares the recording against what you are running and says up front if the engine version or the shape of your game has moved since. While it replays it also reports how many keyframes put playback back onto the recorded state, and the divergence warning no longer claims that everything after a divergence is worthless — a drift is bounded to the stretch before the next keyframe, and saying otherwise had people binning tables that were mostly fine.
+- The dev server answers the toolbox's Sessions panel — listing this game's recordings, deleting one, and pinning one. Only ever on the dev server, and deleting or pinning a recording works only from a page this dev server itself served. `looop dev` listens on every network interface so your phone can play, which means everything else on that wifi can reach it too — on a cafe or coworking network that is not a set of machines you control, and nothing there can now remove one of your sessions.
+
 ## [0.1.35] - 2026-09-02
 
 ### Added

package/bin/looop.mjs

@@ -36,6 +36,7 @@ Usage:
   looop update [--rc <v>]    Move this game to the latest engine release (--rc <v> takes a specific pre-release)
   looop model bake <glb>     Re-bake a 3D model's server-side hit data now (normally automatic)
   looop publish [--slug <s>]  Publish this game to play.looop.games (--slug for an A/B copy)
+  looop replay export [<id>]  Turn a recorded session into a table you can query (Parquet)
   looop feedback             Send reports + replies under notes/feedback/; pull outcomes back in
   looop login                Authenticate this machine as your Looop player account
   looop logout               Forget the stored token
@@ -124,6 +125,23 @@ try {
       await bakeModel(glb);
       break;
     }
+    case 'replay': {
+      // `replay` is the accessor for a recorded session; `export` is its first
+      // verb. Watching one back needs no command at all — it is `?replay=<id>`
+      // on the game's URL, or the toolbox's Sessions panel.
+      const { REPLAY_HELP, replayExport, parseReplayArgs } = await import('../lib/replay-cmd.mjs');
+      // Parsed in the lib so the argv split is under test — a flag's value must
+      // never slide into the session slot, and --help must be answered before
+      // anything is read as an id.
+      const { verb, id, out, help } = parseReplayArgs(rest);
+      if (help) {
+        console.log(REPLAY_HELP);
+        break;
+      }
+      if (verb !== 'export') throw new Error(`Unknown replay command: ${verb} — try: looop replay export`);
+      await replayExport({ stream: id, out });
+      break;
+    }
     case 'publish':
       await publish({ slug: flag('slug') });
       break;

package/lib/dev.mjs

@@ -14,6 +14,7 @@ import { join, dirname, basename } from 'node:path';
 import { findProject } from './project.mjs';
 import { ensureEngine } from './engine.mjs';
 import { createStaticServer } from './static-server.mjs';
+import { pruneOnStart } from './replay-store.mjs';
 import { createLlmShim, DEFAULT_API_BASE } from './llm-shim.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { resolvePorts, portInUse, killPort, lanIp, isRestricted, nextBrowserSafe } from './ports.mjs';
@@ -62,6 +63,11 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   const { ensureBaked } = await import('./model-bake.mjs');
   await ensureBaked({ dir: project.dir, log });
 
+  // Recordings accumulate on the creator's own disk — every session played
+  // under `looop dev` writes one — so the oldest go here, before anything can
+  // be watching one. The caps and the keep marker live in replay-store.mjs.
+  pruneOnStart({ projectDir: project.dir, log });
+
   // Which ports, and may we take them? An explicit --port is obeyed as given
   // (takeover included). With no flag we step around anyone else's stack —
   // another lane, another game, an unrelated app — and only ever reclaim our

package/lib/replay-cmd.mjs

@@ -0,0 +1,155 @@
+// `looop replay export` — the recorded session, on disk as a table.
+//
+// This is the CLI's half: find the game, resolve the engine it is pinned to,
+// hand both to the exporter, and then say enough about what came out that the
+// next step is obvious. The table's shape and every decision about it live in
+// replay-export.mjs; nothing here knows what a column is.
+import { join, relative, resolve } from 'node:path';
+import { statSync } from 'node:fs';
+import { findProject } from './project.mjs';
+import { streamDir } from './replay-store.mjs';
+import { ensureEngine } from './engine.mjs';
+import { exportSession } from './replay-export.mjs';
+
+export const EXPORTS_DIR = ['.looop', 'exports'];
+
+export const REPLAY_HELP = `looop replay — work with the sessions this game has recorded
+
+Usage:
+  looop replay export [<session>] [--out <dir>]
+
+  <session>   Which recording. Defaults to the most recent one.
+  --out       Where the tables go. Defaults to .looop/exports/
+
+Writes two Parquet tables:
+
+  <session>.state.parquet    one row per tick per entity, every declared field
+                             a column (def/id/owner/tick lead)
+  <session>.inputs.parquet   one row per input the player sent
+
+A recording holds what was PRESSED, not what happened — so the export replays
+the session through your game to work out where everything was, then writes it
+down. That costs a few seconds once; every question you ask of the table
+afterwards is free.
+
+  duckdb -c "SELECT def, count(*) FROM '.looop/exports/<session>.state.parquet' GROUP BY def"
+`;
+
+/**
+ * Split `looop replay …`'s arguments into the verb, the session, and the flags.
+ *
+ * A flag's VALUE is a positional-looking word, so dropping only the tokens that
+ * start with `--` leaves `tables` from `--out tables` sitting in the session
+ * slot — and the export then reports it cannot find a recording the creator
+ * never named. The same trap is why `--help` has to be answered before any of
+ * this is used as an id.
+ */
+export function parseReplayArgs(argv = []) {
+  const flag = (name) => {
+    const i = argv.indexOf(`--${name}`);
+    return i === -1 ? undefined : argv[i + 1];
+  };
+  const positional = argv.filter((a, i) => !a.startsWith('-') && !argv[i - 1]?.startsWith('--'));
+  const [verb, id] = positional;
+  return {
+    verb,
+    id,
+    out: flag('out'),
+    help: !verb || verb === 'help' || argv.includes('--help') || argv.includes('-h'),
+  };
+}
+
+const mb = (file) => `${(statSync(file).size / 1024 / 1024).toFixed(1)} MB`;
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.stream] - which recording; defaults to the most recent
+ * @param {string} [opts.out] - where the tables go
+ * @param {(msg: string) => void} [opts.log]
+ * @param {(dir: string, o: object) => Promise<object>} [opts.ensureEngineImpl]
+ * @param {(o: object) => Promise<object>} [opts.exportImpl]
+ */
+export async function replayExport({
+  cwd = process.cwd(), stream, out, log = console.log,
+  ensureEngineImpl = ensureEngine, exportImpl = exportSession,
+} = {}) {
+  const project = findProject(cwd);
+  // The id is about to become a path to read from AND a filename to write. Every
+  // other door into the store runs one through `streamDir`, which refuses rather
+  // than sanitizes; this one is no different for being typed by hand.
+  if (stream) streamDir(project.dir, stream);
+  const outDir = out ? resolve(project.dir, out) : join(project.dir, ...EXPORTS_DIR);
+  // The tables are tens of megabytes and this creates directories to hold them.
+  // A path that climbs out of the game folder is a typo, not an intention.
+  if (outDir !== project.dir && !outDir.startsWith(`${resolve(project.dir)}/`)) {
+    throw new Error(`--out must be inside the game folder, and ${out} is not`);
+  }
+  const engine = await ensureEngineImpl(project.dir, { log });
+
+  const started = Date.now();
+  const res = await exportImpl({
+    dir: project.dir, stream, outDir, sharedDir: engine.sharedDir,
+    engineVersion: engine.version, log,
+  });
+  const secs = ((Date.now() - started) / 1000).toFixed(1);
+
+  const rel = (f) => relative(project.dir, f);
+  log(`exported ${res.stream} in ${secs}s`);
+  log(`  ${rel(res.stateFile)}   ${res.rows.toLocaleString()} rows x ${res.columns} columns  (${mb(res.stateFile)})`);
+  log(`  ${rel(res.inputFile)}  ${res.inputs.toLocaleString()} inputs  (${mb(res.inputFile)})`);
+  // Three different ways the table can describe a world that is not the one
+  // that was played. None of them is buried: an export that looks clean and is
+  // not is worse than one that failed, because the answers it gives are wrong
+  // and confident.
+  if (res.divergences) {
+    // What bounds the damage is the keyframe: the stream carries the room's
+    // complete true state roughly every 30 s, and playback restores it, so a
+    // drift owns one keyframe interval rather than everything downstream.
+    // Saying otherwise sends a reader to bin a table that was mostly fine.
+    //
+    // Only a re-anchor AFTER the last divergence says that last drift was
+    // undone; earlier ones belong to earlier drifts. And a re-anchor is recorded
+    // only when the restore actually changed the world, so zero of them does not
+    // mean nothing corrected it — a drift that came right again on its own also
+    // records none. Claiming "the drift ran to the end of the session" from a
+    // zero count states something this code cannot know.
+    const corrected = res.lastReanchorTick != null
+      && res.lastDivergenceTick != null
+      && res.lastReanchorTick > res.lastDivergenceTick;
+    const putBack = corrected
+      ? ` Playback was put back onto the recorded state at tick ${res.lastReanchorTick}, after the last of them.`
+      : ' Nothing is recorded as putting it back after the last one, so treat the rows from there to the end as this run\'s.';
+    log(`  ⚠ the replay parted from the recording ${res.divergences} time(s) — from each of those `
+      + 'ticks until the next keyframe, the rows are this run\'s world rather than the recorded one.'
+      + putBack
+      + ' The usual cause is that the game changed since the session was recorded; a replay runs '
+      + 'the code as it is now.');
+  }
+  if (res.gaps) {
+    log(`  ⚠ the recording is missing ${res.gaps} segment(s) — the inputs in those gaps were never `
+      + 'stored, so the world after each one is not the session that was played');
+  }
+  if (res.unsupported) {
+    log(`  ⚠ ${res.unsupported} recorded event(s) cannot be reproduced by a replay (a live tune, say) `
+      + '— the world after each one is not the session that was played');
+  }
+  // Repeated from before the replay. That is the right place to say it first —
+  // the answer is known and the replay is the slow part — but a big export puts
+  // screens of output in between, so the line deciding whether to trust the
+  // table would be the one line scrolled off. Costs nothing; both values are
+  // already on the result.
+  if (res.recordedEngine && res.runningEngine && res.recordedEngine !== res.runningEngine) {
+    log(`  ⚠ recorded by engine ${res.recordedEngine}, replayed on ${res.runningEngine}`);
+  }
+  if (res.codeChanged) {
+    log('  ⚠ the game has changed since this session was recorded');
+  }
+  if (res.undoubleable) {
+    log(`  note: ${res.undoubleable} numeric cell(s) held NaN or ±Infinity, which Parquet has no double `
+      + 'for, and read as null — the same as a field the entity kind does not declare');
+  }
+  log('');
+  log(`Ask it something:  duckdb -c "SELECT def, count(*) FROM '${rel(res.stateFile)}' GROUP BY def"`);
+  return res;
+}