Skip to content

3D engine that AI agents drive

Add crucible pack and the <crucible-scene> runtime element (#2178)

Nguyen Xuan An08cfc9bf090e
diff --git a/FEATURES.md b/FEATURES.md
index 6e5cdfca..8cc5752d 100644
--- a/FEATURES.md
+++ b/FEATURES.md
@@ -472,6 +472,13 @@ optional `Ready` expression the driver waits for, and `Drive`.
- Source: `bin/crucible-mcp.mjs`
- Drive: none: not a page
+### `crucible-pack`
+- Name: Compiles a recipe into a runtime-only web bundle with a `<crucible-scene>` element (docs/pack.md)
+- Surface: CLI
+- Reach: command `npx crucible pack <scene.json> --out <dir>`
+- Source: `bin/crucible.mjs`, `src/scene-pack.js`, `src/crucible-scene.js`
+- Drive: none: not a page
+
### `crucible-addon-check`
- Name: Checks an addon folder against the addon contract (docs/addons.md)
- Surface: CLI
diff --git a/bin/crucible.mjs b/bin/crucible.mjs
new file mode 100644
index 00000000..e80f1229
--- /dev/null
+++ b/bin/crucible.mjs
@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// The crucible command line. `crucible pack <scene.json> --out <dir>` compiles a recipe into a runtime-only web bundle (docs/pack.md).
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const USAGE = 'Usage: crucible pack <scene.json> --out <dir> [--poster <picture.webp>] [--runtime <crucible-scene.js>]';
+const PACK_FLAGS = Object.freeze(['--out', '--poster', '--runtime']);
+
+export function parsePackArguments(argumentList) {
+ const options = { recipePath: null };
+ for (let index = 0; index < argumentList.length; index += 1) {
+ const argument = argumentList[index];
+ if (PACK_FLAGS.includes(argument)) {
+ const value = argumentList[index + 1];
+ if (value === undefined || value.startsWith('--')) throw new TypeError(`${argument}: pass a value, such as ${argument} <path>.`);
+ options[argument.slice(2)] = value;
+ index += 1;
+ } else if (argument.startsWith('--')) {
+ throw new TypeError(`${argument}: unknown option; crucible pack takes ${PACK_FLAGS.join(', ')}.`);
+ } else if (options.recipePath === null) {
+ options.recipePath = argument;
+ } else {
+ throw new TypeError(`${argument}: only one scene.json can be packed at a time; pass the others in separate runs.`);
+ }
+ }
+ return options;
+}
+
+// A published package carries build/scene-pack.js; a source checkout runs src/scene-pack.js directly.
+async function loadPackModule() {
+ const built = join(packageRoot, 'build', 'scene-pack.js');
+ return import(pathToFileURL(existsSync(built) ? built : join(packageRoot, 'src', 'scene-pack.js')).href);
+}
+
+async function main(argumentList) {
+ const [command, ...rest] = argumentList;
+ if (command !== 'pack') {
+ console.error(command === undefined ? USAGE : `${command}: unknown command; the only command is pack.\n${USAGE}`);
+ return 1;
+ }
+ try {
+ const options = parsePackArguments(rest);
+ const { packRecipeFile } = await loadPackModule();
+ const result = await packRecipeFile({
+ recipePath: options.recipePath,
+ outDir: options.out,
+ posterPath: options.poster,
+ runtimePath: options.runtime,
+ packageRoot,
+ });
+ console.log(`Packed ${result.packBytes} bytes into ${result.outDir}: ${result.files.join(', ')}`);
+ return 0;
+ } catch (error) {
+ console.error(`crucible pack: ${error.message}\n${USAGE}`);
+ return 1;
+ }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ process.exitCode = await main(process.argv.slice(2));
+}
diff --git a/changes/2178.md b/changes/2178.md
new file mode 100644
index 00000000..d03fe237
--- /dev/null
+++ b/changes/2178.md
@@ -0,0 +1 @@
+- `crucible pack <scene.json> --out <dir>` compiles a recipe into a runtime-only web bundle, and `<crucible-scene>` shows its poster at once and swaps in live 3D without the recipe compiler (#2178)
diff --git a/config/vite.lib.config.js b/config/vite.lib.config.js
index 6554250d..957b9106 100644
--- a/config/vite.lib.config.js
+++ b/config/vite.lib.config.js
@@ -37,7 +37,7 @@ export default defineConfig({
build: {
copyPublicDir: false,
rolldownOptions: {
- external: ['@dimforge/rapier3d-compat', 'jolt-physics', 'manifold-3d'],
+ external: ['@dimforge/rapier3d-compat', 'jolt-physics', 'manifold-3d', /^node:/],
output: { banner: legalBanner },
},
outDir: 'build',
@@ -73,6 +73,8 @@ export default defineConfig({
grass: 'src/grass.js',
clutter: 'src/clutter.js',
'light-bake': 'src/light-bake.js',
+ 'scene-pack': 'src/scene-pack.js',
+ 'crucible-scene': 'src/crucible-scene.js',
'light-bake-gpu': 'src/light-bake-gpu.js',
'ground-bounce': 'src/ground-bounce.js',
'floor-sky-visibility': 'src/floor-sky-visibility.js',
diff --git a/docs/pack.md b/docs/pack.md
new file mode 100644
index 00000000..1bc96db8
--- /dev/null
+++ b/docs/pack.md
@@ -0,0 +1,53 @@
+# Pack: a recipe as a runtime-only web bundle
+
+`crucible pack` compiles a recipe (`format: "crucible.scene"`) in Node into a compact data file, so a web page loads the renderer and the data but not the recipe compiler. The page uses a `<crucible-scene>` element: it shows a poster picture first, then swaps in live 3D when the scene is ready.
+
+This is slice 1 of #2178. It packs a still scene. Scroll, hover and click triggers, and baked lightmaps, come in later slices.
+
+## Pack a scene
+
+```sh
+npx crucible pack scene.json --out dist/scene --poster shot.webp
+```
+
+It writes into `dist/scene`:
+
+| File | What it holds |
+| --- | --- |
+| `scene.pack` | the compiled parts (geometry as typed arrays), camera, lighting, effects and the shader modules the scene needs |
+| `crucible-scene.js` and its chunks | the runtime: the `<crucible-scene>` element and the renderer |
+| `poster.webp` | the picture you passed with `--poster` (WebP, PNG or JPEG) |
+| `index.html` | a page that uses all of the above |
+
+`--poster` copies a picture you rendered. Pack does not render one itself yet. Without it the element shows a dark box until the 3D is ready. `--runtime <file>` names a built `crucible-scene.js` when the package has no `build/` folder, such as in a source checkout.
+
+Packing the same recipe twice writes the same `scene.pack` bytes.
+
+## The element
+
+```html
+<script type="module" src="https://example.com/scene/crucible-scene.js"></script>
+<crucible-scene src="https://example.com/scene/scene.pack" poster="https://example.com/scene/poster.webp" style="height: 480px"></crucible-scene>
+```
+
+- The poster draws at once. The element then loads the pack and the renderer, draws the scene and fades the poster out.
+- The `state` attribute is `loading`, `live` or `error`. The element fires `crucible-scene-ready` or `crucible-scene-error` (with `detail.message`). After an error the poster stays.
+- Changing `src` or `poster` reloads it. It draws again when it changes size.
+
+`crucible-scene.js` imports no `agent-scene` module. `tests/scene-pack.test.js` checks the import graph.
+
+## What a pack refuses
+
+Pack names the recipe field and what to change. For now it refuses `motion`, `timeline`, `physics`, `cloth`, `particles`, `game`, `postPasses`, `armatures`, `environment.sky`, `environment.hdri`, cascaded shadows, area lights, line art, material snippets and procedural material patterns. Scenes light with `environment.setup`. The automatic floor is not drawn: put a floor in the recipe.
+
+## What it costs
+
+Measured on `public/recipes/view-transform.json` (a lamp, six parts), Chrome, gzip of every file the page downloaded, with the same lighting and the same still:
+
+| | Recipe build (compiler + renderer + recipe) | Packed bundle |
+| --- | --- | --- |
+| JavaScript | 232,047 B | 113,960 B |
+| Data | the recipe JSON, inside the JavaScript | `scene.pack`, 114,681 B |
+| Total | 232,182 B | 228,641 B |
+
+The JavaScript halves. The data does not shrink for this scene, because the baked reflection probes of its two metal parts are 196 KB before gzip. A scene without baked probes pays much less data.
diff --git a/package.json b/package.json
index e45f3a17..cb5e1028 100644
--- a/package.json
+++ b/package.json
@@ -64,6 +64,7 @@
"module": "./build/67.module.js",
"bin": {
"crucible-mcp": "./bin/crucible-mcp.mjs",
+ "crucible": "./bin/crucible.mjs",
"crucible-addon-check": "./bin/crucible-addon-check.mjs",
"67js-mcp": "./bin/67js-mcp.mjs",
"67js-addon-check": "./bin/67js-addon-check.mjs"
@@ -102,6 +103,7 @@
"./addons/grass": "./build/grass.js",
"./addons/clutter": "./build/clutter.js",
"./addons/light-bake": "./build/light-bake.js",
+ "./addons/crucible-scene": "./build/crucible-scene.js",
"./addons/light-bake-gpu": "./build/light-bake-gpu.js",
"./addons/ground-bounce": "./build/ground-bounce.js",
"./addons/floor-sky-visibility": "./build/floor-sky-visibility.js",
diff --git a/src/crucible-scene.js b/src/crucible-scene.js
new file mode 100644
index 00000000..a03344cf
--- /dev/null
+++ b/src/crucible-scene.js
@@ -0,0 +1,150 @@
+// <crucible-scene src="scene.pack" poster="poster.webp">: the runtime of `crucible pack` (docs/pack.md).
+// It shows the poster at once, loads the packed scene and the renderer, then swaps the canvas in. It imports no
+// agent-scene module: the recipe was compiled ahead of time, so the page pays for the renderer and nothing else.
+import { decodePack } from './scene-pack-format.js';
+import { loadPackShaderModules } from './scene-pack-shaders.js';
+
+export const SCENE_STATES = Object.freeze(['loading', 'live', 'error']);
+
+const TEMPLATE = `
+<style>
+ :host { display: block; position: relative; overflow: hidden; background: #111; }
+ canvas, img { position: absolute; inset: 0; width: 100%; height: 100%; display: block; }
+ img { object-fit: cover; transition: opacity 240ms ease; }
+ canvas { opacity: 0; transition: opacity 240ms ease; }
+ :host([state="live"]) canvas { opacity: 1; }
+ :host([state="live"]) img { opacity: 0; pointer-events: none; }
+</style>
+<img part="poster" alt="" hidden>
+<canvas part="canvas"></canvas>
+`;
+
+async function fetchPack(url) {
+ const response = await fetch(url);
+ if (!response.ok) throw new Error(`<crucible-scene src="${url}"> answered ${response.status}; point src at the scene.pack that crucible pack wrote.`);
+ return decodePack(await response.arrayBuffer());
+}
+
+// The renderer and its lighting load after the poster is on screen, so the first paint never waits for them.
+async function createLiveRenderer(canvas, scene) {
+ const [{ CrucibleRenderer }, { createLightingSetupMap }] = await Promise.all([
+ import('./renderer.js'),
+ import('./lighting-setups.js'),
+ loadPackShaderModules(scene.shaderModules),
+ ]);
+ const environment = {
+ ...scene.environment,
+ map: createLightingSetupMap(scene.environment.setup, {
+ intensity: scene.environment.environmentIntensity,
+ rotation: scene.environment.environmentRotation,
+ showBackground: scene.environment.world,
+ }),
+ };
+ const renderer = new CrucibleRenderer(canvas, scene.parts, {
+ ground: false,
+ hdr: true,
+ depth: true,
+ world: scene.environment.world,
+ environment,
+ shadowBounds: scene.shadowBounds,
+ });
+ return { renderer, environment };
+}
+
+export class CrucibleSceneElement extends HTMLElement {
+ static observedAttributes = ['src', 'poster'];
+
+ #renderer = null;
+ #frame = null;
+ #resizeObserver = null;
+ #loadToken = 0;
+ // An element that upgrades after parsing gets its attributes before connectedCallback; only a change after the first load reloads.
+ #started = false;
+
+ constructor() {
+ super();
+ this.attachShadow({ mode: 'open' }).innerHTML = TEMPLATE;
+ }
+
+ connectedCallback() {
+ this.#started = true;
+ this.#showPoster();
+ this.#load();
+ }
+
+ disconnectedCallback() {
+ this.#started = false;
+ this.#dispose();
+ }
+
+ attributeChangedCallback(name) {
+ if (!this.#started) return;
+ if (name === 'poster') this.#showPoster();
+ if (name === 'src') this.#load();
+ }
+
+ get state() {
+ return this.getAttribute('state');
+ }
+
+ #showPoster() {
+ const image = this.shadowRoot.querySelector('img');
+ const poster = this.getAttribute('poster');
+ image.hidden = !poster;
+ if (poster) image.src = poster;
+ }
+
+ #dispose() {
+ this.#loadToken += 1;
+ this.#resizeObserver?.disconnect();
+ this.#resizeObserver = null;
+ if (this.#frame !== null) cancelAnimationFrame(this.#frame);
+ this.#frame = null;
+ this.#renderer?.dispose?.();
+ this.#renderer = null;
+ }
+
+ async #load() {
+ this.#dispose();
+ const token = this.#loadToken;
+ const source = this.getAttribute('src');
+ this.setAttribute('state', 'loading');
+ try {
+ if (!source) throw new Error('<crucible-scene> needs a src attribute: the scene.pack that crucible pack wrote.');
+ const scene = await fetchPack(source);
+ const canvas = this.shadowRoot.querySelector('canvas');
+ const { renderer, environment } = await createLiveRenderer(canvas, scene);
+ if (token !== this.#loadToken) {
+ renderer.dispose?.();
+ return;
+ }
+ this.#renderer = renderer;
+ this.#startDrawing(scene, environment);
+ this.setAttribute('state', 'live');
+ this.dispatchEvent(new CustomEvent('crucible-scene-ready', { detail: { parts: scene.parts.length } }));
+ } catch (error) {
+ if (token !== this.#loadToken) return;
+ this.setAttribute('state', 'error');
+ this.dispatchEvent(new CustomEvent('crucible-scene-error', { detail: { message: error.message } }));
+ }
+ }
+
+ // A still scene draws again only when the element changes size.
+ #startDrawing(scene, environment) {
+ const draw = () => {
+ this.#frame = null;
+ this.#renderer.resize();
+ this.#renderer.render({ ...scene.camera, environment, effects: scene.effects, exposure: scene.effects.exposure, time: 0 });
+ };
+ const schedule = () => {
+ if (this.#frame === null) this.#frame = requestAnimationFrame(draw);
+ };
+ this.#resizeObserver = new ResizeObserver(schedule);
+ this.#resizeObserver.observe(this);
+ schedule();
+ }
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('crucible-scene')) {
+ customElements.define('crucible-scene', CrucibleSceneElement);
+}
diff --git a/src/scene-pack-format.js b/src/scene-pack-format.js
new file mode 100644
index 00000000..c50ea474
--- /dev/null
+++ b/src/scene-pack-format.js
@@ -0,0 +1,105 @@
+// The file format of `crucible pack` (docs/pack.md): a compiled scene as one JSON header plus one binary block.
+// This module is shared by the Node compiler (src/scene-pack.js) and the web runtime (src/crucible-scene.js), so it imports
+// nothing: the runtime must not pull any agent-scene code through it.
+
+export const PACK_FORMAT = 'crucible.pack';
+export const PACK_VERSION = 1;
+
+const TYPED_ARRAYS = Object.freeze({
+ Float32Array, Float64Array, Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array,
+});
+const TYPED_MARKER = '$typed';
+const ALIGNMENT = 4;
+const HEADER_BYTES = 8;
+const MAGIC = 0x4b435243; // "CRCK" read as little endian
+
+function padTo(length, alignment) {
+ return Math.ceil(length / alignment) * alignment;
+}
+
+function describeKind(value) {
+ return Object.prototype.toString.call(value).slice(8, -1);
+}
+
+/**
+ * Splits a value into JSON and binary: every typed array becomes a { $typed, offset, length } marker and its bytes go to
+ * the binary block, so geometry is never written as text. Anything JSON cannot hold throws and names where it sits.
+ */
+function encodeValue(value, path, chunks, cursor) {
+ if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+ if (typeof value === 'number') {
+ if (!Number.isFinite(value)) throw new TypeError(`${path}: got ${value}; expected a finite number. Fix the recipe field that produced it.`);
+ return value;
+ }
+ if (ArrayBuffer.isView(value)) {
+ const name = value.constructor.name;
+ if (!Object.hasOwn(TYPED_ARRAYS, name)) throw new TypeError(`${path}: got ${name}; expected a typed array such as Float32Array or Uint32Array.`);
+ const offset = padTo(cursor.bytes, ALIGNMENT);
+ const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+ chunks.push({ offset, bytes });
+ cursor.bytes = offset + bytes.byteLength;
+ return { [TYPED_MARKER]: name, offset, length: value.length };
+ }
+ if (Array.isArray(value)) return value.map((entry, index) => encodeValue(entry, `${path}[${index}]`, chunks, cursor));
+ if (value !== undefined && typeof value === 'object') {
+ const kind = describeKind(value);
+ if (kind !== 'Object') throw new TypeError(`${path}: got a ${kind}; expected plain data. A pack holds numbers, strings, arrays, objects and typed arrays only.`);
+ const encoded = {};
+ for (const key of Object.keys(value)) {
+ if (value[key] !== undefined) encoded[key] = encodeValue(value[key], `${path}.${key}`, chunks, cursor);
+ }
+ return encoded;
+ }
+ throw new TypeError(`${path}: got ${typeof value}; expected plain data. A pack holds numbers, strings, arrays, objects and typed arrays only.`);
+}
+
+function decodeValue(value, binary) {
+ if (Array.isArray(value)) return value.map(entry => decodeValue(entry, binary));
+ if (value === null || typeof value !== 'object') return value;
+ if (Object.hasOwn(value, TYPED_MARKER)) {
+ const Constructor = TYPED_ARRAYS[value[TYPED_MARKER]];
+ if (!Constructor) throw new TypeError(`pack: unknown typed array "${value[TYPED_MARKER]}"; repack the scene with this version of crucible pack.`);
+ return new Constructor(binary.buffer, binary.byteOffset + value.offset, value.length);
+ }
+ const decoded = {};
+ for (const key of Object.keys(value)) decoded[key] = decodeValue(value[key], binary);
+ return decoded;
+}
+
+/** Encodes a scene description into one deterministic Uint8Array: the same input always gives the same bytes. */
+export function encodePack(scene) {
+ if (scene === null || typeof scene !== 'object' || Array.isArray(scene)) {
+ throw new TypeError('encodePack: pass the scene object to pack, such as { camera, environment, parts }.');
+ }
+ const chunks = [];
+ const cursor = { bytes: 0 };
+ const body = encodeValue(scene, 'scene', chunks, cursor);
+ const header = new TextEncoder().encode(JSON.stringify({ format: PACK_FORMAT, version: PACK_VERSION, scene: body }));
+ const binaryStart = padTo(HEADER_BYTES + header.length, ALIGNMENT);
+ const output = new Uint8Array(binaryStart + cursor.bytes);
+ const view = new DataView(output.buffer);
+ view.setUint32(0, MAGIC, true);
+ view.setUint32(4, header.length, true);
+ output.set(header, HEADER_BYTES);
+ for (const { offset, bytes } of chunks) output.set(bytes, binaryStart + offset);
+ return output;
+}
+
+/** Reads what encodePack wrote. Typed arrays are views on `bytes`, so the caller must keep it alive. */
+export function decodePack(input) {
+ const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input;
+ if (!(bytes instanceof Uint8Array)) throw new TypeError('decodePack: pass the bytes of a .pack file as an ArrayBuffer or Uint8Array.');
+ if (bytes.length < HEADER_BYTES || new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, true) !== MAGIC) {
+ throw new TypeError('decodePack: these bytes are not a crucible pack. Pass a file written by `crucible pack`.');
+ }
+ const headerLength = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(4, true);
+ if (HEADER_BYTES + headerLength > bytes.length) throw new TypeError('decodePack: the pack is cut short. Download or copy it again.');
+ const header = JSON.parse(new TextDecoder().decode(bytes.subarray(HEADER_BYTES, HEADER_BYTES + headerLength)));
+ if (header.format !== PACK_FORMAT || header.version !== PACK_VERSION) {
+ throw new TypeError(`decodePack: got ${header.format} version ${header.version}; expected ${PACK_FORMAT} version ${PACK_VERSION}. Repack the scene with this version of crucible pack.`);
+ }
+ const binaryStart = padTo(HEADER_BYTES + headerLength, ALIGNMENT);
+ // The typed array views need a 4 byte aligned buffer offset, so a pack read from an odd offset is copied once.
+ const aligned = (bytes.byteOffset + binaryStart) % ALIGNMENT === 0 ? bytes.subarray(binaryStart) : bytes.slice(binaryStart);
+ return decodeValue(header.scene, aligned);
+}
diff --git a/src/scene-pack-shaders.js b/src/scene-pack-shaders.js
new file mode 100644
index 00000000..117a1b56
--- /dev/null
+++ b/src/scene-pack-shaders.js
@@ -0,0 +1,38 @@
+// The shader code a packed scene can need at run time. The renderer draws a feature only after its shader module has been
+// imported, which agent-scene does when it compiles a recipe (src/agent-scene-modules.js). A pack lists the module names
+// its scene needs and the runtime imports exactly those, so the page never loads the recipe compiler. The names are the
+// keys of agent-scene-modules.js; each module here only registers GLSL and imports no agent-scene code.
+
+export const PACK_SHADER_MODULES = Object.freeze({
+ layerShaders: () => import('./material-layer-shaders.js'),
+ emissionMask: () => import('./emission-mask.js'),
+ liquidShader: () => import('./liquid-shader.js'),
+ subsurfaceShader: () => import('./subsurface-shader.js'),
+ fogShader: () => import('./fog-shader.js'),
+ retroShader: () => import('./retro-shader.js'),
+ worldMaterials: () => import('./world-material-shader.js'),
+ // The probe code of the object reflections a metal part carries; the traced probe data itself travels in the pack.
+ reflections: () => import('./reflection-probes.js'),
+ viewTransform: () => import('./view-transform-shader.js'),
+ postSteps: () => import('./post-steps.js'),
+ volumeGrid: () => import('./local-volume-grid.js'),
+ volumeRamp: () => import('./local-volume-ramp.js'),
+});
+
+// Recipe features that need more than shader code at run time. A pack refuses them until a later slice of #2178 carries them.
+export const PACK_UNSUPPORTED_MODULES = Object.freeze({
+ cascades: 'cascaded shadows, sun angular radius, ies profiles or area lights',
+ lineArt: 'line art or toon shading',
+ userPass: 'postPasses',
+ materialSnippet: 'material snippets',
+ patterns: 'procedural material patterns',
+});
+
+/** Imports the shader modules a pack names. Throws for a name this runtime does not know, which means the pack is newer. */
+export function loadPackShaderModules(names) {
+ return Promise.all(names.map(name => {
+ const load = PACK_SHADER_MODULES[name];
+ if (!load) throw new Error(`The pack needs the shader module "${name}", which this runtime does not have; update crucible or repack the scene.`);
+ return load();
+ }));
+}
diff --git a/src/scene-pack.js b/src/scene-pack.js
new file mode 100644
index 00000000..82f5b6fc
--- /dev/null
+++ b/src/scene-pack.js
@@ -0,0 +1,160 @@
+// Compiles a recipe (format crucible.scene) in Node into a runtime-only web bundle (docs/pack.md).
+// The compiler stays here; the page loads src/crucible-scene.js, which reads the result without any agent-scene code.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { createAgentScene, loadAllAgentSceneModules } from './agent-scene.js';
+import { fitAgentShadow, resolveAgentShadow } from './agent-look.js';
+import { agentSceneModulesNeeded } from './agent-scene-modules.js';
+import { encodePack } from './scene-pack-format.js';
+import { PACK_SHADER_MODULES, PACK_UNSUPPORTED_MODULES } from './scene-pack-shaders.js';
+
+export const PACK_FILE_NAME = 'scene.pack';
+export const PACK_RUNTIME_FILE_NAME = 'crucible-scene.js';
+export const PACK_POSTER_EXTENSIONS = Object.freeze(['.webp', '.png', '.jpg', '.jpeg']);
+const RECIPE_FORMAT = 'crucible.scene';
+// Sections of a recipe that move or simulate. Slice 1 of #2178 packs the scene at time zero only.
+const UNSUPPORTED_SECTIONS = Object.freeze(['motion', 'timeline', 'physics', 'cloth', 'particles', 'game', 'postPasses', 'armatures']);
+
+function refuse(message) {
+ throw new TypeError(message);
+}
+
+/** The checks that need no compile: they name the recipe field and what to pass instead. */
+export function validatePackRecipe(recipe) {
+ if (recipe === null || typeof recipe !== 'object' || Array.isArray(recipe)) {
+ refuse('recipe: got something that is not an object; pass a scene.json written for format crucible.scene.');
+ }
+ if (recipe.format !== RECIPE_FORMAT) {
+ refuse(`recipe.format: got ${JSON.stringify(recipe.format)}; expected "${RECIPE_FORMAT}". Pass a scene recipe, not a glTF or a pack.`);
+ }
+ for (const section of UNSUPPORTED_SECTIONS) {
+ if (recipe[section] !== undefined) {
+ refuse(`recipe.${section}: crucible pack writes a still scene for now; remove "${section}" from the recipe (animated packs are planned in #2178).`);
+ }
+ }
+ const needed = agentSceneModulesNeeded(recipe);
+ for (const name of needed) {
+ if (Object.hasOwn(PACK_UNSUPPORTED_MODULES, name)) {
+ refuse(`recipe: it uses ${PACK_UNSUPPORTED_MODULES[name]}, which crucible pack does not carry yet; remove it from the recipe (planned in #2178).`);
+ }
+ }
+ const environment = recipe.environment ?? {};
+ for (const field of ['sky', 'hdri']) {
+ if (environment[field]) {
+ refuse(`recipe.environment.${field}: crucible pack lights a scene with a lighting setup for now; remove "${field}" and set environment.setup (daylight, studio and the other names scene_capabilities lists).`);
+ }
+ }
+}
+
+/** Compiles a recipe to the bytes of a `.pack` file: its parts, camera, lighting and effects, ready for the runtime. */
+export async function compileRecipeToPack(recipe) {
+ validatePackRecipe(recipe);
+ await loadAllAgentSceneModules();
+ const scene = createAgentScene(recipe);
+ const environment = scene.environment;
+ return encodePack({
+ shaderModules: agentSceneModulesNeeded(recipe).filter(name => Object.hasOwn(PACK_SHADER_MODULES, name)),
+ camera: scene.camera,
+ environment,
+ effects: scene.effects,
+ shadowBounds: resolveAgentShadow(fitAgentShadow(scene.shadow, scene.parts), environment.lightDirection),
+ parts: scene.parts.map(part => ({ name: part.name, geometry: part.geometry, material: part.material, matrix: part.matrix })),
+ });
+}
+
+export function indexHtml({ title, posterName }) {
+ const posterAttribute = posterName ? ` poster="./${posterName}"` : '';
+ return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>html,body{margin:0;height:100%;background:#111}crucible-scene{display:block;width:100%;height:100%}</style>
+<script type="module" src="./${PACK_RUNTIME_FILE_NAME}"></script>
+</head>
+<body>
+<crucible-scene src="./${PACK_FILE_NAME}"${posterAttribute}></crucible-scene>
+</body>
+</html>
+`;
+}
+
+function requireFile(path, flag, what) {
+ if (!path) refuse(`${flag}: pass the path of ${what}.`);
+ if (!existsSync(path) || !statSync(path).isFile()) refuse(`${flag}: ${path} is not a file; pass the path of ${what}.`);
+}
+
+// A `from "./x.js"`, a bare `import "./x.js"` at the start of a statement or an `import("./x.js")`. An error message that
+// only mentions an import ("add import './x.js'") does not count.
+const RELATIVE_IMPORT = /(?:\bfrom\s*|(?:^|[;}\n])\s*import\s*|\bimport\s*\(\s*)["'](\.\/[^"']+\.js)["']/g;
+
+// Pages that import the runtime also need the chunks it imports, so the whole relative import tree is copied beside it.
+function runtimeFilesOf(entryPath) {
+ const found = new Set();
+ const pending = [entryPath];
+ while (pending.length > 0) {
+ const path = pending.pop();
+ if (found.has(path)) continue;
+ found.add(path);
+ const source = readFileSync(path, 'utf8');
+ for (const match of source.matchAll(RELATIVE_IMPORT)) {
+ pending.push(join(dirname(path), match[1]));
+ }
+ }
+ return [...found];
+}
+
+/** The built runtime of this package, build/crucible-scene.js, or the file `--runtime` names. */
+export function findRuntimeEntry(runtimePath, packageRoot) {
+ if (runtimePath) {
+ requireFile(runtimePath, '--runtime', 'a built crucible-scene.js');
+ return resolve(runtimePath);
+ }
+ const built = join(packageRoot, 'build', PACK_RUNTIME_FILE_NAME);
+ if (!existsSync(built)) refuse(`--runtime: ${built} does not exist; run npm run build, or pass --runtime <path to a built crucible-scene.js>.`);
+ return built;
+}
+
+function readRecipe(recipePath) {
+ requireFile(recipePath, '<scene.json>', 'the recipe to pack, such as scene.json');
+ try {
+ return JSON.parse(readFileSync(recipePath, 'utf8'));
+ } catch (error) {
+ return refuse(`<scene.json>: ${recipePath} is not valid JSON (${error.message}); pass a recipe file.`);
+ }
+}
+
+function checkPosterFile(posterPath) {
+ requireFile(posterPath, '--poster', 'a WebP, PNG or JPEG picture of the scene');
+ if (!PACK_POSTER_EXTENSIONS.includes(extname(posterPath).toLowerCase())) {
+ refuse(`--poster: ${posterPath} is not ${PACK_POSTER_EXTENSIONS.join(', ')}; pass a WebP, PNG or JPEG picture.`);
+ }
+}
+
+/** Reads scene.json, writes <outDir>/scene.pack, the runtime, an optional poster and index.html. Returns what it wrote. */
+export async function packRecipeFile({ recipePath, outDir, posterPath, runtimePath, packageRoot }) {
+ const recipe = readRecipe(recipePath);
+ if (!outDir) refuse('--out: pass the folder to write the web bundle into, such as --out dist/scene.');
+ if (posterPath) checkPosterFile(posterPath);
+ const runtimeEntry = findRuntimeEntry(runtimePath, packageRoot);
+ const packBytes = await compileRecipeToPack(recipe);
+ mkdirSync(outDir, { recursive: true });
+ const files = [];
+ writeFileSync(join(outDir, PACK_FILE_NAME), packBytes);
+ files.push(PACK_FILE_NAME);
+ for (const file of runtimeFilesOf(runtimeEntry)) {
+ // The entry is always written as crucible-scene.js; its chunks keep their own names.
+ const name = file === runtimeEntry ? PACK_RUNTIME_FILE_NAME : basename(file);
+ copyFileSync(file, join(outDir, name));
+ files.push(name);
+ }
+ const posterName = posterPath ? `poster${extname(posterPath).toLowerCase()}` : null;
+ if (posterName) {
+ copyFileSync(posterPath, join(outDir, posterName));
+ files.push(posterName);
+ }
+ writeFileSync(join(outDir, 'index.html'), indexHtml({ title: basename(recipePath, extname(recipePath)), posterName }));
+ files.push('index.html');
+ return { outDir, files, packBytes: packBytes.length };
+}
diff --git a/tests/scene-pack.test.js b/tests/scene-pack.test.js
new file mode 100644
index 00000000..de7f8ee4
--- /dev/null
+++ b/tests/scene-pack.test.js
@@ -0,0 +1,137 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { build } from 'esbuild';
+import { createAgentScene, loadAllAgentSceneModules } from '../src/agent-scene.js';
+import { encodePack, decodePack } from '../src/scene-pack-format.js';
+import { compileRecipeToPack, validatePackRecipe, packRecipeFile, indexHtml } from '../src/scene-pack.js';
+import { parsePackArguments } from '../bin/crucible.mjs';
+
+const RECIPE = Object.freeze({
+ format: 'crucible.scene',
+ schemaVersion: 1,
+ geometries: [{ id: 'cube', type: 'box', bevel: 0 }, { id: 'ball', type: 'sphere' }],
+ materials: [{ id: 'blue', color: [0.1, 0.3, 0.8] }, { id: 'red', color: [0.8, 0.1, 0.1], roughness: 0.2 }],
+ nodes: [
+ { id: 'cube', geometry: 'cube', material: 'blue' },
+ { id: 'ball', geometry: 'ball', material: 'red', translation: [1.5, 0.5, 0] },
+ ],
+});
+
+function temporaryFolder() {
+ return mkdtempSync(join(tmpdir(), 'crucible-pack-'));
+}
+
+test('a packed scene holds the same geometry bytes as compiling the recipe directly', async () => {
+ await loadAllAgentSceneModules();
+ const direct = createAgentScene(structuredClone(RECIPE));
+ const packed = decodePack(await compileRecipeToPack(structuredClone(RECIPE)));
+ assert.equal(packed.parts.length, direct.parts.length);
+ direct.parts.forEach((part, index) => {
+ const unpacked = packed.parts[index];
+ assert.equal(unpacked.name, part.name);
+ assert.deepEqual(unpacked.material, JSON.parse(JSON.stringify(part.material)));
+ assert.deepEqual([...unpacked.matrix], [...part.matrix]);
+ for (const [attribute, array] of Object.entries(part.geometry)) {
+ assert.ok(unpacked.geometry[attribute] instanceof array.constructor, `${attribute} keeps its typed array type`);
+ assert.deepEqual(Buffer.from(unpacked.geometry[attribute].buffer, unpacked.geometry[attribute].byteOffset, unpacked.geometry[attribute].byteLength),
+ Buffer.from(array.buffer, array.byteOffset, array.byteLength), `${attribute} bytes of ${part.name}`);
+ }
+ });
+ assert.deepEqual(packed.camera, direct.camera);
+ assert.equal(packed.environment.setup, direct.environment.setup);
+});
+
+test('packing the same recipe twice gives the same bytes', async () => {
+ const first = await compileRecipeToPack(structuredClone(RECIPE));
+ const second = await compileRecipeToPack(structuredClone(RECIPE));
+ assert.deepEqual(Buffer.from(first), Buffer.from(second));
+});
+
+test('the pack format keeps typed arrays aligned and rejects what JSON cannot hold', () => {
+ const bytes = encodePack({ values: new Float32Array([1, 2, 3]), small: new Uint8Array([7]), more: new Uint32Array([9, 8]), label: 'x' });
+ const decoded = decodePack(bytes);
+ assert.deepEqual([...decoded.values], [1, 2, 3]);
+ assert.deepEqual([...decoded.more], [9, 8]);
+ assert.equal(decoded.label, 'x');
+ const shifted = new Uint8Array(bytes.length + 1);
+ shifted.set(bytes, 1);
+ assert.deepEqual([...decodePack(shifted.subarray(1)).values], [1, 2, 3]);
+ assert.throws(() => encodePack({ bad: Number.NaN }), /scene\.bad: got NaN; expected a finite number/);
+ assert.throws(() => encodePack({ bad: new Map() }), /scene\.bad: got a Map; expected plain data/);
+ assert.throws(() => encodePack({ bad: () => 1 }), /scene\.bad: got function/);
+ assert.throws(() => encodePack(null), /pass the scene object to pack/);
+ assert.throws(() => decodePack(new Uint8Array(16)), /not a crucible pack/);
+ assert.throws(() => decodePack(bytes.subarray(0, 12)), /cut short/);
+ assert.throws(() => decodePack('text'), /as an ArrayBuffer or Uint8Array/);
+});
+
+test('a recipe that crucible pack cannot write yet is refused with what to change', () => {
+ assert.throws(() => validatePackRecipe([]), /not an object/);
+ assert.throws(() => validatePackRecipe({ format: 'gltf' }), /expected "crucible.scene"/);
+ assert.throws(() => validatePackRecipe({ ...RECIPE, motion: {} }), /recipe\.motion: .*remove "motion"/);
+ assert.throws(() => validatePackRecipe({ ...RECIPE, environment: { hdri: 'studio' } }), /environment\.hdri: .*set environment\.setup/);
+ assert.doesNotThrow(() => validatePackRecipe(RECIPE));
+});
+
+test('crucible pack arguments name the flag that is wrong', () => {
+ assert.deepEqual(parsePackArguments(['scene.json', '--out', 'dist', '--poster', 'p.webp']), { recipePath: 'scene.json', out: 'dist', poster: 'p.webp' });
+ assert.throws(() => parsePackArguments(['a.json', 'b.json']), /only one scene\.json/);
+ assert.throws(() => parsePackArguments(['a.json', '--out']), /--out: pass a value/);
+ assert.throws(() => parsePackArguments(['--minify']), /--minify: unknown option/);
+});
+
+test('packRecipeFile writes the pack, the runtime, the poster and an index.html that uses the runtime only', async () => {
+ const folder = temporaryFolder();
+ try {
+ const recipePath = join(folder, 'scene.json');
+ const runtimePath = join(folder, 'runtime.js');
+ const posterPath = join(folder, 'shot.webp');
+ writeFileSync(recipePath, JSON.stringify(RECIPE));
+ writeFileSync(runtimePath, 'import "./chunk.js";\nexport const runtime = true;\nexport const hint = "add import \'./not-a-chunk.js\'";\n');
+ writeFileSync(join(folder, 'chunk.js'), 'export const chunk = true;\n');
+ writeFileSync(posterPath, 'poster');
+ const outDir = join(folder, 'out');
+ const result = await packRecipeFile({ recipePath, outDir, posterPath, runtimePath, packageRoot: folder });
+ assert.deepEqual(result.files.sort(), ['chunk.js', 'crucible-scene.js', 'index.html', 'poster.webp', 'scene.pack']);
+ const html = readFileSync(join(outDir, 'index.html'), 'utf8');
+ assert.match(html, /<crucible-scene src="\.\/scene\.pack" poster="\.\/poster\.webp">/);
+ assert.match(html, /src="\.\/crucible-scene\.js"/);
+ assert.ok(!html.includes('agent-scene'));
+ assert.equal(decodePack(readFileSync(join(outDir, 'scene.pack'))).parts.length, 2);
+ assert.ok(!indexHtml({ title: 't', posterName: null }).includes('poster='));
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ }
+});
+
+test('packRecipeFile checks its inputs before it writes anything', async () => {
+ const folder = temporaryFolder();
+ try {
+ const recipePath = join(folder, 'scene.json');
+ writeFileSync(recipePath, JSON.stringify(RECIPE));
+ const runtimePath = join(folder, 'runtime.js');
+ writeFileSync(runtimePath, 'export {};');
+ const outDir = join(folder, 'out');
+ await assert.rejects(packRecipeFile({ recipePath: join(folder, 'none.json'), outDir, runtimePath }), /<scene\.json>: .*is not a file/);
+ writeFileSync(join(folder, 'broken.json'), '{');
+ await assert.rejects(packRecipeFile({ recipePath: join(folder, 'broken.json'), outDir, runtimePath }), /not valid JSON/);
+ await assert.rejects(packRecipeFile({ recipePath, runtimePath }), /--out: pass the folder/);
+ writeFileSync(join(folder, 'poster.bmp'), 'x');
+ await assert.rejects(packRecipeFile({ recipePath, outDir, runtimePath, posterPath: join(folder, 'poster.bmp') }), /--poster: .*pass a WebP, PNG or JPEG/);
+ await assert.rejects(packRecipeFile({ recipePath, outDir, packageRoot: folder }), /--runtime: .*does not exist; run npm run build/);
+ assert.ok(!existsSync(outDir), 'nothing is written when an input is wrong');
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ }
+});
+
+test('the <crucible-scene> runtime imports no agent-scene compiler code', async () => {
+ const result = await build({ entryPoints: ['src/crucible-scene.js'], bundle: true, write: false, metafile: true, format: 'esm', splitting: true, outdir: 'out', logLevel: 'error' });
+ const inputs = Object.keys(result.metafile.inputs);
+ assert.ok(inputs.includes('src/renderer.js'), 'the runtime reaches the renderer');
+ const compilerModules = inputs.filter(path => /src\/(agent-scene(?!-capabilities)|agent-look|agent-apply|scene-pack\.js)/.test(path));
+ assert.deepEqual(compilerModules, []);
+});