sindicate 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Sindicate — open-world game engine for three.js WebGPU. Streaming worlds, characters, mounts & vehicles, missions, crowds.",
   "type": "module",
   "main": "src/index.js",
@@ -22,7 +22,8 @@
   ],
   "exports": {
     ".": "./src/index.js",
-    "./*": "./src/*"
+    "./*": "./src/*",
+    "./tools/*": "./tools/*"
   },
   "files": [
     "src",

package/src/audio/music.js

@@ -111,7 +111,7 @@ export class Music {
   _onEnded(t) {
     if (this._cur !== t) return;
     if (t === this.restSleep) return;             // asleep under the black; the wake cut takes over
-    if (t === this.restWake) { this._state = 'area'; this._playArea(this._area || 'desert'); return; }
+    if (t === this.restWake) { this._state = 'area'; this._playArea(this._area || Object.keys(this.areas)[0]); return; }
     if (this._state === 'sting') {
       const fb = this._stingFallback; this._stingFallback = null;
       this._state = 'area'; this._playArea(fb || this._area || this._half);
@@ -126,6 +126,16 @@ export class Music {
     if (this._unlocked) return;
     this._unlocked = true;
     this._ensureCtx();
+    // Pre-decode the catalogue's `resident` list (file names) so combat stings and
+    // exploration cuts start INSTANTLY — everything else decodes on first crossfade.
+    if (this._cat.resident?.length) {
+      const defs = [this.menu, ...this.attack, ...this.venue,
+        ...Object.values(this.areas).flat(), this.restSleep, this.restWake].filter(Boolean);
+      for (const name of this._cat.resident) {
+        const t = defs.find((d) => d.url.endsWith(`/${name}`));
+        if (t) this._decode(t).catch(() => { /* pre-decode is best-effort */ });
+      }
+    }
     if (this.ctx.state === 'suspended') this.ctx.resume().catch(() => {});
   }
 

package/src/core/assets.js

@@ -8,6 +8,11 @@ import { texture, uv } from 'three/tsl';
 // Register BEFORE the first applyAtlas/instantiate call (materials are cached).
 let atlasEmissiveHook = null;
 export function setAtlasEmissiveHook(fn) { atlasEmissiveHook = fn; }
+
+// The cooked-clip cache version tracks each GAME's animation sources (a rebake bumps
+// it), not the engine — register per game: setClipCacheVersion(2). Defaults to 2
+// (western's current rebake generation).
+export function setClipCacheVersion(v) { CLIP_JSON_VER = v; }
 // Patched loader from vendor/ — merges ALL FBX animation layers per stack. The
 // engine does NOT depend on a node_modules postinstall patch.
 import { FBXLoader } from '../vendor/FBXLoader.js';
@@ -532,7 +537,7 @@ export function applyAtlas(root, tex, { emissive = null } = {}) {
 // public/assets/clips/<name>.json on first parse (self-written via /__save-clipjson)
 // and read the JSON on every later boot. Bump CLIP_JSON_VER after changing any source
 // animation (the name alone can't see content changes), or delete the folder.
-const CLIP_JSON_VER = 2; // v2: full-pack gsbake rebake (97 clips, 2026-07-12)
+let CLIP_JSON_VER = 2; // v2: full-pack gsbake rebake (97 clips, 2026-07-12)
 function clipJsonName(url) {
   let h = 5381;
   for (let i = 0; i < url.length; i++) h = ((h << 5) + h + url.charCodeAt(i)) >>> 0;

package/tools/devPlugin.js

@@ -0,0 +1,232 @@
+// sindicateDevTools(config) — the engine's dev-server tooling suite, extracted from the
+// western game's vite config. Returns an array of vite plugins (all `apply: 'serve'` —
+// none of this exists in a production build):
+//
+//   • guarded SOURCE-WRITE endpoints — bench pages persist tuned data straight into the
+//     game's data files (grip/rig/map/LOD... whatever the game declares)
+//   • COOK-TO-FILE stores — the game bakes its own caches (VAT bins, nav grids, parsed
+//     animation clips, world cook bins, map PNGs) and every later boot is a file read.
+//     Each store serves its directory itself: the dirs are excluded from vite's watcher
+//     (writes must not full-reload the page), and vite 8's watcher-fed public registry
+//     404s files created after startup — so we bypass it.
+//   • PERF SINK — [PERF]/FREEZE samples append to a JSONL on disk, readable without the
+//     console (a backgrounded tab pauses rAF and CDP is flaky; disk is neither)
+//   • EDITOR + GAME COMMAND BUSES — queue {js|op} snippets over HTTP; the live page polls,
+//     executes, posts results back. Scripted playtests and editor drives with curl.
+//
+// Usage (a game's vite.config.js):
+//   import { sindicateDevTools } from 'sindicate/tools/devPlugin.js';
+//   plugins: [...sindicateDevTools({
+//     sourceWrites: [{ route: '/__save-grip', file: 'src/game/data/gripTuning.json',
+//                      json: true, mustInclude: 'revolver' }],
+//     assetLists:   [{ route: '/__list-assets', dir: 'public/assets/world', ext: 'fbx' }],
+//     perfSink: process.env.MY_PERF_SINK || '/tmp/mygame-perf.jsonl',
+//   })]
+import fs from 'node:fs';
+
+// Guard for the source-writing endpoints: only same-machine pages may write, and the
+// payload must look like the file it claims to be — an empty/garbage body used to be
+// written verbatim (truncating a committed src file to 0 bytes and breaking the boot via
+// HMR), and cross-origin simple POSTs from any open webpage could reach these routes.
+function guardOk(req, res, body, checks) {
+  const origin = req.headers.origin;
+  if (origin && !/^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) {
+    res.statusCode = 403; res.end('cross-origin write refused'); return false;
+  }
+  if (!body || body.length < 20) { res.statusCode = 400; res.end('empty body refused'); return false; }
+  for (const [label, ok] of checks) {
+    if (!ok) { res.statusCode = 400; res.end(`payload failed check: ${label}`); return false; }
+  }
+  return true;
+}
+
+const readBody = (req) => new Promise((resolve) => {
+  const c = []; req.on('data', (d) => c.push(d)); req.on('end', () => resolve(Buffer.concat(c)));
+});
+const sendJson = (res, code, obj) => {
+  res.statusCode = code; res.setHeader('content-type', 'application/json'); res.end(JSON.stringify(obj));
+};
+
+// One guarded write-through-to-a-source-file endpoint (grip/rig/map/LOD tuners).
+function sourceWritePlugin({ route, file, json = false, mustInclude = null }) {
+  return {
+    name: `sindicate-write:${route}`,
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(route, (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        let body = '';
+        req.on('data', (c) => { body += c; });
+        req.on('end', () => {
+          try {
+            const checks = mustInclude ? [[`payload mentions '${mustInclude}'`, body.includes(mustInclude)]] : [];
+            if (!guardOk(req, res, body, checks)) return;
+            if (json) JSON.parse(body);           // never write a malformed file
+            fs.writeFileSync(file, body);
+            res.statusCode = 200; res.end('ok');
+          } catch (e) { res.statusCode = 500; res.end(String(e)); }
+        });
+      });
+    },
+  };
+}
+
+// Directory listing for editor asset palettes.
+function assetListPlugin({ route, dir, ext }) {
+  const re = new RegExp(`\\.${ext}$`, 'i');
+  return {
+    name: `sindicate-list:${route}`,
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(route, (req, res) => {
+        try {
+          const files = fs.readdirSync(dir).filter((f) => re.test(f)).map((f) => f.replace(re, '')).sort();
+          sendJson(res, 200, files);
+        } catch (e) { res.statusCode = 500; res.end('[]'); }
+      });
+    },
+  };
+}
+
+// Serve + accept a cook-to-file store (bins/JSON/PNG the game bakes for itself).
+function binStorePlugin({ name, serveRoute, saveRoute, dir, nameRe, contentType }) {
+  return {
+    name: `sindicate-store:${name}`,
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(serveRoute, (req, res, next) => {
+        const file = (req.url || '').split('?')[0].replace(/^\//, '');
+        if (!nameRe.test(file)) return next();
+        try {
+          const buf = fs.readFileSync(`${dir}/${file}`);
+          res.setHeader('content-type', typeof contentType === 'function' ? contentType(file) : contentType);
+          res.end(buf);
+        } catch (e) { res.statusCode = 404; res.end('not cooked'); }
+      });
+      server.middlewares.use(saveRoute, async (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        const file = new URL(req.url, 'http://x').searchParams.get('name') || '';
+        if (!nameRe.test(file)) { res.statusCode = 400; return res.end('bad name'); }
+        try {
+          fs.mkdirSync(dir, { recursive: true });
+          fs.writeFileSync(`${dir}/${file}`, await readBody(req));
+          res.statusCode = 200; res.end('ok');
+        } catch (e) { res.statusCode = 500; res.end(String(e)); }
+      });
+    },
+  };
+}
+
+// JSONL telemetry sink with size rotation.
+function perfSinkPlugin(sinkPath) {
+  return {
+    name: 'sindicate-perf-sink',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use('/__perf', (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        let body = '';
+        req.on('data', (c) => { body += c; });
+        req.on('end', () => {
+          try {
+            try { if (fs.statSync(sinkPath).size > 8_000_000) fs.renameSync(sinkPath, sinkPath + '.1'); } catch { /* no sink yet */ }
+            fs.appendFileSync(sinkPath, body.trim() + '\n'); res.statusCode = 200; res.end('ok');
+          } catch (e) { res.statusCode = 500; res.end(String(e)); }
+        });
+      });
+    },
+  };
+}
+
+// A poll/take command bus: POST {…} to /cmd → the page polls /poll → posts /result →
+// collect via /take?id=N. `originGuard` restricts /cmd to same-machine pages.
+function busPlugin({ name, prefix, originGuard = false }) {
+  return {
+    name: `sindicate-bus:${name}`,
+    apply: 'serve',
+    configureServer(server) {
+      const queue = [];
+      const results = new Map();
+      let nextId = 1;
+      server.middlewares.use(`${prefix}/cmd`, async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { err: 'POST only' });
+        if (originGuard) {
+          const origin = req.headers.origin;
+          if (origin && !/^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) return sendJson(res, 403, { err: 'cross-origin refused' });
+        }
+        try {
+          const cmd = JSON.parse((await readBody(req)).toString());
+          cmd.id = nextId++; queue.push(cmd);
+          if (queue.length > 40) queue.splice(0, queue.length - 40);
+          sendJson(res, 200, { id: cmd.id });
+        } catch (e) { sendJson(res, 400, { err: String(e) }); }
+      });
+      server.middlewares.use(`${prefix}/poll`, (req, res) => sendJson(res, 200, { cmds: queue.splice(0) }));
+      server.middlewares.use(`${prefix}/result`, async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { err: 'POST only' });
+        try {
+          const r = JSON.parse((await readBody(req)).toString());
+          results.set(r.id, r);
+          if (results.size > 100) results.delete(results.keys().next().value);
+          sendJson(res, 200, { ok: 1 });
+        } catch (e) { sendJson(res, 400, { err: String(e) }); }
+      });
+      server.middlewares.use(`${prefix}/take`, (req, res) => {
+        const id = Number(new URL(req.url, 'http://x').searchParams.get('id') || 0);
+        if (!results.has(id)) return sendJson(res, 404, { pending: true });
+        const r = results.get(id); results.delete(id); sendJson(res, 200, r);
+      });
+    },
+  };
+}
+
+// Editor screenshot drop (ring-limited) + baked-map store.
+function editorShotsPlugin({ shotsDir, mapsDir }) {
+  return {
+    name: 'sindicate-editor-shots',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use('/__save-editorshot', async (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        const name = new URL(req.url, 'http://x').searchParams.get('name') || '';
+        if (!/^[\w.-]+\.png$/.test(name)) { res.statusCode = 400; return res.end('bad name'); }
+        try {
+          fs.mkdirSync(shotsDir, { recursive: true });
+          fs.writeFileSync(`${shotsDir}/${name}`, await readBody(req));
+          const shots = fs.readdirSync(shotsDir).filter((f) => f.endsWith('.png'));
+          if (shots.length > 150) {
+            shots.map((f) => [f, fs.statSync(`${shotsDir}/${f}`).mtimeMs]).sort((a, b) => a[1] - b[1])
+              .slice(0, shots.length - 150).forEach(([f]) => { try { fs.unlinkSync(`${shotsDir}/${f}`); } catch { /* raced */ } });
+          }
+          res.end('ok');
+        } catch (e) { res.statusCode = 500; res.end(String(e)); }
+      });
+    },
+  };
+}
+
+export function sindicateDevTools({
+  sourceWrites = [],
+  assetLists = [],
+  perfSink = process.env.SINDICATE_PERF_SINK || '/tmp/sindicate-perf.jsonl',
+  cookStores = null,        // override to add/remove stores; null = the standard set below
+  editorShotsDir = 'public/editor-shots',
+  mapsDir = 'public/assets/maps',
+} = {}) {
+  const stores = cookStores ?? [
+    { name: 'vat', serveRoute: '/assets/vat', saveRoute: '/__save-vatbin', dir: 'public/assets/vat', nameRe: /^[\w-]+\.bin$/, contentType: 'application/octet-stream' },
+    { name: 'nav', serveRoute: '/assets/nav', saveRoute: '/__save-navbin', dir: 'public/assets/nav', nameRe: /^[\w.-]+\.bin$/, contentType: 'application/octet-stream' },
+    { name: 'clips', serveRoute: '/assets/clips', saveRoute: '/__save-clipjson', dir: 'public/assets/clips', nameRe: /^[\w.-]+\.json$/, contentType: 'application/json' },
+    { name: 'cook', serveRoute: '/assets/cook', saveRoute: '/__save-cookbin', dir: 'public/assets/cook', nameRe: /^[\w.-]+\.(bin|json)$/, contentType: 'application/octet-stream' },
+    { name: 'maps', serveRoute: '/assets/maps', saveRoute: '/__save-mappng', dir: mapsDir, nameRe: /^[\w.-]+\.(png|json)$/, contentType: (f) => (f.endsWith('.json') ? 'application/json' : 'image/png') },
+  ];
+  return [
+    ...sourceWrites.map(sourceWritePlugin),
+    ...assetLists.map(assetListPlugin),
+    ...stores.map(binStorePlugin),
+    perfSinkPlugin(perfSink),
+    busPlugin({ name: 'game', prefix: '/__game', originGuard: true }),
+    busPlugin({ name: 'editor', prefix: '/__editor' }),
+    editorShotsPlugin({ shotsDir: editorShotsDir, mapsDir }),
+  ];
+}