3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { readFileSync, existsSync, statSync, openSync, fstatSync, closeSync } from 'node:fs';
import { resolve, dirname, join, basename } from 'node:path';
import { LARGE_ASSET_BYTES, startAssetServer } from './asset-server.mjs';
const ASSET_FIELDS = ['glb', 'hdri'];
const MAXIMUM_KEY_FILE_BYTES = 64 * 1024 ** 2;
// Opens once and checks the size on the same handle, so the file cannot change between the check and the read.
function readBoundedFile(file) {
let descriptor;
try {
descriptor = openSync(file, 'r');
} catch {
throw new Error('The camera keys file is missing or larger than 64 MiB.');
}
try {
if (fstatSync(descriptor).size > MAXIMUM_KEY_FILE_BYTES) throw new Error('The camera keys file is missing or larger than 64 MiB.');
return readFileSync(descriptor, 'utf8');
} finally {
closeSync(descriptor);
}
}
/** Reads camera keys: { fps, frames: [[eye, target], ...] } or the keys createCameraPath takes. */
export function readCameraKeys(path) {
const file = resolve(path);
const keys = JSON.parse(readBoundedFile(file));
if (Array.isArray(keys.frames)) {
if (!keys.frames.length) throw new Error('Camera keys need at least one frame.');
const valid = pose => Array.isArray(pose) && pose.length === 2 && pose.every(vector => Array.isArray(vector) && vector.length === 3 && vector.every(Number.isFinite));
if (!keys.frames.every(valid)) throw new Error('Every camera frame must be [[eyeX, eyeY, eyeZ], [targetX, targetY, targetZ]].');
const fps = keys.fps ?? 24;
if (!Number.isFinite(fps) || fps < 1 || fps > 240) throw new Error('Camera keys fps must be between 1 and 240.');
return { ...keys, fps, duration: keys.frames.length / fps };
}
if (!keys.eye || !Number.isFinite(keys.duration)) throw new Error('Camera keys need either frames or createCameraPath keys (duration, eye, target).');
return keys;
}
/**
* Finds a scene.json asset on disk. A path like /showcase/bistro/scene.glb is relative to a served public folder, so it is tried
* under --root, then under the config's folder, then by file name next to the config.
*/
export function resolveAssetPath(assetPath, { configDirectory, root }) {
const relative = assetPath.replace(/^\/+/, '');
const candidates = [root && join(root, relative), join(configDirectory, relative), join(configDirectory, basename(relative))].filter(Boolean);
const found = candidates.find(candidate => existsSync(candidate) && statSync(candidate).isFile());
if (!found) throw new Error(`Scene asset ${assetPath} was not found. Looked in: ${candidates.join(', ')}. Use --root to name the folder it is relative to.`);
return found;
}
/** Reads scene.json and swaps each asset path for a /__file/asset/<n>/<name> URL the export script answers from disk. */
export function prepareFileScene({ configPath, root, largeAssetOrigin, largeAssetBytes = LARGE_ASSET_BYTES }) {
const file = resolve(configPath);
const description = JSON.parse(readFileSync(file, 'utf8'));
const configDirectory = dirname(file);
const assets = [];
const route = assetPath => {
if (/^[a-z]+:/i.test(assetPath)) throw new Error(`Remote asset URLs are not allowed: ${assetPath}`);
const diskPath = resolveAssetPath(assetPath, { configDirectory, root: root ? resolve(root) : null });
assets.push(diskPath);
const name = encodeURIComponent(basename(diskPath));
const isLarge = largeAssetOrigin && statSync(diskPath).size > largeAssetBytes;
return isLarge ? `${largeAssetOrigin}/asset/${assets.length - 1}/${name}` : `/__file/asset/${assets.length - 1}/${name}`;
};
for (const field of ASSET_FIELDS) {
if (typeof description[field] !== 'string') throw new Error(`scene.json needs a "${field}" path.`);
description[field] = route(description[field]);
}
routeStagedParts(description, route);
return { description, assets };
}
// A staged scene lists its other parts in "glbRest", routed like "glb". The first-view fields only speed up the page's first
// frame, so a headless render drops them.
function routeStagedParts(description, route) {
if (description.glbRest !== undefined) {
const isPathList = Array.isArray(description.glbRest) && description.glbRest.every(path => typeof path === 'string');
if (!isPathList) throw new Error('scene.json "glbRest" must be a list of glb paths.');
description.glbRest = description.glbRest.map(route);
}
delete description.hdriPreview;
delete description.glbFirstView;
}
/**
* Reads scene.json and serves every asset above `largeAssetBytes` from a local HTTP server instead of a page route, so a big
* GLB never goes through the browser protocol (it closed the tab at about 80 MiB, #1811). `close()` stops the server.
*/
export async function prepareServedFileScene({ configPath, root, pageOrigin, largeAssetBytes = LARGE_ASSET_BYTES }) {
const assetPaths = [];
const assetServer = await startAssetServer(assetPaths, { pageOrigin });
try {
const world = prepareFileScene({ configPath, root, largeAssetOrigin: assetServer.origin, largeAssetBytes });
assetPaths.push(...world.assets);
return { ...world, close: assetServer.close };
} catch (error) {
await assetServer.close();
throw error;
}
}