3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { closeSync, fstatSync, openSync, readSync, statSync } from 'node:fs';
import { resolve } from 'node:path';
import { setVolumeGridLoader, VOLUME_GRID_MAX_BYTES } from './volume-grid.js';
import { VOLUME_GRID_SEQUENCE_MAX_BYTES, VOLUME_GRID_SEQUENCE_MAX_FRAMES } from './volume-grid-sequence.js';
import { AGENT_ASSET_LIMITS } from './agent-asset-limits.js';
import { explosionGridByteLength, explosionGridBytes, explosionGridNamesFor } from './explosion-grids.js';
// Lets a recipe name a grid volume's file (`grid: "blast.67vg"`) in the MCP server: the name is looked up in one folder, never as a path, so a
// recipe cannot read anywhere else. The folder is the server's working directory unless this variable names another.
export const GRID_DIRECTORY_VARIABLE = 'JS67_GRID_DIRECTORY';
const GRID_FILE_NAME = /^[A-Za-z0-9_-][A-Za-z0-9_.-]*\.67vg$/;
function gridRoot(directory) {
return resolve(directory || process.env[GRID_DIRECTORY_VARIABLE] || process.cwd());
}
/** The bytes of the grid file `name` in `directory`, or null when the name is not a plain .67vg file name or no such file exists. */
export function readVolumeGridFile(name, directory) {
if (typeof name !== 'string' || !GRID_FILE_NAME.test(name)) return null;
const path = resolve(gridRoot(directory), name);
let descriptor;
try {
descriptor = openSync(path, 'r');
} catch {
// The grids add-explosion names are baked from the name when no such file exists, so its recipe works in any session (#1050).
return explosionGridBytes(name);
}
try {
// The size comes from the open file, so the file checked is the file read.
const size = fstatSync(descriptor).size;
if (size > VOLUME_GRID_MAX_BYTES + 4096) throw new RangeError(`grid file "${name}" is ${size} bytes, over the ${VOLUME_GRID_MAX_BYTES} byte limit; convert it with a lower --max-resolution`);
const bytes = new Uint8Array(size);
let offset = 0;
while (offset < size) {
const read = readSync(descriptor, bytes, offset, size - offset, offset);
if (read === 0) break;
offset += read;
}
return offset === size ? bytes : bytes.subarray(0, offset);
} finally {
closeSync(descriptor);
}
}
/** Makes volume grid names that end in .67vg load from `directory`. */
export function installVolumeGridFiles(directory) {
const root = gridRoot(directory);
setVolumeGridLoader(name => readVolumeGridFile(name, root));
}
/** The grid volumes of a recipe or edit list: one `{ names, label }` per volume, `names` being its `frames` or its one `grid`. */
export function volumeGridUses(value) {
const uses = [];
const visit = (node, depth) => {
if (!node || typeof node !== 'object' || depth > 12) return;
if (Array.isArray(node)) {
node.forEach(child => visit(child, depth + 1));
return;
}
if (node.type === 'add-explosion') {
// The fireball grid of an add-explosion is made while the page applies it, so its files go to the page with the call (#1050).
const names = explosionGridNamesFor(node);
if (names) uses.push({ names, label: 'add-explosion' });
}
if (Array.isArray(node.localVolumes)) {
node.localVolumes.forEach((volume, index) => {
if (!volume || typeof volume !== 'object' || volume.shape !== 'grid') return;
uses.push({ names: Array.isArray(volume.frames) ? volume.frames : [volume.grid], label: `environment.localVolumes[${index}]` });
});
}
Object.values(node).forEach(child => visit(child, depth + 1));
};
visit(value, 0);
return uses;
}
/**
* The total size on disk of the distinct grid files a recipe or edit list names, counted without reading any of them, so a caller can refuse
* a call that would send too many bytes before it loads them. A name that is invalid or missing counts as zero here, and a list over the
* frame bound is not counted at all; reading it later throws the error that says what to pass instead. Counting stops once the total
* passes the combined limit, so the number of stat calls stays bounded.
*/
export function volumeGridFileBytes(value, directory) {
const sizes = new Map();
let total = 0;
for (const { names } of volumeGridUses(value)) {
if (names.length > VOLUME_GRID_SEQUENCE_MAX_FRAMES) continue;
for (const name of names) {
if (total > AGENT_ASSET_LIMITS.maxCombinedBytes) return total;
if (typeof name !== 'string' || !GRID_FILE_NAME.test(name) || sizes.has(name)) continue;
let size = 0;
try {
size = statSync(resolve(gridRoot(directory), name)).size;
} catch {
// No file: a grid that add-explosion bakes counts at its known size without baking it (#1903); any other missing name is
// named by readVolumeGridFiles in its own error.
size = explosionGridByteLength(name) ?? 0;
}
sizes.set(name, size);
total += size;
}
}
return total;
}
/**
* The grid files a recipe or edit list names, as a Map of name to bytes, for the preview page, which has no file access. Throws an error that says
* what to pass instead when a name is not a .67vg file name, no such file is in the grid folder, or a sequence is over its byte budget.
*/
export function readVolumeGridFiles(value, directory) {
const files = new Map();
for (const { names, label } of volumeGridUses(value)) {
if (names.length > VOLUME_GRID_SEQUENCE_MAX_FRAMES) throw new RangeError(`${label}.frames lists ${names.length} grids; a sequence has at most ${VOLUME_GRID_SEQUENCE_MAX_FRAMES}`);
let sequenceBytes = 0;
for (const name of names) {
if (typeof name !== 'string' || !GRID_FILE_NAME.test(name)) {
throw new TypeError(`${label} names the grid ${JSON.stringify(name)}; in the MCP server a grid is a file name such as "blast.67vg" in the grid folder, never a path`);
}
if (!files.has(name)) {
const bytes = readVolumeGridFile(name, directory);
if (!bytes) {
throw new RangeError(`${label} names the grid "${name}", which is not in the grid folder: put the file made by scripts/vdb-to-grid.py there (the server's working directory, or the folder ${GRID_DIRECTORY_VARIABLE} names)`);
}
files.set(name, bytes);
}
sequenceBytes += files.get(name).length;
if (sequenceBytes > VOLUME_GRID_SEQUENCE_MAX_BYTES) {
throw new RangeError(`${label}.frames hold ${sequenceBytes} bytes by "${name}", over the ${VOLUME_GRID_SEQUENCE_MAX_BYTES} byte limit for a sequence; use fewer frames or convert with a lower --max-resolution`);
}
}
}
return files;
}