3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { currentFormatName } from './legacy-names.js';
import { mat4, mat3 } from 'gl-matrix';
import { createAgentScene, REVISION_HISTORY_LIMIT } from './agent-scene.js';
import { environmentPatchWithSetup } from './agent-look.js';
import { assetDiagnostics } from './agent-diagnostics.js';
import { fitPerspectiveDistance } from './camera.js';
import { skinnedWorldBounds, validateSkinGeometry, validateSkinPose } from './skinning.js';
import { validateMorphGeometry, validateMorphTransform } from './morph.js';
import * as agentMotion from './agent-motion.js';
import { clipDisplayName } from './clip-name.js';
import { compileClipStrip } from './clip-strip.js';
import { clipLayerContextFromAsset, retargetSourceFromAsset } from './agent-clip-layers.js';
import { retargetAssetClip, retargetReport } from './agent-retarget.js';
import { createFootLock } from './foot-lock.js';
import { clipFromGltfAnimation, createAssetLayerEvaluator, morphClipFromGltfAnimation } from './skeleton-pose.js';
import { registerAgentSceneModule, agentSceneModule } from './agent-scene-modules.js';
import { normalizeMeshEditEntries, meshEditEntriesAfter, realizeMeshEdits, meshEditSignature } from './agent-asset-mesh.js';
import { invalidField, withFieldPrefix } from './field-error.js';
registerAgentSceneModule('motion', agentMotion);
const MAX_MESH_REPORTS = 16;
const MAX_RECIPE_BYTES = 1024 * 1024;
const MAX_CHECKPOINTS = 8;
const MAX_OPERATIONS = 256;
const MAX_INSPECTION_VERTICES = 2_000_000;
const ROOT_FIELDS = ['translation', 'rotation', 'scale'];
const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor'];
const LOOK_FIELDS = ['environment', 'effects', 'shadow'];
const LOOK_OPERATIONS = Object.freeze({
'set-environment': 'environment',
'set-effects': 'effects',
'set-shadow': 'shadow',
});
export const AGENT_ASSET_CAPABILITIES = Object.freeze({
format: 'crucible.asset', schemaVersion: 1, fixedTopology: false,
operations: Object.freeze([
'set-camera', 'set-environment', 'set-effects', 'set-shadow',
'set-root', 'set-animation', 'set-material', 'set-asset-node', 'set-motion', 'set-physics', 'edit-mesh',
]),
motionDrive: 'drive {path | legs [{path, direction forward|reverse, pause}], cruiseSpeed | speed, wheels auto | [{id,node,side,axle,radius}], lights {headlights, tailLights [{material,signal brake|reverse,off,on}]}}: a car along a path; duration may be left out. scene_inspect motionDrive reports wheels, rejectedNames and light signals; docs/vehicle.md has every field',
ragdoll: 'physics {duration, floor?, ragdoll {}}: joints fall limp onto a floor at world height floor (default 0)',
boundsKind: 'authored-base-world',
});
function knownKeys(value, fields, label) {
if (!value || typeof value !== 'object' || Array.isArray(value) ||
(Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
throw invalidField(label, value, 'a plain JSON object, such as {}', TypeError);
}
for (const key of Object.keys(value)) {
if (!fields.includes(key)) {
throw invalidField(`${label}.${key}`, value[key], `no such field; use one of ${fields.join(', ')}`, TypeError);
}
}
}
function copiedJson(input) {
let bytes = 0;
const ancestors = new Set();
const encoder = new TextEncoder();
function charge(count) {
bytes += count;
if (bytes > MAX_RECIPE_BYTES) {
throw new RangeError('Asset recipe JSON exceeds 1 MiB. Reduce the input.');
}
}
function copy(value, depth) {
if (depth > 64) {
throw new RangeError('Asset recipe JSON nesting exceeds 64 levels.');
}
if (value === null || typeof value === 'boolean') {
charge(value === null ? 4 : String(value).length);
return value;
}
if (typeof value === 'number' && Number.isFinite(value) && Number.isFinite(Math.fround(value))) {
charge(String(value).length);
return value;
}
if (typeof value === 'string') {
if (value.length > MAX_RECIPE_BYTES) {
throw new RangeError('Asset recipe JSON exceeds 1 MiB.');
}
charge(encoder.encode(JSON.stringify(value)).length);
return value;
}
if (!value || typeof value !== 'object' || ancestors.has(value)) {
throw new TypeError('Asset recipe requires finite, acyclic JSON data.');
}
const array = Array.isArray(value);
if (array && (value.length > MAX_RECIPE_BYTES || Object.getPrototypeOf(value) !== Array.prototype)) {
throw new TypeError('Asset recipe arrays must be ordinary bounded JSON arrays.');
}
if (!array && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
throw new TypeError('Asset recipe objects must be plain JSON objects.');
}
ancestors.add(value);
charge(2);
const result = array ? [] : {};
for (const key of Reflect.ownKeys(value)) {
if (array && key === 'length') {
continue;
}
if (typeof key !== 'string' || key === '__proto__') {
throw new TypeError('Invalid asset recipe JSON key.');
}
const descriptor = Object.getOwnPropertyDescriptor(value, key);
if (!descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) {
throw new TypeError('Asset recipe accessors and hidden fields are unsupported.');
}
if (array && key !== String(result.length)) {
throw new TypeError('Asset recipe arrays must be dense without extra fields.');
}
charge(array ? 1 : encoder.encode(JSON.stringify(key)).length + 2);
result[key] = copy(descriptor.value, depth + 1);
}
if (array && result.length !== value.length) {
throw new TypeError('Asset recipe arrays cannot contain trailing holes.');
}
ancestors.delete(value);
return result;
}
const result = copy(input, 0);
if (encoder.encode(JSON.stringify(result)).length > MAX_RECIPE_BYTES) {
throw new RangeError('Asset recipe JSON exceeds 1 MiB.');
}
return result;
}
function vector(value, length, label) {
if (!Array.isArray(value) || value.length !== length ||
!value.every(component => typeof component === 'number' && Number.isFinite(Math.fround(component)))) {
throw invalidField(label, value, `an array of ${length} finite numbers, such as [${Array(length).fill(1).join(', ')}]`, TypeError);
}
return [...value];
}
function rootFrom(input = {}, path = 'root') {
knownKeys(input, ROOT_FIELDS, path);
const root = {
translation: vector(input.translation === undefined ? [0, 0, 0] : input.translation, 3, `${path}.translation`),
rotation: vector(input.rotation === undefined ? [0, 0, 0, 1] : input.rotation, 4, `${path}.rotation`),
scale: vector(input.scale === undefined ? [1, 1, 1] : input.scale, 3, `${path}.scale`),
};
const rotationLength = Math.hypot(...root.rotation);
if (rotationLength === 0 || root.scale.some(component => Math.fround(component) <= 0)) {
if (rotationLength === 0) {
throw invalidField(`${path}.rotation`, input.rotation, 'a quaternion that is not all zero, such as [0, 0, 0, 1]');
}
throw invalidField(`${path}.scale`, root.scale, 'positive numbers, such as [1, 1, 1]');
}
root.rotation = root.rotation.map(component => component / rotationLength);
return root;
}
function viewRecipe(input, materials = []) {
const recipe = { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials, nodes: [] };
for (const field of ['camera', ...LOOK_FIELDS]) {
if (Object.hasOwn(input, field)) {
recipe[field] = input[field];
}
}
return createAgentScene(recipe, { maxMaterials: Math.max(256, materials.length) }).exportRecipe();
}
function geometryMaxima(geometry) {
const maximum = [0, 0, 0];
for (let offset = 0; offset < geometry.positions.length; offset += 3) {
for (let axis = 0; axis < 3; axis++) {
maximum[axis] = Math.max(maximum[axis], Math.abs(geometry.positions[offset + axis]));
}
}
return maximum;
}
function localBounds(geometry) {
const minimum = [Infinity, Infinity, Infinity];
const maximum = [-Infinity, -Infinity, -Infinity];
for (let offset = 0; offset < geometry.positions.length; offset += 3) {
for (let axis = 0; axis < 3; axis++) {
minimum[axis] = Math.min(minimum[axis], geometry.positions[offset + axis]);
maximum[axis] = Math.max(maximum[axis], geometry.positions[offset + axis]);
}
}
return { min: minimum, max: maximum };
}
// Unskinned parts use their geometry bounds corners; a skinned part is measured as drawn, through its joint palette.
function framingBounds(geometryInfos, matrices, skinnedParts = []) {
const minimum = [Infinity, Infinity, Infinity];
const maximum = [-Infinity, -Infinity, -Infinity];
for (let index = 0; index < geometryInfos.length; index++) {
const skinned = skinnedParts[index];
if (skinned) {
const drawn = skinnedWorldBounds(skinned.geometry, skinned.skin, matrices[index]);
for (let axis = 0; axis < 3; axis++) {
minimum[axis] = Math.min(minimum[axis], drawn.minimum[axis]);
maximum[axis] = Math.max(maximum[axis], drawn.maximum[axis]);
}
continue;
}
const bounds = geometryInfos[index].bounds;
const matrix = matrices[index];
for (let corner = 0; corner < 8; corner++) {
const point = bounds.min.map((component, axis) => corner & (1 << axis) ? bounds.max[axis] : component);
for (let axis = 0; axis < 3; axis++) {
const value = matrix[axis] * point[0] + matrix[axis + 4] * point[1] +
matrix[axis + 8] * point[2] + matrix[axis + 12];
minimum[axis] = Math.min(minimum[axis], value);
maximum[axis] = Math.max(maximum[axis], value);
}
}
}
return { min: minimum, max: maximum };
}
function validatePositionBounds(maxima, world, skin) {
for (let row = 0; row < 4; row++) {
let coordinateBound = 0;
for (let column = 0; column < 4; column++) {
let coefficient = Math.abs(world[column * 4 + row]);
if (skin) {
coefficient = 0;
for (let axis = 0; axis < 4; axis++) {
let paletteBound = 0;
for (let offset = column * 4 + axis; offset < skin.jointMatrices.length; offset += 16) {
paletteBound = Math.max(paletteBound, Math.abs(skin.jointMatrices[offset]));
}
coefficient += Math.abs(world[axis * 4 + row]) * paletteBound * (1 + 2 ** -21);
if (!Number.isFinite(Math.fround(coefficient))) {
throw new RangeError('Asset world/skin matrix products exceed Float32 range.');
}
}
}
coordinateBound += coefficient * (column === 3 ? 1 : maxima[column]);
if (!Number.isFinite(Math.fround(coordinateBound))) {
throw new RangeError('Asset world geometry bounds exceed Float32 range.');
}
}
}
}
function baseBounds(geometries, matrices) {
const minimum = [Infinity, Infinity, Infinity];
const maximum = [-Infinity, -Infinity, -Infinity];
for (let index = 0; index < geometries.length; index++) {
const positions = geometries[index].positions;
const matrix = matrices[index];
for (let offset = 0; offset < positions.length; offset += 3) {
for (let axis = 0; axis < 3; axis++) {
const value = matrix[axis] * positions[offset] + matrix[4 + axis] * positions[offset + 1] +
matrix[8 + axis] * positions[offset + 2] + matrix[12 + axis];
minimum[axis] = Math.min(minimum[axis], value);
maximum[axis] = Math.max(maximum[axis], value);
}
}
}
return { min: minimum, max: maximum };
}
function framedCamera(bounds) {
const target = bounds.min.map((component, axis) => (component + bounds.max[axis]) / 2);
const radius = Math.hypot(...bounds.max.map((component, axis) => (component - bounds.min[axis]) / 2));
const near = Math.max(0.001, radius * 0.001);
const far = Math.max(10, radius * 10);
const probeDistance = Math.max(1, radius);
const directionLength = Math.hypot(4, 3, 5);
const direction = [4, 3, 5].map(component => component / directionLength);
const camera = {
target, eye: target.map((component, axis) => component + direction[axis] * probeDistance),
up: [0, 1, 0], fov: 45, near, far,
};
const distance = fitPerspectiveDistance({ minimum: bounds.min, maximum: bounds.max }, camera, 1, 1.2);
camera.eye = target.map((component, axis) => component + direction[axis] * distance);
return camera;
}
/** Own authoring state around one exclusively owned, decoded parseGltf asset. */
export function createAgentAssetScene(asset, inputRecipe, { sources } = {}) {
if (!asset || !Array.isArray(asset.parts) || !Array.isArray(asset.animations) ||
typeof asset.stagePose !== 'function' || !Array.isArray(asset.nodes)) {
throw new TypeError('createAgentAssetScene requires a decoded parseGltf asset.');
}
if (!asset.parts.length) {
throw new TypeError('This file has no meshes, so there is nothing to draw. A skeleton-only file works as a clip source: set motion.layers[].from on a character that has a mesh.');
}
if (asset.parts.length > 4096 || asset.animations.length > 256 ||
new Set(asset.parts.map(part => part.material)).size > 4096) {
throw new RangeError('Asset budgets allow 4096 parts, 4096 materials, and 256 animation clips.');
}
const sourceParts = [...asset.parts];
const materials = new Map();
const geometries = new Map();
const morphMetadata = new Map();
const records = sourceParts.map((source, index) => {
if (!materials.has(source.material)) {
const id = `material-${materials.size}`;
const baseline = {};
for (const field of MATERIAL_FIELDS) {
const value = source.material[field];
if (value !== undefined) {
baseline[field] = Array.isArray(value) ? [...value] : value;
}
}
materials.set(source.material, { id, baseline });
}
if (!geometries.has(source.geometry)) {
const metadata = validateMorphGeometry(source.geometry, source.morph);
if (metadata) {
morphMetadata.set(source.geometry, metadata);
}
geometries.set(source.geometry, {
id: `geometry-${geometries.size}`, maxima: geometryMaxima(source.geometry), bounds: localBounds(source.geometry),
});
}
validateSkinGeometry(source.geometry, source.skin);
return {
id: `mesh-${index}`, label: String(source.name ?? `Mesh ${index}`).slice(0, 256), source,
geometry: geometries.get(source.geometry), material: materials.get(source.material),
sourceMatrix: source.matrix, jointMatrices: source.skin?.jointMatrices,
jointWorldMatrices: source.skin?.jointWorldMatrices, morphWeights: source.morph?.weights,
};
});
const materialRecords = new Map([...materials.values()].map(record => [record.id, record]));
const sourceNodes = new Map(asset.nodes.map(node => [node.id, structuredClone(node)]));
const clipLayerContext = clipLayerContextFromAsset(asset.animations, [...sourceNodes.values()]);
/** Other catalog assets whose clips layers may retarget, by asset ID: decoded `{ animations, nodes }`. */
function provideMotionSources(decodedSources) {
for (const [sourceId, decoded] of Object.entries(decodedSources ?? {})) {
if (/^[a-f0-9]{64}$/i.test(sourceId)) clipLayerContext.external.set(sourceId.toLowerCase(), retargetSourceFromAsset(decoded));
}
}
provideMotionSources(sources);
// Morph targets by the names the file gives them, so motion can key a weight by name; defaults fill a part no layer drives.
const morphTargetIndex = new Map();
const morphDefaults = sourceParts.map(part => (part.morph ? Float32Array.from(part.morph.weights) : null));
sourceParts.forEach((part, partIndex) => {
(part.morphTargetNames ?? []).forEach((name, index) => {
if (!morphTargetIndex.has(name)) morphTargetIndex.set(name, []);
morphTargetIndex.get(name).push({ part: partIndex, index });
});
});
const initialRecipe = copiedJson(inputRecipe);
const assetId = initialRecipe?.assetId;
if (typeof assetId !== 'string' || !/^[a-f0-9]{64}$/i.test(assetId)) {
throw invalidField('assetId', assetId, '64 hexadecimal characters, such as "ab12..." (the SHA256 that scene_create_asset returned)', TypeError);
}
const canonicalAssetId = assetId.toLowerCase();
const cameraOmitted = !Object.hasOwn(initialRecipe, 'camera');
let recipe;
let materialSnapshots = new Map();
let matrices = [];
let revision = 0;
let sampler = null;
let physicsSampler = null;
let physicsBake = null;
let layerEvaluator = null;
let footLockEvaluator = null;
let motionTime = null;
let sampledCamera;
const checkpoints = new Map();
// Earlier recipes, oldest first. A published recipe is never edited in place, so the reference is a safe snapshot.
const revisionHistory = [];
const materialOutputs = new Map([...materials].map(([source, record]) => {
const output = {};
for (const [field, value] of Object.entries(source)) {
if (!MATERIAL_FIELDS.includes(field)) {
output[field] = Array.isArray(value) ? Object.freeze([...value]) : value;
}
}
for (const field of MATERIAL_FIELDS) {
Object.defineProperty(output, field, {
enumerable: true,
get() {
return materialSnapshots.get(record.id)[field];
},
});
}
return [record.id, Object.freeze(output)];
}));
// Parts of edited meshes carry rebuilt geometry. The matrices stay the same arrays, so poses keep writing to them.
const partMatrices = records.map(record => new Float32Array(record.source.matrix));
let editedParts = new Map();
let editSignature = meshEditSignature(editedParts);
let topologyRevision = 0;
/** A part by its ID (mesh-3); anything else that is not a source node is an unknown ID. */
function partRecordFor(id) {
const record = records.find(value => value.id === id);
if (!record) {
throw invalidField('geometry', id, 'an imported mesh ID such as "mesh-0", or a source node ID; call scene_inspect without ids to list the meshes, or with kind hierarchy for source nodes');
}
return record;
}
/** The parts scene_inspect lists for one ID: a mesh ID is that part; a source node is every part of it and of the nodes below it. */
function inspectedRecordsFor(id, originNodes = new Map()) {
const sourceNode = sourceNodes.get(id);
if (!sourceNode || records.some(value => value.id === id)) {
return [partRecordFor(id)];
}
const found = collectNodeRecords(id);
for (const record of found) {
if (!record.isSourceNodeReport) {
originNodes.set(record.id, id);
}
}
return found;
}
/** A source node with no part anywhere below it (a joint or an empty): its transform at rest, so an agent can aim at it or pose it. */
function sourceNodeReport(sourceNode) {
const world = mat4.create();
const chain = [];
for (let current = sourceNode; current; current = current.parent ? sourceNodes.get(current.parent) : null) {
chain.unshift(current);
}
for (const link of chain) {
mat4.multiply(world, world, mat4.fromRotationTranslationScale(mat4.create(), link.rotation, link.translation, link.scale));
}
return {
isSourceNodeReport: true, id: sourceNode.id, label: sourceNode.label, name: sourceNode.name, parent: sourceNode.parent,
joint: Boolean(sourceNode.joint), translation: [...sourceNode.translation], rotation: [...sourceNode.rotation], scale: [...sourceNode.scale],
restWorldPosition: [world[12], world[13], world[14]], meshIds: [],
};
}
/** Every part of a source node and of the nodes below it; with no part anywhere below it, the node's own report. */
function collectNodeRecords(id) {
const partIds = [];
const pending = [id];
while (pending.length > 0) {
const nodeId = pending.pop();
partIds.push(...(sourceNodes.get(nodeId).meshIds ?? []));
pending.push(...[...sourceNodes.values()].filter(node => node.parent === nodeId).map(node => node.id));
}
if (partIds.length === 0) {
return [sourceNodeReport(sourceNodes.get(id))];
}
return records.filter(value => partIds.includes(value.id));
}
function geometryOf(record, edited = editedParts) {
return edited.get(record.id)?.geometry ?? record.source.geometry;
}
function geometryInfoOf(record, edited = editedParts) {
return edited.get(record.id)?.info ?? record.geometry;
}
function morphMetadataOf(record, edited = editedParts) {
return edited.get(record.id)?.morphMetadata ?? morphMetadata.get(record.source.geometry);
}
function describeGeometry(geometry) {
return { maxima: geometryMaxima(geometry), bounds: localBounds(geometry) };
}
function buildParts(edited) {
return Object.freeze(records.map((record, index) => {
const part = {
name: record.id, geometry: geometryOf(record, edited),
matrix: partMatrices[index], material: materialOutputs.get(record.material.id),
};
if (record.source.skin) {
part.skin = record.source.skin;
}
if (record.source.morph) {
part.morph = record.source.morph;
}
if (record.source.castShadow !== undefined) {
part.castShadow = record.source.castShadow;
}
return Object.freeze(part);
}));
}
let parts = buildParts(editedParts);
const capabilities = Object.freeze({
...AGENT_ASSET_CAPABILITIES,
animations: asset.animations.length,
skinning: parts.some(part => Boolean(part.skin)),
morphTargets: parts.some(part => Boolean(part.morph)),
textures: [...materialOutputs.values()].some(material => Boolean(material.map || material.normalMap ||
material.metallicRoughnessMap || material.occlusionMap || material.emissiveMap)),
});
function normalize(input) {
const candidate = copiedJson(input);
knownKeys(candidate, ['format', 'schemaVersion', 'assetId', 'camera', ...LOOK_FIELDS, 'root', 'animation', 'materialOverrides', 'nodeOverrides', 'motion', 'physics', 'meshEdits'], 'asset recipe');
candidate.format = currentFormatName(candidate.format);
if (candidate.format !== 'crucible.asset' || candidate.schemaVersion !== 1 ||
typeof candidate.assetId !== 'string' || candidate.assetId.toLowerCase() !== canonicalAssetId) {
const wrongField = candidate.format !== 'crucible.asset' ? 'format' : candidate.schemaVersion !== 1 ? 'schemaVersion' : 'assetId';
const expectedValue = wrongField === 'format' ? '"crucible.asset"' : wrongField === 'schemaVersion' ? '1' : `the bound asset ID, such as "${canonicalAssetId.slice(0, 8)}..."`;
throw invalidField(wrongField, candidate[wrongField], expectedValue);
}
const overrides = candidate.materialOverrides === undefined ? [] : candidate.materialOverrides;
if (!Array.isArray(overrides) || overrides.length > materialRecords.size) {
throw invalidField('materialOverrides', Array.isArray(overrides) ? `${overrides.length} entries` : overrides, `an array of at most ${materialRecords.size} entries, one per decoded material, such as []`);
}
const seen = new Set();
const definitions = overrides.map((override, index) => {
knownKeys(override, ['id', ...MATERIAL_FIELDS], `materialOverrides[${index}]`);
const original = materialRecords.get(override.id);
if (!original || seen.has(override.id)) {
throw invalidField(`materialOverrides[${index}].id`, override.id, `the ID of a decoded material, used once; one of ${[...materialRecords.keys()].slice(0, 5).join(', ')}`);
}
seen.add(override.id);
return { id: override.id, ...original.baseline, ...override };
});
const view = viewRecipe(candidate, definitions);
const normalizedOverrides = view.materials.map(material => {
const result = { id: material.id };
for (const field of MATERIAL_FIELDS) {
if (material[field] !== undefined) {
result[field] = material[field];
}
}
return result;
});
const animation = candidate.animation === undefined ? null : candidate.animation;
if (animation !== null) {
knownKeys(animation, ['clip', 'time'], 'animation');
const clipCount = asset.animations.length;
const clip = asset.animations[animation.clip];
if (!Number.isInteger(animation.clip) || !clip || !Number.isFinite(animation.time) ||
animation.time < 0 || animation.time > clip.duration) {
if (!Number.isInteger(animation.clip) || !clip) {
throw invalidField('animation.clip', animation.clip, clipCount === 0 ? 'no animation, since this asset has no clips; drop it, such as null' : `a clip index from 0 to ${clipCount - 1}, such as 0`);
}
throw invalidField('animation.time', animation.time, `seconds from 0 to ${clip.duration}, such as 0`);
}
}
const nodeOverrides = candidate.nodeOverrides === undefined ? [] : candidate.nodeOverrides;
if (!Array.isArray(nodeOverrides) || nodeOverrides.length > sourceNodes.size) {
throw invalidField('nodeOverrides', Array.isArray(nodeOverrides) ? `${nodeOverrides.length} entries` : nodeOverrides, `an array of at most ${sourceNodes.size} entries, one per source node, such as []`);
}
const seenNodes = new Set();
const normalizedNodes = nodeOverrides.map((override, index) => {
knownKeys(override, ['id', ...ROOT_FIELDS], `nodeOverrides[${index}]`);
const node = sourceNodes.get(override.id);
if (!node || seenNodes.has(override.id) || !node.editable) {
throw invalidField(`nodeOverrides[${index}].id`, override.id, 'the ID of an editable source node, used once; call scene_inspect with kind hierarchy to list them');
}
seenNodes.add(override.id);
const fields = Object.keys(override).filter(field => field !== 'id');
if (!fields.length) {
throw invalidField(`nodeOverrides[${index}]`, override, 'an id plus at least one of translation, rotation or scale, such as { "id": "node-1", "translation": [0, 1, 0] }');
}
const transform = rootFrom(Object.fromEntries(fields.map(field => [field, override[field]])), `nodeOverrides[${index}]`);
return { id: override.id, ...Object.fromEntries(fields.map(field => [field, transform[field]])) };
});
const result = copiedJson({
format: 'crucible.asset', schemaVersion: 1, assetId: canonicalAssetId,
camera: view.camera, environment: view.environment, effects: view.effects, shadow: view.shadow,
root: rootFrom(candidate.root), animation, materialOverrides: normalizedOverrides, nodeOverrides: normalizedNodes,
});
const meshEdits = normalizeMeshEditEntries(candidate.meshEdits, records);
if (meshEdits.length) {
result.meshEdits = meshEdits;
}
if ((candidate.motion?.ik?.length || candidate.motion?.springs || candidate.motion?.footLock) && Math.max(...result.root.scale) - Math.min(...result.root.scale) > 1e-3 * Math.max(...result.root.scale)) {
throw invalidField('root.scale', result.root.scale, 'the same number on every axis, such as [1, 1, 1], because motion ik, springs and footLock need a uniform asset root scale');
}
result.motion = agentMotion.normalizeAgentMotion(candidate.motion, motionRecipe(result));
if (candidate.physics !== undefined && candidate.physics !== null) {
result.physics = agentSceneModule('physics').normalizeAssetPhysics(candidate.physics);
}
return copiedJson(result);
}
/** The drive of motion.drive for this asset. Built once per distinct entry: the rig and the speed profile cost a simulation. */
const builtDrives = new Map();
function buildDrive(drive) {
const key = JSON.stringify(drive);
if (!builtDrives.has(key)) {
builtDrives.set(key, agentSceneModule('drive').createAssetDrive(asset, drive, { materialIds: new Set(materialRecords.keys()) }));
}
return builtDrives.get(key);
}
function motionRecipe(candidate) {
const baselines = new Map([...materialRecords].map(([id, record]) => [id, { id, ...record.baseline }]));
for (const override of candidate.materialOverrides) {
baselines.set(override.id, { ...baselines.get(override.id), ...override });
}
const root = candidate.root;
return {
nodes: [...sourceNodes.values()].filter(node => node.editable),
materials: [...baselines.values()], camera: candidate.camera,
buildDrive, normalizeDrive: (input, path) => agentSceneModule('drive').normalizeDrive(input, path), ikHierarchy: [...sourceNodes.values()], clipLayerContext, morphTargets: [...morphTargetIndex.keys()],
ikRootMatrix: Array.from(mat4.fromRotationTranslationScale(mat4.create(), root.rotation, root.translation, [root.scale[0], root.scale[0], root.scale[0]])),
};
}
/** Stage clip and overrides without publishing them, and read the local pose IK must start from. */
function stagedNodePoses(animation, overrides) {
const probe = asset.stagePose({ animation, nodeOverrides: overrides });
try {
return probe.nodePoses();
} finally {
probe.discard();
}
}
/** A clip of another catalog asset moved onto this asset's rest pose. Cached: the same layer always gives the same clip. */
const retargetedClips = new Map();
function retargetedLayerClip(layer, loop) {
const key = JSON.stringify([layer.from, layer.scale, layer.rootMotion, loop]);
if (!retargetedClips.has(key)) {
const source = clipLayerContext.external.get(layer.from.asset);
const sourceClip = clipFromGltfAnimation(source.animations[layer.from.clip], { loop });
retargetedClips.set(key, retargetAssetClip(source.nodes, asset.nodes, sourceClip, { scale: layer.scale, rootMotion: layer.rootMotion }));
}
return retargetedClips.get(key);
}
/** Foot lock over the motion's layers, or null when the motion does not ask for it. */
function compileFootLock(candidate) {
const motion = candidate.motion;
if (!motion?.footLock) return null;
return createFootLock({
settings: motion.footLock, nodes: asset.nodes, rootMatrix: motionRecipe(candidate).ikRootMatrix,
layers: layerDefinitions(motion.layers), duration: motion.duration, loop: motion.loop,
});
}
/** Weights keyed by morph target name replace what layers or the file's defaults give those targets. */
function keyedMorphWeights(layerWeights, keyed) {
if (!keyed?.size) return layerWeights;
const byPart = new Map(layerWeights.map(({ part, weights }) => [part, weights]));
for (const [name, patch] of keyed) {
for (const { part, index } of morphTargetIndex.get(name) ?? []) {
if (!byPart.has(part)) byPart.set(part, Array.from(morphDefaults[part]));
byPart.get(part)[index] = patch.weight;
}
}
return [...byPart].map(([part, weights]) => ({ part, weights }));
}
/**
* A strip times its layer: the fade envelope multiplies the layer's weight and the strip maps motion time to clip
* time. The clip holds its ends, since the strip does the repeating.
*/
function stripTiming(layer) {
if (!layer.strip) return { loop: layer.loop !== false, timing: {} };
const duration = layer.from ? clipLayerContext.external.get(layer.from.asset).clips[layer.from.clip].duration : asset.animations[layer.clip].duration;
const compiled = compileClipStrip(layer.strip, duration);
const base = layer.weight ?? 1;
return { loop: false, timing: { weight: time => base * compiled.weight(time), clipTime: compiled.clipTime } };
}
/** Layers of the motion as definitions for the pose code: decoded clips, renamed by `bones`, with their morph tracks. */
function layerDefinitions(layers) {
return layers.map(layer => {
const { loop, timing } = stripTiming(layer);
const common = { weight: layer.weight, speed: layer.speed, offset: layer.offset, additive: layer.additive, reference: layer.reference, mask: layer.mask, ...timing };
if (layer.from) return { clip: retargetedLayerClip(layer, loop), ...common };
const animation = asset.animations[layer.clip];
return {
clip: clipFromGltfAnimation(animation, { loop, rename: layer.bones }),
...(layer.morph === false ? {} : { morphs: morphClipFromGltfAnimation(animation, { loop }) }),
...common,
};
});
}
/** Evaluates the motion's clip layers at a time, or null when it has none. Stateless, so a seek equals playing. */
function compileLayers(motion) {
return motion?.layers?.length ? createAssetLayerEvaluator(asset, layerDefinitions(motion.layers)) : null;
}
/** Where tracks, layers and the recipe's own overrides meet: the recipe's overrides, then layers, then tracks on top. */
function poseOverrides(baseOverrides, layerEvaluator, sampled, time) {
const layered = layerEvaluator?.evaluate(time);
const withLayers = new Map(baseOverrides.map(override => [override.id, override]));
for (const override of layered?.nodeOverrides ?? []) {
withLayers.set(override.id, { ...withLayers.get(override.id), ...override });
}
return { nodeOverrides: trackOverrides([...withLayers.values()], sampled), morphWeights: keyedMorphWeights(layered?.morphWeights ?? [], sampled?.morphs) };
}
function trackOverrides(baseOverrides, sampled) {
const nodeOverrides = new Map(baseOverrides.map(override => [override.id, override]));
for (const [id, patch] of sampled?.nodes ?? []) {
const copiedPatch = Object.fromEntries(Object.entries(patch).map(([field, value]) => [field, Array.from(value)]));
nodeOverrides.set(id, { ...nodeOverrides.get(id), id, ...copiedPatch });
}
return nodeOverrides;
}
/** A ragdoll bake costs a solver run, so an unchanged section on an unchanged starting pose reuses the last one. */
function stageAssetPhysics(candidate) {
if (!candidate.physics) return null;
const key = JSON.stringify([candidate.physics, candidate.animation, candidate.nodeOverrides, candidate.root]);
if (physicsBake?.key !== key) {
const root = candidate.root;
const rootMatrix = mat4.fromRotationTranslationScale(mat4.create(), root.rotation, root.translation, root.scale);
const startingPoses = stagedNodePoses(candidate.animation, candidate.nodeOverrides);
physicsBake = { key, sampler: agentSceneModule('physics').bakeAssetRagdoll(candidate.physics, [...sourceNodes.values()], startingPoses, rootMatrix) };
}
return physicsBake.sampler;
}
/** Joint poses from the ragdoll at a time. Physics holds its last pose after its duration. */
function ragdollOverrides(stagedPhysics, time) {
const patches = stagedPhysics.sample(Math.min(time, stagedPhysics.duration));
return [...patches].map(([id, patch]) => ({ id, translation: Array.from(patch.translation), rotation: Array.from(patch.rotation) }));
}
function publish(input, autoFrame = false, increment = true, transientTime = undefined, transientAnimation = undefined) {
let candidate = transientTime === undefined ? normalize(input) : recipe;
if (transientAnimation !== undefined) {
candidate = { ...candidate, animation: transientAnimation };
}
let stagedSampler = transientTime === undefined ? agentMotion.compileAgentMotion(candidate.motion, motionRecipe(candidate)) : sampler;
const stagedLayers = transientTime === undefined ? compileLayers(candidate.motion) : layerEvaluator;
const stagedFootLock = transientTime === undefined ? compileFootLock(candidate) : footLockEvaluator;
const stagedPhysics = transientTime === undefined ? stageAssetPhysics(candidate) : physicsSampler;
const targetTime = transientTime === undefined ? (candidate.motion || candidate.physics ? 0 : null) : transientTime;
if (targetTime !== null && !stagedSampler && !stagedPhysics) {
throw new RangeError('The asset has no authored motion or physics to sample.');
}
let sampled = targetTime === null ? null : stagedSampler?.sample(targetTime);
if (asset.parts.length !== records.length) {
throw new RangeError('Decoded part membership must remain fixed.');
}
const stagedEdits = realizeMeshEdits(candidate.meshEdits ?? [], records, editedParts, describeGeometry);
for (let index = 0; index < records.length; index++) {
const record = records[index];
const source = record.source;
if (asset.parts[index] !== source || geometryOf(record) !== parts[index].geometry ||
source.skin !== parts[index].skin || source.morph !== parts[index].morph ||
source.matrix !== record.sourceMatrix || source.skin?.jointMatrices !== record.jointMatrices ||
source.skin?.jointWorldMatrices !== record.jointWorldMatrices || source.morph?.weights !== record.morphWeights ||
parts[index].matrix.length !== 16 || parts[index].matrix.byteLength !== 64) {
throw new RangeError('Decoded resources and retained adapter matrices must not change identity or detach.');
}
}
const { nodeOverrides, morphWeights } = poseOverrides(candidate.nodeOverrides, targetTime === null ? null : stagedLayers, sampled, targetTime);
if (targetTime !== null && stagedFootLock) {
const nodePoses = stagedNodePoses(candidate.animation, [...nodeOverrides.values()]);
for (const override of stagedFootLock.solve(targetTime, nodePoses)) {
if (sourceNodes.get(override.id)?.editable) nodeOverrides.set(override.id, { ...nodeOverrides.get(override.id), ...override });
}
}
if (targetTime !== null && stagedSampler?.ikUsesStagedPose) {
const nodePoses = stagedNodePoses(candidate.animation, [...nodeOverrides.values()]);
for (const override of stagedSampler.solveStagedPose(targetTime, nodePoses)) {
nodeOverrides.set(override.id, { ...nodeOverrides.get(override.id), ...override });
}
}
if (targetTime !== null && stagedPhysics) {
for (const override of ragdollOverrides(stagedPhysics, targetTime)) {
nodeOverrides.set(override.id, { ...nodeOverrides.get(override.id), ...override });
}
}
let transaction;
try {
transaction = asset.stagePose({ animation: candidate.animation, nodeOverrides: [...nodeOverrides.values()], morphWeights });
const rootMatrix = mat4.fromRotationTranslationScale(mat4.create(), candidate.root.rotation, candidate.root.translation, candidate.root.scale);
const normal = mat3.create();
const stagedMatrices = records.map((record, index) => {
const posed = transaction.parts[index];
const world = mat4.multiply(mat4.create(), rootMatrix, posed.matrix);
const determinant = mat4.determinant(world);
if (!world.every(Number.isFinite) || !Number.isFinite(determinant) || determinant === 0 ||
!mat3.normalFromMat4(normal, world) || !normal.every(Number.isFinite)) {
throw new RangeError('Asset root/world matrices must remain finite and nonsingular at Float32 precision.');
}
if (posed.skin) {
validateSkinPose(posed.skin, geometryOf(record, stagedEdits), world);
}
if (posed.morph) {
validateMorphTransform(posed.morph, morphMetadataOf(record, stagedEdits), world, posed.skin);
} else {
validatePositionBounds(geometryInfoOf(record, stagedEdits).maxima, world, posed.skin);
}
return world;
});
if (autoFrame) {
candidate.camera = framedCamera(framingBounds(
records.map(record => geometryInfoOf(record, stagedEdits)),
stagedMatrices,
records.map((record, index) => transaction.parts[index].skin ? { geometry: geometryOf(record, stagedEdits), skin: transaction.parts[index].skin } : null),
));
candidate = normalize(candidate);
stagedSampler = agentMotion.compileAgentMotion(candidate.motion, motionRecipe(candidate));
sampled = targetTime === null ? null : stagedSampler?.sample(targetTime);
}
const stagedMaterials = new Map([...materialRecords].map(([id, record]) => [id, { ...record.baseline }]));
for (const override of candidate.materialOverrides) {
stagedMaterials.set(override.id, { ...stagedMaterials.get(override.id), ...override });
}
for (const [id, patch] of sampled?.materials ?? []) {
const copiedPatch = Object.fromEntries(Object.entries(patch).map(([field, value]) => [field, typeof value === 'number' ? value : Array.from(value)]));
stagedMaterials.set(id, { ...stagedMaterials.get(id), ...copiedPatch });
}
for (const snapshot of stagedMaterials.values()) {
for (const field of ['color', 'emissiveColor']) {
if (snapshot[field]) {
Object.freeze(snapshot[field]);
}
}
Object.freeze(snapshot);
}
const stagedCamera = sampled?.camera ? {
...candidate.camera,
...Object.fromEntries(Object.entries(sampled.camera).filter(([field]) => field !== 'projection').map(([field, value]) => [field, ArrayBuffer.isView(value) ? Array.from(value) : value])),
} : candidate.camera;
// Validate camera geometry through the same canonical view contract.
viewRecipe({ camera: stagedCamera });
const preparedTransaction = transaction;
transaction = null;
preparedTransaction.commit();
for (let index = 0; index < parts.length; index++) {
Float32Array.prototype.set.call(parts[index].matrix, stagedMatrices[index]);
}
const stagedSignature = meshEditSignature(stagedEdits);
if (stagedSignature !== editSignature) {
editedParts = stagedEdits;
editSignature = stagedSignature;
parts = buildParts(editedParts);
topologyRevision++;
}
const previousRecipe = recipe;
if (transientTime === undefined) {
recipe = candidate;
sampler = stagedSampler;
physicsSampler = stagedPhysics;
layerEvaluator = stagedLayers;
footLockEvaluator = stagedFootLock;
}
materialSnapshots = stagedMaterials;
sampledCamera = stagedCamera;
motionTime = targetTime;
if (transientTime === undefined) {
matrices = stagedMatrices;
}
if (increment) {
if (transientTime === undefined) {
revisionHistory.push({ revision, recipe: previousRecipe });
while (revisionHistory.length > REVISION_HISTORY_LIMIT) {
revisionHistory.shift();
}
}
revision++;
}
return revision;
} catch (error) {
transaction?.discard();
throw error;
}
}
/** scene_inspect's motionIk: how each solver fares across the clip, from a sampler that leaves the published pose alone. */
function diagnosticsReport() {
const diagnostics = assetDiagnostics({
assetId: canonicalAssetId,
warnings: asset.warnings,
skinnedParts: records.filter(record => record.source.skin).length,
jointCount: [...sourceNodes.values()].filter(node => node.joint).length,
clipCount: asset.animations.length,
});
return diagnostics.length ? { diagnostics } : {};
}
/** scene_inspect's retargets (what the humanoid map matched for each layer taken from another asset), footLock (when feet are planted) and morph target names. */
function motionLayerReport() {
const retargets = (recipe.motion?.layers ?? []).flatMap((layer, position) => (layer.from
? [{ layer: position, from: layer.from, ...retargetReport(clipLayerContext.external.get(layer.from.asset).nodes, [...sourceNodes.values()], 'retarget') }]
: []));
return {
...(retargets.length ? { retargets } : {}),
...(footLockEvaluator ? { footLock: footLockEvaluator.report() } : {}),
...(morphTargetIndex.size ? { morphTargetNames: [...morphTargetIndex.keys()].slice(0, 128) } : {}),
};
}
/** scene_inspect's motionDrive: the wheels found, the names rejected and the light signals at the current motion time. */
function motionDriveReport() {
if (!recipe.motion?.drive) return {};
const drive = buildDrive(recipe.motion.drive);
return { motionDrive: drive.describe(motionTime === null ? undefined : drive.sample(motionTime).pose) };
}
function motionIkReport() {
if (!recipe.motion?.ik?.length) return {};
const sweeper = agentMotion.compileAgentMotion(recipe.motion, motionRecipe(recipe));
return {
motionIk: sweeper.sweepIk(time => stagedNodePoses(recipe.animation, [...poseOverrides(recipe.nodeOverrides, layerEvaluator, sweeper.sample(time), time).nodeOverrides.values()])),
};
}
function expected(options) {
knownKeys(options, ['expectedRevision'], 'transaction options');
if (!Number.isSafeInteger(options.expectedRevision) || options.expectedRevision !== revision) {
throw invalidField('expectedRevision', options.expectedRevision, `the current revision, such as ${revision}`);
}
}
publish(initialRecipe, cameraOmitted, false);
return Object.freeze({
capabilities,
get parts() {
return parts;
},
get revision() {
return revision;
},
get topologyRevision() {
return topologyRevision;
},
get camera() {
return structuredClone(sampledCamera);
},
get motionTime() {
return motionTime;
},
get environment() {
return structuredClone(recipe.environment);
},
get effects() {
return structuredClone(recipe.effects);
},
get shadow() {
return structuredClone(recipe.shadow);
},
exportRecipe() {
return structuredClone(recipe);
},
provideMotionSources,
sampleMotion(time) {
if (time !== null && (!Number.isFinite(time) || time < 0 || time > 3600)) {
throw invalidField('motionTime', time, 'null, or seconds from 0 to 3600, such as 0.5');
}
publish(recipe, false, false, time);
return motionTime;
},
sampleFrame(input) {
const frame = copiedJson(input);
knownKeys(frame, ['animation', 'motionTime'], 'asset frame');
const time = frame.motionTime === undefined ? motionTime : frame.motionTime;
if (time !== null && (!Number.isFinite(time) || time < 0 || time > 3600)) {
throw invalidField('motionTime', time, 'null, or seconds from 0 to 3600, such as 0.5');
}
publish(recipe, false, false, time, frame.animation);
return motionTime;
},
apply(inputOperations, options = {}) {
expected(options);
if (!Array.isArray(inputOperations) || !inputOperations.length || inputOperations.length > MAX_OPERATIONS) {
throw invalidField('operations', Array.isArray(inputOperations) ? `${inputOperations.length} commands` : inputOperations, `an array of 1 to ${MAX_OPERATIONS} commands, such as [{ "type": "set-root", "translation": [0, 1, 0] }]`);
}
const operations = copiedJson(inputOperations);
const candidate = structuredClone(recipe);
for (const [operationIndex, operation] of operations.entries()) {
const path = `operations[${operationIndex}]`;
const lookField = Object.hasOwn(LOOK_OPERATIONS, operation.type) ? LOOK_OPERATIONS[operation.type] : null;
if (lookField) {
knownKeys(operation, ['type', lookField], path);
const patch = operation[lookField];
knownKeys(patch, Object.keys(candidate[lookField]), lookField);
const nested = lookField === 'environment' ? 'volumeFog' : lookField === 'effects' ? 'bloom' : null;
const merged = { ...candidate[lookField], ...(lookField === 'environment' ? environmentPatchWithSetup(patch) : patch) };
if (nested && Object.hasOwn(patch, nested)) {
knownKeys(patch[nested], Object.keys(candidate[lookField][nested]), nested);
merged[nested] = { ...candidate[lookField][nested], ...patch[nested] };
}
candidate[lookField] = merged;
} else if (operation.type === 'set-camera') {
knownKeys(operation, ['type', ...Object.keys(candidate.camera)], path);
for (const field of Object.keys(candidate.camera)) {
if (Object.hasOwn(operation, field)) {
candidate.camera[field] = operation[field];
}
}
} else if (operation.type === 'set-root') {
knownKeys(operation, ['type', ...ROOT_FIELDS], path);
for (const field of ROOT_FIELDS) {
if (Object.hasOwn(operation, field)) {
candidate.root[field] = operation[field];
}
}
} else if (operation.type === 'set-motion' && Object.hasOwn(operation, 'removeTracks')) {
candidate.motion = agentSceneModule('motionTrackRemoval').removeMotionTracks(operation, candidate.motion, path);
} else if (operation.type === 'set-motion') {
knownKeys(operation, ['type', 'motion'], path);
if (!Object.hasOwn(operation, 'motion')) {
throw invalidField(`${path}.motion`, undefined, 'a motion record, or null to clear it, such as null', TypeError);
}
candidate.motion = operation.motion;
} else if (operation.type === 'set-physics') {
knownKeys(operation, ['type', 'physics'], path);
if (!Object.hasOwn(operation, 'physics')) {
throw invalidField(`${path}.physics`, undefined, 'a physics record, or null to clear it, such as null', TypeError);
}
candidate.physics = operation.physics;
} else if (operation.type === 'set-asset-node') {
knownKeys(operation, ['type', 'id', ...ROOT_FIELDS], path);
if (!sourceNodes.has(operation.id)) {
throw invalidField(`${path}.id`, operation.id, 'the ID of a source node; call scene_inspect with kind hierarchy to list them');
}
const fields = ROOT_FIELDS.filter(field => Object.hasOwn(operation, field));
if (!fields.length) {
throw invalidField(path, operation, 'an id plus at least one of translation, rotation or scale, such as { "type": "set-asset-node", "id": "node-1", "translation": [0, 1, 0] }', TypeError);
}
let override = candidate.nodeOverrides.find(value => value.id === operation.id);
if (!override) {
override = { id: operation.id };
candidate.nodeOverrides.push(override);
}
for (const field of fields) {
override[field] = operation[field];
}
} else if (operation.type === 'set-animation') {
knownKeys(operation, ['type', 'clip', 'time'], path);
if (operation.clip === null) {
if (Object.hasOwn(operation, 'time')) {
throw invalidField(`${path}.time`, operation.time, 'no time when clip is null, which returns to the initial pose; drop time', TypeError);
}
candidate.animation = null;
} else {
const clip = operation.clip === undefined ? candidate.animation?.clip : operation.clip;
const sameClip = candidate.animation !== null && clip === candidate.animation.clip;
const time = operation.time === undefined ? (sameClip ? candidate.animation.time : 0) : operation.time;
candidate.animation = { clip, time };
}
} else if (operation.type === 'set-material') {
knownKeys(operation, ['type', 'id', ...MATERIAL_FIELDS], path);
if (!materialRecords.has(operation.id)) {
throw invalidField(`${path}.id`, operation.id, `the ID of a decoded material, one of ${[...materialRecords.keys()].slice(0, 5).join(', ')}`);
}
let override = candidate.materialOverrides.find(value => value.id === operation.id);
if (!override) {
override = { id: operation.id };
candidate.materialOverrides.push(override);
}
for (const field of MATERIAL_FIELDS) {
if (Object.hasOwn(operation, field)) {
override[field] = operation[field];
}
}
} else if (operation.type === 'edit-mesh') {
knownKeys(operation, ['type', 'geometry', 'edits', 'replace'], path);
candidate.meshEdits = withFieldPrefix(path, () => meshEditEntriesAfter(candidate.meshEdits ?? [], operation, records));
} else {
throw invalidField(`${path}.type`, operation.type, 'one of set-camera, set-root, set-motion, set-physics, set-asset-node, set-animation, set-material or edit-mesh, such as "set-root"; imported parts take edit-mesh with a mesh ID such as mesh-0', TypeError);
}
}
return publish(candidate);
},
inspect(inputOptions = {}) {
const options = copiedJson(inputOptions);
knownKeys(options, ['ids', 'limit', 'includeBounds', 'kind', 'offset'], 'inspection');
const limit = options.limit === undefined ? 64 : options.limit;
if (!Number.isInteger(limit) || limit < 1 || limit > 256 ||
(options.includeBounds !== undefined && typeof options.includeBounds !== 'boolean')) {
if (options.includeBounds !== undefined && typeof options.includeBounds !== 'boolean') {
throw invalidField('includeBounds', options.includeBounds, 'true or false');
}
throw invalidField('limit', limit, 'a whole number from 1 to 256, such as 64');
}
const offset = options.offset === undefined ? 0 : options.offset;
if (!Number.isInteger(offset) || offset < 0 || offset > 4096 ||
(options.kind !== undefined && !['meshes', 'hierarchy'].includes(options.kind))) {
if (options.kind !== undefined && !['meshes', 'hierarchy'].includes(options.kind)) {
throw invalidField('kind', options.kind, 'one of meshes, hierarchy');
}
throw invalidField('offset', offset, 'a whole number from 0 to 4096, such as 0');
}
if (options.kind === 'hierarchy') {
if (options.ids !== undefined && (!Array.isArray(options.ids) || options.ids.length > sourceNodes.size)) {
throw invalidField('ids', Array.isArray(options.ids) ? `${options.ids.length} IDs` : options.ids, `an array of at most ${sourceNodes.size} source-node IDs, such as []`);
}
const selected = options.ids === undefined ? [...sourceNodes.values()] : options.ids.map(id => {
if (!sourceNodes.has(id)) {
throw invalidField('ids', id, 'the ID of a source node; call scene_inspect with kind hierarchy to list them');
}
return sourceNodes.get(id);
});
const nodes = structuredClone(selected.slice(offset, offset + limit));
return { revision, topologyRevision, assetId: canonicalAssetId, kind: 'hierarchy', ...motionIkReport(), ...motionDriveReport(), ...motionLayerReport(), ...diagnosticsReport(),
counts: { nodes: sourceNodes.size, joints: [...sourceNodes.values()].filter(node => node.joint).length },
nodes, offset, truncated: offset + nodes.length < selected.length,
...(options.includeBounds ? { note: 'Hierarchy lists no bounds; inspect without kind, with ids of nodes or meshes, to get them.' } : {}),
motion: recipe.motion ? { duration: recipe.motion.duration, loop: recipe.motion.loop, tracks: recipe.motion.tracks.length, time: motionTime } : null };
}
if (options.ids !== undefined && (!Array.isArray(options.ids) || options.ids.length > Math.max(records.length, sourceNodes.size))) {
throw invalidField('ids', Array.isArray(options.ids) ? `${options.ids.length} IDs` : options.ids, `an array of at most ${Math.max(records.length, sourceNodes.size)} mesh or node IDs, such as ["mesh-0"]`);
}
const originNodes = new Map();
const selected = options.ids === undefined ? records : options.ids.flatMap(id => inspectedRecordsFor(id, originNodes));
const visible = selected.slice(offset, offset + limit);
if (options.includeBounds && visible.filter(record => !record.isSourceNodeReport).reduce((total, record) => total + geometryOf(record).positions.length / 3, 0) > MAX_INSPECTION_VERTICES) {
throw invalidField('ids', `${visible.length} meshes`, 'fewer meshes, under two million authored base vertices in all, such as ["mesh-0"]');
}
const nodes = visible.map(record => {
if (record.isSourceNodeReport) {
const { isSourceNodeReport, ...report } = record;
return report;
}
const index = Number(record.id.slice(5));
const node = {
id: record.id, label: record.label, geometry: record.geometry.id, material: record.material.id,
vertices: geometryOf(record).positions.length / 3,
triangles: geometryOf(record).indices.length / 3,
skinned: Boolean(record.source.skin), morphTargets: geometryOf(record).morphTargets?.length ?? 0,
...(editedParts.has(record.id) ? { edited: true } : {}),
...(originNodes.has(record.id) ? { fromNode: originNodes.get(record.id) } : {}),
};
if (options.includeBounds) {
node.bounds = baseBounds([geometryOf(record)], [matrices[index]]);
node.boundsKind = AGENT_ASSET_CAPABILITIES.boundsKind;
}
return node;
});
let geometryBytes = 0;
let vertices = 0;
const activeGeometries = new Set(records.map(record => geometryOf(record)));
for (const geometry of activeGeometries) {
vertices += geometry.positions.length / 3;
for (const value of Object.values(geometry)) {
if (ArrayBuffer.isView(value)) {
geometryBytes += value.byteLength;
}
}
for (const target of geometry.morphTargets ?? []) {
geometryBytes += (target.positions?.byteLength ?? 0) + (target.normals?.byteLength ?? 0);
}
}
return {
revision, topologyRevision, assetId: canonicalAssetId, ...diagnosticsReport(),
counts: { nodes: parts.length, parts: parts.length, geometries: activeGeometries.size, materials: materials.size, vertices },
geometryBytes, animation: structuredClone(recipe.animation),
motion: recipe.motion ? { duration: recipe.motion.duration, loop: recipe.motion.loop, tracks: recipe.motion.tracks.length, layers: recipe.motion.layers?.length ?? 0, time: motionTime } : null,
physics: physicsSampler ? physicsSampler.report() : null,
animations: asset.animations.map((clip, index) => ({ id: index, label: clipDisplayName(clip, index).slice(0, 256), duration: clip.duration })),
nodes, offset, truncated: selected.length > offset + nodes.length,
};
},
/** Polygon reports of imported parts, with the edit results and what was transferred to the edited geometry. */
inspectMeshes(options = {}) {
knownKeys(options, ['geometries'], 'mesh inspection');
const requested = options.geometries ?? records.slice(0, MAX_MESH_REPORTS).map(record => record.id);
if (!Array.isArray(requested) || requested.length > MAX_MESH_REPORTS) {
throw invalidField('geometries', Array.isArray(requested) ? `${requested.length} IDs` : requested, `an array of at most ${MAX_MESH_REPORTS} mesh IDs, such as ["mesh-0"]`);
}
const meshes = requested.map(id => {
const index = records.findIndex(record => record.id === id);
if (index < 0) {
throw invalidField('geometries', id, 'an imported mesh ID such as "mesh-0"; scene_inspect lists them');
}
const record = records[index];
const edited = editedParts.get(id);
const matrix = matrices[index];
const scale = mat4.getScaling([0, 0, 0], matrix).map(value => Number(value.toPrecision(4)));
// Where each local axis points in the world, so an agent can place a cutter or select by direction.
const localAxesInWorld = [0, 4, 8].map(offset => {
const length = Math.hypot(matrix[offset], matrix[offset + 1], matrix[offset + 2]) || 1;
return [0, 1, 2].map(axis => Number((matrix[offset + axis] / length).toFixed(3)));
});
return {
geometry: id, ...agentSceneModule('mesh').importedMeshReport(geometryOf(record)),
...(edited ? { transfer: edited.transfer } : {}),
localToWorldScale: scale, localAxesInWorld,
};
});
return { revision, meshes, truncated: false };
},
/** The surfaces a scene query walks: every part with its geometry, world matrix and material ID. */
queryParts() {
return records.map(record => ({ id: record.id, geometry: geometryOf(record), matrix: matrices[Number(record.id.slice(5))], material: record.material.id }));
},
checkpoint() {
if (checkpoints.size >= MAX_CHECKPOINTS) {
throw invalidField('checkpoints', `${checkpoints.size} saved`, `at most ${MAX_CHECKPOINTS} saved checkpoints; release one first, such as with scene_release_checkpoint`);
}
const handle = Object.freeze({});
checkpoints.set(handle, structuredClone(recipe));
return handle;
},
restore(handle, options = {}) {
expected(options);
if (!checkpoints.has(handle)) {
throw invalidField('checkpointId', 'unknown or released', 'a checkpointId that scene_checkpoint returned and you have not released, such as the last one returned');
}
return publish(checkpoints.get(handle));
},
/** Go back to an earlier revision that apply or restore left behind; no checkpoint is needed. */
restoreRevision(target, options = {}) {
expected(options);
const entry = revisionHistory.find(candidate => candidate.revision === target);
if (!entry) {
const kept = revisionHistory.map(candidate => candidate.revision);
throw invalidField('revision', target, kept.length > 0
? `one of the kept revisions: ${kept.join(', ')} (the last ${REVISION_HISTORY_LIMIT} are kept; older ones are dropped)`
: 'a revision this session kept, but none is kept yet because nothing has been edited; apply an edit first');
}
return publish(entry.recipe);
},
releaseCheckpoint(handle) {
if (!checkpoints.delete(handle)) {
throw invalidField('checkpointId', 'unknown or released', 'a checkpointId that scene_checkpoint returned and you have not released, such as the last one returned');
}
},
});
}