3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { createHash } from 'node:crypto';
import { open, readdir, realpath, lstat } from 'node:fs/promises';
import { dirname, isAbsolute, join, relative, sep } from 'node:path';
import { clipDisplayName } from '../src/clip-name.js';
import { AGENT_ASSET_LIMITS, assetBytesLimitMessage } from '../src/agent-asset-limits.js';
import { MAXIMUM_CATALOG_ENVIRONMENT_BYTES, MAXIMUM_CATALOG_LOOK_BYTES } from '../src/look-catalog.js';
import { imageLimitProblem, readImageDimensions } from '../src/image-header.js';
import { TEXTURE_SEQUENCE_LIMITS } from '../src/texture-sequence-limits.js';
import { decompressDracoGlb, usesDraco } from './agent-draco.mjs';
import { transcodeKtx2Glb, usesKtx2 } from './agent-ktx2.mjs';
import { findSequenceRuns } from './agent-asset-sequences.mjs';
const MAXIMUM_ASSETS = AGENT_ASSET_LIMITS.maxAssets;
const IMAGE_FILE_PATTERN = /\.(png|jpe?g|webp)$/i;
const MAXIMUM_BYTES = AGENT_ASSET_LIMITS.maxBytes;
const IMAGE_EXTENSIONS = { png: /\.png$/i, jpeg: /\.jpe?g$/i, webp: /\.webp$/i };
/**
* A file the catalog refuses for its size, its pixel bounds or a texture it cannot find (#2072). Listing skips it and says why, so one such file does not hide the
* others; reading it by name still throws.
*/
export class SkippableCatalogFileError extends RangeError {
constructor(message) {
super(message);
this.name = 'SkippableCatalogFileError';
}
}
/** 'environment' for a Radiance .hdr and 'look' for a .cube file, by extension and a first-bytes check; the preview decodes them. */
function lookFileKind(filename, bytes) {
const isHdr = /\.hdr$/i.test(filename);
const isCube = /\.cube$/i.test(filename);
if (!isHdr && !isCube) return null;
const limitBytes = isHdr ? MAXIMUM_CATALOG_ENVIRONMENT_BYTES : MAXIMUM_CATALOG_LOOK_BYTES;
if (bytes.length > limitBytes) {
const kindName = isHdr ? 'An .hdr catalog file' : 'A .cube catalog file';
const advice = isHdr ? 'Use a 2k or smaller HDRI.' : 'Use a smaller LUT, for example 33 points on a side.';
throw new SkippableCatalogFileError(`${kindName} is at most ${limitBytes / 1048576} MiB; this one is ${(bytes.length / 1048576).toFixed(1)} MiB. ${advice}`);
}
if (isHdr) {
if (!/^#\?(?:RADIANCE|RGBE)/.test(bytes.toString('latin1', 0, 10))) throw new Error('An .hdr catalog file must be a Radiance file starting with #?RADIANCE or #?RGBE.');
return 'environment';
}
if (!bytes.toString('utf8').includes('LUT_3D_SIZE')) throw new Error('A .cube catalog file must be a 3D look (LUT_3D_SIZE).');
return 'look';
}
const IMAGE_MIME = { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' };
/** 'png', 'jpeg' or 'webp' from the file signature, else null. Catalog images are decoded by the preview, never by the server. */
export function imageKind(bytes) {
if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'png';
if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'jpeg';
if (bytes.length >= 12 && bytes.toString('latin1', 0, 4) === 'RIFF' && bytes.toString('latin1', 8, 12) === 'WEBP' && bytes.readUInt32LE(4) + 8 === bytes.length) return 'webp';
return null;
}
const JSON_CHUNK = 0x4e4f534a;
const BINARY_CHUNK = 0x004e4942;
function glbDocument(bytes) {
if (bytes.length < 20 || bytes.readUInt32LE(0) !== 0x46546c67 || bytes.readUInt32LE(4) !== 2 || bytes.readUInt32LE(8) !== bytes.length) {
throw new Error('Asset must be a complete glTF 2.0 binary file.');
}
const jsonLength = bytes.readUInt32LE(12);
if (bytes.readUInt32LE(16) !== JSON_CHUNK || jsonLength % 4 !== 0 || jsonLength > bytes.length - 20) {
throw new Error('GLB must start with a bounded JSON chunk.');
}
const document = JSON.parse(bytes.subarray(20, 20 + jsonLength).toString('utf8'));
if (document.asset?.version !== '2.0') {
throw new Error('Asset must declare glTF version 2.0.');
}
return { document, jsonLength };
}
/** A GLB whose buffers are embedded. Image `uri` fields are allowed here; embedSiblingImages turns them into embedded images. */
function selfContainedGlb(bytes) {
const parsed = glbDocument(bytes);
for (const collection of ['buffers', 'images']) {
const resources = parsed.document[collection];
if (resources !== undefined && !Array.isArray(resources)) {
throw new Error(`GLB ${collection} must be an array.`);
}
for (const resource of resources ?? []) {
if (!resource || typeof resource !== 'object') {
throw new Error(`GLB ${collection} entries must be objects.`);
}
if (collection === 'buffers' && Object.hasOwn(resource, 'uri')) {
throw new Error('Catalog GLBs must embed all buffers; a .bin file next to the GLB is not loaded. Re-export the model as a single .glb.');
}
}
}
return parsed;
}
/** The path segments of an image beside the GLB, or an error that names the GLB, the URI and what to pass instead. */
function siblingImageSegments(filename, uri) {
const prefix = `${filename}: image uri "${uri}"`;
if (typeof uri !== 'string' || !uri || uri.length > 512) {
throw new Error(`${prefix} must be a relative file path of at most 512 characters, such as "Textures/colormap.png".`);
}
if (/^[a-z][a-z0-9+.-]*:/i.test(uri)) {
throw new Error(`${prefix} is a remote or embedded address, which the catalog does not fetch. Put the image file next to the GLB and use a relative path, such as "colormap.png", or embed the image in the GLB.`);
}
let decoded;
try {
decoded = decodeURIComponent(uri);
} catch {
throw new Error(`${prefix} is not valid percent-encoding. Use a plain relative path, such as "Textures/colormap.png".`);
}
const segments = decoded.split(/[\\/]/);
if (decoded.startsWith('/') || decoded.startsWith('\\') || /^[a-z]:/i.test(decoded) || segments.includes('..')) {
throw new Error(`${prefix} leaves the GLB's folder. Copy the image into the folder (or a folder below it) and use a relative path, such as "colormap.png".`);
}
return segments.filter(segment => segment && segment !== '.');
}
function padded(buffer, fill) {
const padding = (4 - (buffer.length % 4)) % 4;
return padding ? Buffer.concat([buffer, Buffer.alloc(padding, fill)]) : buffer;
}
/** Rebuilds the GLB with every image `uri` read from the GLB's folder and stored in the binary chunk, so the stored asset is self-contained. */
async function embedSiblingImages(bytes, parsed, filename, readSibling) {
const { document, jsonLength } = parsed;
const binaryStart = 20 + jsonLength;
const hasBinary = bytes.length >= binaryStart + 8 && bytes.readUInt32LE(binaryStart + 4) === BINARY_CHUNK;
if (!hasBinary || !Array.isArray(document.buffers) || document.buffers.length === 0) {
throw new Error(`${filename}: a GLB that points at image files needs a binary chunk to hold them. Re-export it with its mesh data embedded.`);
}
const binaryLength = bytes.readUInt32LE(binaryStart);
const chunks = [padded(bytes.subarray(binaryStart + 8, binaryStart + 8 + binaryLength), 0)];
let size = chunks[0].length;
if (!Array.isArray(document.bufferViews)) document.bufferViews = [];
const embeddedByPath = new Map();
for (const image of document.images) {
if (image.uri === undefined) continue;
const segments = siblingImageSegments(filename, image.uri);
const key = segments.join('/');
if (!embeddedByPath.has(key)) {
const { imageBytes, format } = await readSibling(filename, image.uri, segments);
const imageChunk = padded(imageBytes, 0);
const total = bytes.length + (size - binaryLength) + imageChunk.length;
if (total > MAXIMUM_BYTES) throw new RangeError(`${filename}: with its images next to it the asset reaches ${total} bytes. ${assetBytesLimitMessage(total)}`);
document.bufferViews.push({ buffer: 0, byteOffset: size, byteLength: imageBytes.length });
embeddedByPath.set(key, { view: document.bufferViews.length - 1, mimeType: IMAGE_MIME[format] });
chunks.push(imageChunk);
size += imageChunk.length;
}
const embedded = embeddedByPath.get(key);
delete image.uri;
image.bufferView = embedded.view;
image.mimeType = embedded.mimeType;
}
document.buffers[0].byteLength = size;
const binary = Buffer.concat(chunks);
const json = padded(Buffer.from(JSON.stringify(document)), 0x20);
const total = 12 + 8 + json.length + 8 + binary.length;
const result = Buffer.alloc(total);
result.writeUInt32LE(0x46546c67, 0);
result.writeUInt32LE(2, 4);
result.writeUInt32LE(total, 8);
result.writeUInt32LE(json.length, 12);
result.writeUInt32LE(JSON_CHUNK, 16);
json.copy(result, 20);
const binaryOffset = 20 + json.length;
result.writeUInt32LE(binary.length, binaryOffset);
result.writeUInt32LE(BINARY_CHUNK, binaryOffset + 4);
binary.copy(result, binaryOffset + 8);
return result;
}
/** One image file below a catalog folder: a regular file, not a link, inside the folder, a real PNG, JPEG or WebP, within the byte bound. */
async function readSiblingImage(directory, glbName, uri, segments) {
const label = `${glbName}: image "${uri}"`;
// glTF resolves an image URI against the GLB's own folder, which inside a pack may be a subfolder.
const path = join(directory, dirname(glbName), ...segments);
let original;
try {
original = await lstat(path);
} catch {
throw new SkippableCatalogFileError(`${label} was not found next to the GLB. Copy that file into the GLB's folder at the same relative path.`);
}
if (!original.isFile() || original.isSymbolicLink()) throw new Error(`${label} must be a regular file, without links.`);
const resolved = await realpath(path);
const offset = relative(directory, resolved);
if (offset.startsWith(`..${sep}`) || offset === '..' || isAbsolute(offset)) throw new Error(`${label} leaves the GLB's folder. Copy the image into the folder and use a relative path.`);
if (original.size > MAXIMUM_BYTES) throw new RangeError(`${label}: ${assetBytesLimitMessage(original.size)}`);
const handle = await open(resolved, 'r');
try {
const imageBytes = Buffer.alloc(original.size);
let position = 0;
while (position < imageBytes.length) {
const result = await handle.read(imageBytes, position, imageBytes.length - position, position);
if (result.bytesRead === 0) throw new Error(`${label} was truncated during reading.`);
position += result.bytesRead;
}
const format = imageKind(imageBytes);
if (!format) throw new Error(`${label} is not a PNG, JPEG or WebP file. Convert it to one of those.`);
return { imageBytes, format };
} finally {
await handle.close();
}
}
/**
* Reads one catalog file (GLB, image, .hdr or .cube) inside a real directory: its bytes, kind and content ID. `filename` may be a
* relative path with forward slashes. A GLB whose images point at files beside it gets those images embedded, so the ID binds
* the self-contained bytes. `enforceImageLimits: false` skips the sequence frame pixel limits, for an image that is never a frame.
*/
// The preview page has no Draco decoder, so a compressed GLB is decoded here (#1698). A missing decoder or a mesh that
// grows past the size limit skips the file with the reason, so the catalog lists it instead of failing as a whole.
async function decompressedDraco(bytes, filename) {
let result;
try {
result = await decompressDracoGlb(bytes, { filename });
} catch (error) {
throw new SkippableCatalogFileError(`${filename}: ${error.message}`);
}
if (result.bytes.length > MAXIMUM_BYTES) {
throw new SkippableCatalogFileError(`${filename}: decoded from Draco the asset reaches ${result.bytes.length} bytes. ${assetBytesLimitMessage(result.bytes.length)}`);
}
return result.bytes;
}
// The preview page has no KTX2 loader, so KHR_texture_basisu images are transcoded to PNG here (#1709), with the same skip rules.
async function transcodedKtx2(bytes, filename) {
let result;
try {
result = await transcodeKtx2Glb(bytes, { filename });
} catch (error) {
throw new SkippableCatalogFileError(`${filename}: ${error.message}`);
}
if (result.bytes.length > MAXIMUM_BYTES) {
throw new SkippableCatalogFileError(`${filename}: transcoded from KTX2 the asset reaches ${result.bytes.length} bytes. ${assetBytesLimitMessage(result.bytes.length)}`);
}
return result.bytes;
}
export async function readCatalogFile(directory, filename, { enforceImageLimits = true } = {}) {
const path = join(directory, filename);
const original = await lstat(path);
if (!original.isFile() || original.isSymbolicLink()) {
throw new Error('Catalog assets must be regular files, without links.');
}
const resolved = await realpath(path);
const offset = relative(directory, resolved);
if (offset.startsWith(`..${sep}`) || offset === '..' || isAbsolute(offset) || offset.split(sep).join('/') !== filename) {
throw new Error('Asset must remain inside its configured directory.');
}
const handle = await open(resolved, 'r');
try {
const current = await handle.stat();
if (current.isFile() && current.size > MAXIMUM_BYTES) {
throw new RangeError(`${filename}: ${assetBytesLimitMessage(current.size)}`);
}
if (!current.isFile() || current.dev !== original.dev || current.ino !== original.ino || current.size < 20) {
throw new Error('Asset changed during opening or is too small to be a GLB.');
}
let bytes = Buffer.alloc(current.size);
let position = 0;
while (position < bytes.length) {
const result = await handle.read(bytes, position, bytes.length - position, position);
if (result.bytesRead === 0) throw new Error('Asset was truncated during reading.');
position += result.bytesRead;
}
const after = await handle.stat();
if (after.size !== current.size || after.mtimeMs !== current.mtimeMs || after.ctimeMs !== current.ctimeMs) {
throw new Error('Asset changed during reading.');
}
const lookKind = lookFileKind(filename, bytes);
const imageFormat = lookKind ? null : imageKind(bytes);
if (imageFormat && !IMAGE_EXTENSIONS[imageFormat].test(filename)) throw new Error('Image extension must match its PNG, JPEG or WebP content.');
// The header gives the size, so an oversized frame is refused here, before the preview page decodes its pixels.
const imageProblem = imageFormat && enforceImageLimits ? imageLimitProblem(bytes, filename, TEXTURE_SEQUENCE_LIMITS, 'Resize it before adding it to the --assets or --packs folder.') : null;
if (imageProblem) throw new SkippableCatalogFileError(imageProblem);
if (!imageFormat && !lookKind && !/\.glb$/i.test(filename)) throw new Error('Catalog files must be GLB, PNG, JPEG, WebP, HDR or CUBE, with a matching extension.');
let document = null;
if (!imageFormat && !lookKind) {
const parsed = selfContainedGlb(bytes);
document = parsed.document;
if (document.images?.some(image => Object.hasOwn(image, 'uri'))) {
const readSibling = (glbName, uri, segments) => readSiblingImage(directory, glbName, uri, segments);
bytes = await embedSiblingImages(bytes, parsed, filename, readSibling);
document = glbDocument(bytes).document;
}
if (usesDraco(document)) {
bytes = await decompressedDraco(bytes, filename);
document = glbDocument(bytes).document;
}
if (usesKtx2(document)) {
bytes = await transcodedKtx2(bytes, filename);
document = glbDocument(bytes).document;
}
}
const assetId = createHash('sha256').update(bytes).digest('hex');
return { bytes, document, assetId, imageFormat, lookKind, kind: lookKind ?? (imageFormat ? 'image' : 'glb') };
} finally {
await handle.close();
}
}
/** The catalog record of a file read by readCatalogFile; `name` is what the agent sees. */
export function describeCatalogFile(name, { bytes, document, assetId, imageFormat, lookKind }) {
if (lookKind) return Object.freeze({ assetId, name, bytes: bytes.length, kind: lookKind });
if (imageFormat) return Object.freeze({ assetId, name, bytes: bytes.length, kind: 'image', mimeType: IMAGE_MIME[imageFormat] });
const animations = document.animations ?? [];
if (!Array.isArray(animations)) throw new Error('GLB animations must be an array.');
return Object.freeze({
assetId, name, bytes: bytes.length, kind: 'glb',
meshes: document.meshes?.length ?? 0,
skins: document.skins?.length ?? 0,
images: document.images?.length ?? 0,
animationCount: animations.length,
animationsTruncated: animations.length > 16,
animations: animations.slice(0, 16).map((animation, index) => ({ index, name: clipDisplayName(animation, index).slice(0, 80) })),
});
}
/** The catalog record of a collapsed run of numbered images: pattern, first and last frame number, count and frame size. */
async function describeSequenceRun(directory, run, skipped) {
let first;
try {
first = await readCatalogFile(directory, run.names[0]);
} catch (error) {
if (!(error instanceof SkippableCatalogFileError)) throw error;
skipped.push({ name: run.pattern, reason: `first frame ${run.names[0]}: ${error.message}` });
return null;
}
const { width, height } = readImageDimensions(first.bytes);
return Object.freeze({ kind: 'sequence', name: run.pattern, first: run.first, last: run.last, frames: run.names.length, width, height });
}
const HASH_CONCURRENCY = 16;
/** Reads and hashes every frame of a sequence (a few at a time) and records each in `frameEntries`; returns the IDs in frame order. */
async function hashFrames(sequence, frameEntries) {
const frameIds = new Array(sequence.names.length);
let next = 0;
async function worker() {
while (next < sequence.names.length) {
const index = next++;
const name = sequence.names[index];
let result;
try {
result = await readCatalogFile(sequence.directory, name);
} catch (error) {
throw new error.constructor(`${sequence.metadata.name}: frame ${name}: ${error.message}`);
}
frameIds[index] = result.assetId;
if (!frameEntries.has(result.assetId)) frameEntries.set(result.assetId, { directory: sequence.directory, filename: name, metadata: describeCatalogFile(name, result) });
}
}
await Promise.all(Array.from({ length: HASH_CONCURRENCY }, worker));
return frameIds;
}
/**
* A cheap summary of the catalog files in `root` (name, size and modification time, no bytes read), so the runtime can tell whether a
* file was added, removed or rewritten since the catalog was built (#2209). Only the files the catalog lists are looked at, and at
* most as many as the catalog accepts plus one, so a huge folder costs a bounded number of stats.
*/
export async function fingerprintAssetDirectory(root) {
let directory;
let listing;
try {
directory = await realpath(root);
listing = await readdir(directory, { withFileTypes: true });
} catch {
// An unreadable folder has no fingerprint; building the catalog reports the real error with its own advice.
return 'unreadable';
}
const names = listing.filter(entry => /\.(glb|png|jpe?g|webp|hdr|cube)$/i.test(entry.name)).map(entry => entry.name).sort();
const parts = [`${names.length}`];
for (const name of names.slice(0, MAXIMUM_ASSETS + TEXTURE_SEQUENCE_LIMITS.maxFrames + 1)) {
const status = await lstat(join(directory, name)).catch(() => null);
parts.push(`${name}:${status ? `${status.size}:${status.mtimeMs}` : 'gone'}`);
}
return parts.join('|');
}
/**
* Explicit local directory catalog. IDs bind bytes, rather than agent-supplied file paths.
* `packFiles` adds the validated GLB, image, .hdr and .cube files of installed packs (scripts/agent-packs.mjs),
* each `{ directory, filename, assetId, metadata }`. With a null root only pack files are listed.
*/
export async function createAgentAssetCatalog(root, packFiles = []) {
const entries = new Map();
const skipped = [];
const sequences = new Map();
if (root !== null) {
if (typeof root !== 'string' || !isAbsolute(root)) {
throw new TypeError('Asset root must be an explicit absolute directory path.');
}
const directory = await realpath(root);
if (!(await lstat(directory)).isDirectory()) {
throw new TypeError('Asset root must be a directory.');
}
const files = (await readdir(directory, { withFileTypes: true }))
.filter(entry => /\.(glb|png|jpe?g|webp|hdr|cube)$/i.test(entry.name)).sort((left, right) => left.name.localeCompare(right.name));
// Image files are sequence frames, so they have their own cap: a film that changes a texture over time needs thousands.
const imageFileCount = files.filter(entry => IMAGE_FILE_PATTERN.test(entry.name)).length;
const otherFileCount = files.length - imageFileCount;
if (otherFileCount > MAXIMUM_ASSETS) throw new RangeError(`Asset catalog has ${otherFileCount} files other than images, over its maxAssets ${MAXIMUM_ASSETS}. Remove files from the --assets directory.`);
if (imageFileCount > TEXTURE_SEQUENCE_LIMITS.maxFrames) {
throw new RangeError(`Asset catalog has ${imageFileCount} image files, over the ${TEXTURE_SEQUENCE_LIMITS.maxFrames} a texture sequence can use. Remove images from the --assets directory.`);
}
const runs = findSequenceRuns(files.filter(file => file.isFile() && IMAGE_FILE_PATTERN.test(file.name)).map(file => file.name));
const collapsedNames = new Set(runs.flatMap(run => run.names));
for (const file of files.filter(candidate => !collapsedNames.has(candidate.name))) {
let result;
try {
result = await readCatalogFile(directory, file.name);
} catch (error) {
if (!(error instanceof SkippableCatalogFileError)) throw error;
skipped.push({ name: file.name, reason: error.message });
continue;
}
if (entries.has(result.assetId)) continue;
entries.set(result.assetId, { directory, filename: file.name, metadata: describeCatalogFile(file.name, result) });
}
for (const run of runs) {
const metadata = await describeSequenceRun(directory, run, skipped);
if (metadata) sequences.set(run.pattern, { directory, names: run.names, metadata, frameIds: null });
}
}
for (const file of packFiles) {
if (!entries.has(file.assetId)) entries.set(file.assetId, { directory: file.directory, filename: file.filename, metadata: file.metadata });
}
// The frames of collapsed sequences are hashed when a recipe names the sequence, or when a pinned frame ID is not known yet
// (a recipe from an earlier run), never at startup. The IDs go in frameEntries, which list() does not show.
const frameEntries = new Map();
const hashing = new Map();
function hashSequenceFrames(pattern) {
const sequence = sequences.get(pattern);
if (sequence.frameIds) return Promise.resolve(sequence.frameIds);
if (!hashing.has(pattern)) {
hashing.set(pattern, hashFrames(sequence, frameEntries).then(frameIds => {
sequence.frameIds = frameIds;
return frameIds;
}, error => {
hashing.delete(pattern);
throw error;
}));
}
return hashing.get(pattern);
}
async function lookupEntry(assetId) {
const known = entries.get(assetId) ?? frameEntries.get(assetId);
if (known) return known;
for (const pattern of sequences.keys()) await hashSequenceFrames(pattern);
return frameEntries.get(assetId);
}
return Object.freeze({
list() {
return { assets: structuredClone([...entries.values()].map(entry => entry.metadata)), ...(sequences.size ? { sequences: [...sequences.values()].map(sequence => ({ ...sequence.metadata })) } : {}), maximumBytes: MAXIMUM_BYTES, maximumAssets: MAXIMUM_ASSETS, ...(skipped.length ? { skipped: structuredClone(skipped) } : {}) };
},
/**
* The asset id of the GLB listed under exactly this name (a file in --assets, or `pack/file` for a pack), so a recipe can name
* a file that is re-exported often. Several GLBs under one name are refused rather than guessed.
*/
resolveName(name) {
if (typeof name !== 'string' || !name) {
throw new TypeError('asset.name must be the file name of a catalog GLB, such as "sheep_body.glb"; scene_asset_catalog lists the names.');
}
const glbs = [...entries.entries()].filter(([, entry]) => entry.metadata.kind === 'glb');
const matches = glbs.filter(([, entry]) => entry.metadata.name === name);
if (matches.length === 1) return matches[0][0];
if (matches.length > 1) {
const ids = matches.map(([assetId]) => assetId.slice(0, 12)).join(', ');
throw new Error(`${matches.length} catalog GLBs are named "${name}" (ids ${ids}). Pass asset.id with one full id from scene_asset_catalog instead of the name.`);
}
const wanted = name.toLowerCase();
const near = glbs.map(([, entry]) => entry.metadata.name)
.filter(candidate => candidate.toLowerCase().includes(wanted) || wanted.includes(candidate.toLowerCase())).slice(0, 5);
const advice = near.length ? `Near names: ${near.map(candidate => `"${candidate}"`).join(', ')}.` : 'Run scene_asset_catalog to list the names.';
throw new Error(`No catalog GLB is named "${name}". ${advice} A name must match exactly, such as "sheep_body.glb".`);
},
/**
* The frame asset IDs, in frame order, of the sequence listed under exactly this pattern (such as "frame_####.png"), so a
* recipe can write `map.sequence.catalog` instead of thousands of IDs. The frames are hashed on the first call.
*/
async resolveSequence(pattern) {
if (typeof pattern !== 'string' || !sequences.has(pattern)) {
const near = [...sequences.keys()].filter(candidate => typeof pattern === 'string' && pattern && (candidate.includes(pattern) || pattern.includes(candidate))).slice(0, 5);
const advice = near.length ? `Near patterns: ${near.map(candidate => `"${candidate}"`).join(', ')}.` : sequences.size ? 'Run scene_asset_catalog and pass the pattern of one of its sequences.' : 'The catalog lists no sequence: a run of more than 64 consecutively numbered images becomes one.';
throw new RangeError(`map.sequence.catalog must be the pattern of a catalog sequence, such as "frame_####.png"; no sequence matches ${typeof pattern === 'string' ? `"${pattern.slice(0, 80)}"` : String(pattern)}. ${advice}`);
}
return [...(await hashSequenceFrames(pattern))];
},
/**
* The length `read` returns, known from the catalog record without loading the file. A GLB whose images sit beside it is
* larger than its file on disk, because `read` embeds those images.
*/
async size(assetId) {
const entry = await lookupEntry(assetId);
if (!entry) throw new Error(`Unknown asset ID ${String(assetId).slice(0, 12)}. Call scene_asset_catalog and pass an assetId it lists.`);
return entry.metadata.bytes;
},
async read(assetId) {
const entry = await lookupEntry(assetId);
if (!entry) throw new Error(`Unknown asset ID ${String(assetId).slice(0, 12)}. Call scene_asset_catalog and pass an assetId it lists.`);
const result = await readCatalogFile(entry.directory, entry.filename);
if (result.assetId !== assetId) throw new Error('Asset bytes changed since catalog creation. Restart the runtime to refresh the catalog.');
const clipCount = result.document?.animations?.length ?? 0;
if (clipCount > AGENT_ASSET_LIMITS.maxClips) throw new RangeError(`Asset has ${clipCount} animation clips, over the catalog maxClips ${AGENT_ASSET_LIMITS.maxClips}. Remove clips from the file.`);
return result.bytes;
},
});
}