3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { mat4, mat3 } from 'gl-matrix';
import { box, checkTorusShape, circle, cone, cylinder, grid, icoSphere, sphere, torus } from './geometry.js';
import { createSceneGraph } from './scene-graph.js';
import { currentFormatName } from './legacy-names.js';
import { invalidField, withFieldPrefix } from './field-error.js';
import { applyProjection, validateCameraShift, CAMERA_LENS_FIELDS } from './camera.js';
import { checkLocalVolumePartNames } from './local-volume-resolve.js';
import { normalizeAgentLook, environmentPatchWithSetup, environmentLinksLights, agentEnvironmentMap, SKY_OVERRIDABLE_FIELDS, VOLUME_FOG_FIELDS } from './agent-look.js';
import { postStepSupport } from './shader-registry.js';
import { agentSceneModule, agentSceneModuleActive, agentSceneModuleLoaded, defaultStageModulesNamed } from './agent-scene-modules.js';
import { CURVE_TEXT_LIMITS, AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, MAX_MATERIAL_PATTERNS, RECIPE_ALPHA_MODES } from './agent-scene-capabilities.js';
import { normalizeMaterialWear, geometryWithSurfaceMasks } from './material-wear.js';
import { ALL_LIGHTS_MASK, MATERIAL_LAYER_FIELDS, validateMaterialLayers } from './material-layers.js';
import { recipeDiagnostics, closedRoomDiagnostic } from './agent-diagnostics.js';
import { closedRoomShare, CLOSED_ROOM_SHARE } from './closed-room.js';
import { depthLayerOf, MAXIMUM_DEPTH_LAYER } from './depth-layer.js';
import { normalizeRayVisibility } from './ray-visibility.js';
import { armatureNodes, bakeRigExport, bindSkins, createSkinStages, normalizeArmatures, publishSkinPoses, restWorldMatrix, rigReport, stageSkinPoses, transformedBounds, withoutArmatureNodes } from './rig.js';
export { AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS };
/**
* Earlier revisions a session keeps for scene_restore with a revision. Each one holds a recipe copy (a few kilobytes) and
* shares geometry buffers with the live scene, so four cost little; their geometry still counts in the allocation budget.
*/
export const REVISION_HISTORY_LIMIT = 4;
const FIELD_EDIT_OPERATIONS = new Set(['set-node', 'set-material', 'set-camera']);
// Fields of a set-node operation that move or show a node without changing the graph's shape, the geometry or the materials.
const POSE_EDIT_FIELDS = new Set(['type', 'id', 'translation', 'rotation', 'scale', 'visible']);
const TRANSFORM_FIELDS = ['translation', 'rotation', 'scale'];
/** The IDs of the nodes a batch of set-node operations moves, or null when the batch edits anything besides pose and visibility. */
function poseEditNodeIds(operations) {
const movedNodes = new Set();
for (const operation of operations) {
if (operation.type !== 'set-node' || Object.keys(operation).some(field => !POSE_EDIT_FIELDS.has(field))) return null;
if (TRANSFORM_FIELDS.some(field => Object.hasOwn(operation, field))) movedNodes.add(operation.id);
}
return movedNodes;
}
export { normalizeAgentLook, resolveAgentShadow } from './agent-look.js';
import { OWN_SECTIONS as NULLABLE_SECTION_OPERATIONS } from './agent-apply-report.js';
export { describeApplication } from './agent-apply-report.js';
export {
needsMeshBooleans, loadMeshBooleans, meshBooleansLoaded, setManifoldModuleLoader,
needsPhysics, needsBuoyancy, loadPhysicsEngine, physicsEngineLoaded, setPhysicsModuleLoader,
loadAgentSceneModules, loadAllAgentSceneModules, registerAgentSceneFont, allAgentSceneModulesLoaded, agentSceneModulesNeeded,
} from './agent-scene-modules.js';
const DEFAULT_LIMITS = AGENT_SCENE_DEFAULT_LIMITS;
const MAX_MESH_REPORTS = 16;
// A boolean cutter may name another recipe geometry, which may itself cut with a third. Both bounds are static, so they
// do not depend on what the evaluation cache holds.
const MAX_CUTTER_DEPTH = 4;
const MAX_CUTTER_WORK_VERTICES = 250_000;
// Where a geometry is checked before the whole recipe is known: references stay unresolved and count nothing.
const PENDING_CUTTER_SCOPE = Object.freeze({ definitions: null, chain: Object.freeze([]) });
// Terrain meshes carry one more float for each vertex (sky visibility) than the 56 bytes the budget estimates.
const TERRAIN_SKY_VISIBILITY_BYTES = 4;
const CAMERA_DEFAULTS = Object.freeze({ eye: [4, 3, 5], target: [0, 0, 0], up: [0, 1, 0], fov: 45, near: 0.1, far: 1000 });
// Per-node render flags: `visible` hides a node and its children; the rest become renderer part flags of a mesh node.
const RENDER_FLAG_FIELDS = ['visible', 'castShadow', 'receiveShadow', 'holdout', 'shadowCatcher', 'shadowOnly'];
const PART_FLAG_FIELDS = RENDER_FLAG_FIELDS.slice(1);
const NODE_FIELDS = ['translation', 'rotation', 'scale', 'parent', 'label', 'geometry', 'material', 'skin', 'relations', 'asset', 'vegetation', 'decal', 'depthLayer', 'blend', 'rayVisibility', ...RENDER_FLAG_FIELDS];
const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', 'map', 'subsurface', 'snippet', 'waterPreset', 'absorption', 'turbidity', 'caustics', 'waterRamp', 'aov', 'wear', 'retro', 'emissionMask', 'toonColors', ...MATERIAL_LAYER_FIELDS];
const PATTERN_TEXTURE_FIELDS = ['map', 'normalMap', 'metallicRoughnessMap', 'emissiveMap', 'layerMaps', 'transmissionMap', 'aovMap', 'emissionFresnel', 'boxMapScale', 'boxMapAxis'];
const CAMERA_FIELDS = [...Object.keys(CAMERA_DEFAULTS), ...CAMERA_LENS_FIELDS];
// Fields of an optional shader module join the list here, so the long list above stays a line each material feature does not rewrite.
MATERIAL_FIELDS.push('waterGlint');
const LOOK_OPERATION_FIELDS = Object.freeze({
'set-environment': 'environment',
'set-effects': 'effects',
'set-shadow': 'shadow',
});
const ADDITION_FIELDS = Object.freeze({
'add-geometry': ['geometries', 'geometry'],
'add-material': ['materials', 'material'],
'add-node': ['nodes', 'node'],
});
const REMOVAL_FIELDS = Object.freeze({
'remove-geometry': 'geometries',
'remove-material': 'materials',
});
// Rejects a batch that removes a geometry or material and leaves nodes pointing at it, naming them and the fix.
function assertRemovedResourcesUnused(candidate, removals) {
for (const { type, id } of removals) {
const kind = type.slice(7);
const users = candidate.nodes.filter(node => node[kind] === id).map(node => node.id);
if (users.length > 0 && !candidate[REMOVAL_FIELDS[type]].some(record => record.id === id)) {
const more = users.length > 8 ? ` and ${users.length - 8} more` : '';
throw invalidField('id', id, `${kind} ${id} is used by nodes ${users.slice(0, 8).join(', ')}${more}; set-node them to another ${kind} or remove-node them first`);
}
}
}
function knownKeys(value, allowed, label) {
if (!value || typeof value !== 'object' || Array.isArray(value)) {
throw invalidField(label, value, 'an object, such as {}', TypeError);
}
for (const key of Object.keys(value)) {
if (!allowed.includes(key)) {
throw invalidField(`${label}.${key}`, value[key], `one of the fields ${allowed.join(', ')}; remove ${key}`, TypeError);
}
}
}
function resolveLimits(input) {
knownKeys(input, Object.keys(DEFAULT_LIMITS), 'limits');
const result = { ...DEFAULT_LIMITS, ...input };
for (const [key, value] of Object.entries(result)) {
if (!Number.isSafeInteger(value) || value <= 0) {
throw invalidField(`limits.${key}`, value, 'a positive whole number, such as 1024');
}
}
if (result.maxNodes > 4096) {
throw new RangeError('maxNodes cannot exceed 4096.');
}
return Object.freeze(result);
}
// Copy only JSON data. Reject accessors before reading them and bound traversal before serialization.
function assertWithinRecipeBytes(bytes, maximum) {
if (bytes > maximum) {
throw new RangeError('JSON exceeds maxRecipeBytes. Reduce the input.');
}
}
function copiedJson(input, maximum) {
let bytes = 0;
const ancestors = new Set();
const encoder = new TextEncoder();
// Recipes repeat the same keys and ids thousands of times, so each distinct string is measured once.
const stringBytes = new Map();
function jsonStringBytes(text) {
let size = stringBytes.get(text);
if (size === undefined) {
size = encoder.encode(JSON.stringify(text)).length;
stringBytes.set(text, size);
}
return size;
}
function charge(count) {
bytes += count;
assertWithinRecipeBytes(bytes, maximum);
}
function copy(value, depth) {
if (depth > 64) {
throw new RangeError('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)) {
charge(String(value).length);
return value;
}
if (typeof value === 'string') {
if (value.length > maximum) {
throw new RangeError('JSON exceeds maxRecipeBytes.');
}
charge(jsonStringBytes(value));
return value;
}
if (!value || typeof value !== 'object' || ancestors.has(value)) {
throw new TypeError('Recipe must contain finite, acyclic JSON data.');
}
const array = Array.isArray(value);
if (array && value.length > maximum) {
throw new RangeError('JSON exceeds maxRecipeBytes.');
}
if (!array && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
throw new TypeError('Recipe objects must be plain JSON objects.');
}
ancestors.add(value);
charge(2);
const result = array ? [] : {};
const keys = Reflect.ownKeys(value);
let entryCount = 0;
for (const key of keys) {
if (array && key === 'length') continue;
if (typeof key !== 'string' || key === '__proto__') {
throw new TypeError('Invalid JSON key.');
}
const descriptor = Object.getOwnPropertyDescriptor(value, key);
if (!descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) {
throw new TypeError('JSON accessors and hidden fields are unsupported.');
}
if (array && key !== String(result.length)) {
throw new TypeError('JSON arrays must be dense without extra fields.');
}
// Commas are counted exactly (one between entries) so this running size equals the serialized size
// that normalizeRecipe checks after a field edit; both paths then accept and refuse the same recipes.
const separatorBytes = entryCount === 0 ? 0 : 1;
entryCount += 1;
charge(array ? separatorBytes : jsonStringBytes(key) + 1 + separatorBytes);
result[key] = copy(descriptor.value, depth + 1);
}
if (array && result.length !== value.length) {
throw new TypeError('JSON arrays must be dense without trailing holes.');
}
ancestors.delete(value);
return result;
}
const result = copy(input, 0);
if (encoder.encode(JSON.stringify(result)).length > maximum) {
throw new RangeError('JSON exceeds maxRecipeBytes.');
}
return result;
}
function finite(value, label) {
if (!Number.isFinite(value) || !Number.isFinite(Math.fround(value))) {
throw invalidField(label, value, 'a finite number that fits Float32, such as 0.5', TypeError);
}
return value;
}
function vector(value, length, label) {
if (!Array.isArray(value) || value.length !== length) {
const example = `[${Array.from({ length }, (_, index) => (index === length - 1 && length === 4 ? 1 : 0)).join(', ')}]`;
throw invalidField(label, value, `an array of ${length} numbers, such as ${example}`, TypeError);
}
return value.map((component, index) => finite(component, `${label}[${index}]`));
}
function defaultValue(value, fallback) {
return value === undefined ? fallback : value;
}
function integer(value, minimum, maximum, label) {
if (!Number.isInteger(value) || value < minimum || value > maximum) {
throw invalidField(label, value, `a whole number from ${minimum} to ${maximum}, such as ${minimum}`);
}
return value;
}
function identifier(value, label = 'id') {
if (typeof value !== 'string' || !value.trim() || value.length > 128) {
throw invalidField(label,value, 'a string of 1 to 128 characters, such as "wall-left"', TypeError);
}
return value;
}
/**
* Checks a list of records and returns the normalized copies. A record in `alreadyNormalized` came out of `validate` before
* and nobody has changed it since, so it is kept as it is; `validate` adds the records it returns when `isShareable` says
* no later stage rewrites them in place.
*/
function resources(values, maximum, label, validate, { alreadyNormalized = null, isShareable = null } = {}) {
if (!Array.isArray(values) || values.length > maximum) {
throw invalidField(label, Array.isArray(values) ? `${values.length} entries` : values, `an array of at most ${maximum} entries, such as []`);
}
const seen = new Set();
return values.map((value, index) => {
if (alreadyNormalized?.has(value)) {
if (seen.has(value.id)) {
throw invalidField(`${label}[${index}].id`, value.id, `an ID no other ${label} entry uses; rename one, or remove the other`);
}
seen.add(value.id);
return value;
}
return withFieldPrefix(`${label}[${index}]`, () => {
identifier(value?.id);
if (seen.has(value.id)) {
throw invalidField('id', value.id, `an ID no other ${label} entry uses; rename one, or remove the other`);
}
seen.add(value.id);
const normalized = validate(value);
if (alreadyNormalized && isShareable(normalized)) alreadyNormalized.add(normalized);
return normalized;
});
});
}
function copyMaterialLayers(value, result) {
for (const field of MATERIAL_LAYER_FIELDS) {
if (value[field] === undefined) continue;
result[field] = Array.isArray(value[field]) ? vector(value[field], 3, field) : value[field];
}
if (value.toonColors !== undefined) {
result.toonColors = Array.isArray(value.toonColors)
? Object.freeze(value.toonColors.map((color, index) => Object.freeze(vector(color, 3, `toonColors[${index}]`))))
: value.toonColors;
}
validateMaterialLayers(result);
if (value.emissionMask !== undefined) {
result.emissionMask = Object.freeze(agentSceneModule('emissionMask').normalizeEmissionMask(value.emissionMask));
}
if (value.subsurface !== undefined) result.subsurface = agentSceneModule('subsurfaceShader').copySubsurface(value.subsurface, result.tag);
if (value.snippet) result.snippet = agentSceneModule('materialSnippet').normalizeMaterialSnippet(value.snippet, { hasMap: Boolean(value.map || value.pattern) });
if (result.anisotropy > 0 || result.iridescence > 0 || JSON.stringify(value.pattern?.graph?.emission ?? null).includes('"fresnel"')) agentSceneModule('layerShaders');
if (result.toon > 0) agentSceneModule('lineArt');
}
function materialFrom(value) {
knownKeys(value, ['id', 'tag', ...MATERIAL_FIELDS], 'material');
// A pattern brings its own colours, so the color field tints it and leaves it unchanged by default.
const defaultColor = value.pattern === undefined ? [0.5, 0.5, 0.5] : [1, 1, 1];
const graph = value.pattern?.type === 'graph' ? value.pattern.graph : {};
// A graph that makes roughness, metallic or emission passes it through as written, so the factors default to 1.
const graphFactor = (output, fallback) => (Object.hasOwn(graph ?? {}, output) ? 1 : fallback);
const result = { id: value.id, tag: defaultValue(value.tag, 'surface'), color: vector(defaultValue(value.color, defaultColor), 3, 'color'),
...(graphFactor('clearcoat', 0) && { clearcoat: 1 }), ...(graphFactor('transmission', 0) && { transmission: 1 }),
metallic: defaultValue(value.metallic, graphFactor('metallic', 0)), roughness: defaultValue(value.roughness, graphFactor('roughness', 0.5)), emission: defaultValue(value.emission, graphFactor('emission', 0)) };
if (!AGENT_SCENE_CAPABILITIES.materialTags.includes(result.tag)) {
throw invalidField('tag', result.tag, `one of ${AGENT_SCENE_CAPABILITIES.materialTags.join(', ')}`);
}
if (value.map !== undefined) agentSceneModule('assets').applyMapSequence(value, result);
if (value.pattern !== undefined) {
if (result.tag !== 'surface') throw invalidField('pattern', value.pattern?.type, 'a material with the surface tag; remove pattern or set tag to surface');
result.pattern = agentSceneModule('patterns').normalizeMaterialPattern(value.pattern);
}
result.opacity = defaultValue(value.opacity, 1);
finite(result.opacity, 'opacity');
if (result.opacity < 0 || result.opacity > 1) {
throw invalidField('opacity', result.opacity, 'a number from 0 to 1, such as 0.5');
}
const requestedAlphaMode = defaultValue(value.alphaMode, 'opaque');
if (!RECIPE_ALPHA_MODES.includes(requestedAlphaMode)) {
throw invalidField('alphaMode', requestedAlphaMode, `one of ${RECIPE_ALPHA_MODES.join(', ')}`);
}
// The renderer ignores opacity on opaque surfaces, so any opacity below one means blending (additive stays additive).
const graphHasOpacity = graphFactor('opacity', 0);
result.alphaMode = (result.opacity < 1 || graphHasOpacity) && requestedAlphaMode === 'opaque' ? 'blend' : requestedAlphaMode;
result.doubleSided = defaultValue(value.doubleSided, false);
if (typeof result.doubleSided !== 'boolean') {
throw invalidField('doubleSided', result.doubleSided, 'true or false', TypeError);
}
for (const field of ['metallic', 'roughness']) {
finite(result[field], field);
if (result[field] < 0 || result[field] > 1) {
throw invalidField(field, result[field], 'a number from 0 to 1, such as 0.5');
}
}
finite(result.emission, 'emission');
if (result.emission < 0) {
throw invalidField('emission', result.emission, 'a number of 0 or more, such as 1');
}
if (result.color.some(component => component < 0 || component > 1)) {
throw invalidField('color', result.color, 'three numbers from 0 to 1, such as [0.8, 0.2, 0.1]');
}
if (value.emissiveColor !== undefined) {
result.emissiveColor = vector(value.emissiveColor, 3, 'emissiveColor');
if (result.emissiveColor.some(component => component < 0)) {
throw invalidField('emissiveColor', result.emissiveColor, 'three numbers of 0 or more, such as [1, 0.5, 0.2]');
}
}
if (value.aov !== undefined) {
const aov = typeof value.aov === 'number' ? [finite(value.aov, 'aov'), value.aov, value.aov] : vector(value.aov, 3, 'aov');
if (aov.some(component => component < 0 || component > 1)) {
throw invalidField('aov', value.aov, 'a number or three numbers from 0 to 1, such as [1, 0.5, 0]');
}
result.aov = aov;
}
copyMaterialLayers(value, result);
if (value.wear) result.wear = normalizeMaterialWear(value.wear);
if (value.waterGlint !== undefined && value.waterGlint !== null) {
if (result.tag !== 'water') throw invalidField('waterGlint', value.waterGlint, 'a water material: set tag "water" on the material, or remove waterGlint');
result.waterGlint = agentSceneModule('glitterShader').normalizeWaterGlint(value.waterGlint);
}
if (value.retro !== undefined && value.retro !== null) result.retro = agentSceneModule('retroShader').normalizeMaterialRetro(value.retro);
if (agentSceneModuleLoaded('worldMaterials')) {
agentSceneModule('worldMaterials').copyWaterFields(value, result, vector);
agentSceneModule('worldMaterials').copyWaterRamp(value, result, vector);
}
const emissiveColor = result.emissiveColor ?? result.color;
for (const component of emissiveColor) {
const radiance = Math.fround(component) * Math.fround(result.emission);
if (!Number.isFinite(Math.fround(radiance))) {
throw invalidField('emission', result.emission, 'an emission that keeps color times emission within Float32 range, such as 2');
}
if (result.tag === 'unlit' && radiance > 65500) {
throw invalidField('emission', result.emission, 'an unlit emission that keeps color times emission at or below 65500, such as 2');
}
}
return result;
}
function nodeFrom(value) {
knownKeys(value, ['id', 'geometry', 'material', ...NODE_FIELDS], 'node');
const result = { ...value, parent: value.parent ?? null,
translation: vector(defaultValue(value.translation, [0, 0, 0]), 3, 'translation'),
rotation: vector(defaultValue(value.rotation, [0, 0, 0, 1]), 4, 'rotation'),
scale: vector(defaultValue(value.scale, [1, 1, 1]), 3, 'scale') };
if (result.parent !== null) {
identifier(result.parent, 'parent');
}
if (result.label !== undefined && (typeof result.label !== 'string' || result.label.length > 256)) {
throw invalidField('label', result.label, 'a string of at most 256 characters, such as "left wall"', TypeError);
}
if (result.scale.some(component => component <= 0 || Math.fround(component) <= 0)) {
throw invalidField('scale', result.scale, 'three positive numbers, such as [1, 1, 1]');
}
const length = Math.hypot(...result.rotation);
if (length === 0) {
throw invalidField('rotation', result.rotation, 'a nonzero quaternion [x, y, z, w], such as [0, 0, 0, 1] for no rotation');
}
result.rotation = result.rotation.map(component => component / length);
if ((value.geometry !== undefined) !== (value.material !== undefined)) {
throw invalidField(value.geometry === undefined ? 'geometry' : 'material', value.geometry ?? value.material, `set together with ${value.geometry === undefined ? 'material' : 'geometry'} to draw a mesh, or drop both for a group node`, TypeError);
}
if (value.geometry !== undefined) {
identifier(value.geometry);
identifier(value.material);
}
if (value.asset !== undefined) {
if (value.geometry !== undefined || value.skin !== undefined) {
throw invalidField('asset', value.geometry ?? value.skin, 'an asset node without geometry, material and skin; an asset node is a group', TypeError);
}
result.asset = agentSceneModule('assets').normalizeAssetPlacement(value.asset);
}
if (value.vegetation !== undefined) result.vegetation = agentSceneModule('vegetation').normalizeVegetation(value.vegetation, value);
if (value.decal !== undefined && typeof value.decal !== 'boolean') {
throw invalidField('decal', value.decal, 'true or false', TypeError);
}
if (value.depthLayer !== undefined) {
integer(value.depthLayer, 0, MAXIMUM_DEPTH_LAYER, 'depthLayer');
}
for (const flag of RENDER_FLAG_FIELDS) {
if (value[flag] !== undefined && typeof value[flag] !== 'boolean') throw invalidField(flag, value[flag], 'true or false', TypeError);
if (flag !== 'visible' && value[flag] !== undefined && value.geometry === undefined) throw invalidField(flag, value[flag], 'a flag on a mesh node with geometry and material; remove it from group nodes', TypeError);
}
if (value.rayVisibility !== undefined) {
if (value.geometry === undefined) throw invalidField('rayVisibility', value.rayVisibility, 'a field on a mesh node; remove it from group nodes', TypeError);
const rayVisibility = normalizeRayVisibility(value.rayVisibility);
if (rayVisibility === undefined) delete result.rayVisibility;
else result.rayVisibility = rayVisibility;
if (rayVisibility?.shadow === false && value.shadowOnly === true) {
throw invalidField('rayVisibility', value.rayVisibility, 'shadow rays on when shadowOnly is true', TypeError);
}
}
if (value.holdout === true && value.shadowCatcher === true) throw invalidField('shadowCatcher', value.shadowCatcher, 'false when holdout is true; a node is a holdout or a shadow catcher, not both', TypeError);
if (value.shadowOnly === true && (value.castShadow === false || value.holdout === true || value.shadowCatcher === true)) {
throw invalidField('shadowOnly', value.shadowOnly, 'false with castShadow false, holdout or shadowCatcher', TypeError);
}
if (value.skin !== undefined) {
if (value.geometry === undefined) {
throw invalidField('skin', value.skin, 'a skin on a mesh node with geometry and material; remove skin from group nodes', TypeError);
}
knownKeys(value.skin, ['armature', 'maxInfluences', 'maxDistance'], 'skin');
identifier(value.skin.armature);
if (value.skin.maxInfluences !== undefined) {
integer(value.skin.maxInfluences, 1, 4, 'skin maxInfluences');
}
if (value.skin.maxDistance !== undefined && !(Number.isFinite(value.skin.maxDistance) && value.skin.maxDistance > 0)) {
throw invalidField('skin.maxDistance', value.skin.maxDistance, 'a positive number of metres, such as 0.5');
}
}
return result;
}
/** Sets the given camera fields on a camera; a focal length replaces fov and a fov replaces focal length and sensor, never both. */
export function applyCameraFields(camera, fields) {
rejectFovWithFocalLength(fields);
for (const field of CAMERA_FIELDS) {
if (Object.hasOwn(fields, field)) camera[field] = fields[field];
}
if (Object.hasOwn(fields, 'focalLength')) delete camera.fov;
// Back to a perspective view: the old orthographic size no longer applies.
if (fields.projection === 'perspective' && !Object.hasOwn(fields, 'orthoScale')) delete camera.orthoScale;
if (Object.hasOwn(fields, 'fov')) {
delete camera.focalLength;
delete camera.sensorWidth;
}
return camera;
}
function rejectFovWithFocalLength(fields) {
if (fields.fov !== undefined && fields.focalLength !== undefined) {
throw invalidField('camera.focalLength', fields.focalLength, 'only one of fov (degrees) or focalLength (millimetres with sensorWidth), such as fov 45; remove the other');
}
}
function checkCameraLens(camera) {
if (camera.projection !== undefined && camera.projection !== 'perspective' && camera.projection !== 'orthographic') {
throw invalidField('camera.projection', camera.projection, 'perspective or orthographic');
}
const orthographic = camera.projection === 'orthographic';
if (camera.orthoScale !== undefined) {
if (!orthographic) throw invalidField('camera.orthoScale', camera.orthoScale, 'a field of an orthographic camera; set projection to orthographic, or remove orthoScale');
if (!Number.isFinite(camera.orthoScale) || camera.orthoScale <= 0) throw invalidField('camera.orthoScale', camera.orthoScale, 'a positive view height in metres, such as 10');
}
if (camera.sensorWidth !== undefined && camera.focalLength === undefined) throw invalidField('camera.sensorWidth', camera.sensorWidth, 'a field used with focalLength, such as focalLength 35; add focalLength or remove sensorWidth');
if (camera.focalLength !== undefined) {
if (orthographic) throw invalidField('camera.focalLength', camera.focalLength, 'a field of a perspective camera; an orthographic camera is sized by orthoScale, so remove focalLength');
if (!Number.isFinite(camera.focalLength) || camera.focalLength <= 0 || camera.focalLength > 10000) throw invalidField('camera.focalLength', camera.focalLength, 'a lens length above 0 and up to 10000 millimetres, such as 35');
if (camera.sensorWidth !== undefined && !(Number.isFinite(camera.sensorWidth) && camera.sensorWidth > 0 && camera.sensorWidth <= 1000)) throw invalidField('camera.sensorWidth', camera.sensorWidth, 'a width above 0 and up to 1000 millimetres, such as 36');
}
if (camera.shift !== undefined) validateCameraShift(camera.shift);
if (camera.fStop !== undefined && !(Number.isFinite(camera.fStop) && camera.fStop >= 0.7 && camera.fStop <= 64)) {
throw invalidField('camera.fStop', camera.fStop, 'a number from 0.7 to 64, such as 2.8 (smaller numbers blur more)');
}
if (camera.focusDistance !== undefined) {
if (camera.fStop === undefined) throw invalidField('camera.focusDistance', camera.focusDistance, 'a field used with fStop, such as fStop 2.8; add fStop or remove focusDistance');
if (!(Number.isFinite(camera.focusDistance) && camera.focusDistance > 0)) {
throw invalidField('camera.focusDistance', camera.focusDistance, 'a positive distance in metres along the view axis, such as 3.5 (default: the distance to target)');
}
}
}
function cameraFrom(value = {}) {
knownKeys(value, CAMERA_FIELDS, 'camera');
rejectFovWithFocalLength(value);
const result = { ...CAMERA_DEFAULTS, ...value };
if (result.focalLength !== undefined) delete result.fov;
checkCameraLens(result);
result.eye = vector(result.eye, 3, 'camera.eye');
result.target = vector(result.target, 3, 'camera.target');
result.up = vector(result.up, 3, 'camera.up');
const upLength = Math.hypot(...result.up);
if (upLength === 0) {
throw invalidField('camera.up', result.up, 'a nonzero direction, such as [0, 1, 0]');
}
result.up = result.up.map(component => component / upLength);
for (const field of ['fov', 'near', 'far']) {
if (result[field] !== undefined) finite(result[field], `camera.${field}`);
}
// Without fov the lens is a focal length, which gives a valid angle at any positive size.
if ((result.fov !== undefined && (Math.fround(result.fov) <= 0 || Math.fround(result.fov) >= 180)) || Math.fround(result.near) <= 0 || Math.fround(result.far) <= Math.fround(result.near)) {
if (result.fov !== undefined && (Math.fround(result.fov) <= 0 || Math.fround(result.fov) >= 180)) {
throw invalidField('camera.fov', result.fov, 'degrees above 0 and below 180, such as 50');
}
throw invalidField('camera.near', [result.near, result.far], 'near above 0 and far above near, such as near 0.1 and far 100');
}
if (result.eye.every((component, axis) => Math.fround(component) === Math.fround(result.target[axis]))) {
throw invalidField('camera.target', result.target, `a point different from eye ${JSON.stringify(result.eye)}, such as [0, 0, 0]`);
}
const direction = result.target.map((component, axis) => component - result.eye[axis]);
const directionLength = Math.hypot(...direction);
const unitDirection = direction.map(component => component / directionLength);
const crossLength = Math.hypot(unitDirection[1] * result.up[2] - unitDirection[2] * result.up[1],
unitDirection[2] * result.up[0] - unitDirection[0] * result.up[2], unitDirection[0] * result.up[1] - unitDirection[1] * result.up[0]);
if (Math.fround(crossLength) === 0) {
throw invalidField('camera.up', result.up, `a direction not parallel to the view from eye to target, such as [0, 1, 0]`);
}
const view = mat4.lookAt(mat4.create(), result.eye, result.target, result.up);
const projection = applyProjection(mat4.create(), result, 1);
for (const matrix of [view, projection]) {
const determinant = mat4.determinant(matrix);
if (!matrix.every(Number.isFinite) || !Number.isFinite(determinant) || determinant === 0) {
throw new RangeError('Camera matrices must remain finite and nonsingular at Float32 precision.');
}
}
return result;
}
const GEOMETRY_FIELDS = {
box: ['bevel', 'subdivisions'], cylinder: ['segments', 'bevel', 'bevelSegments'],
sphere: ['segments', 'rings'], grid: ['segments'], plane: ['segments'],
cone: ['radiusTop', 'radiusBottom', 'segments'], icoSphere: ['subdivisions'], circle: ['segments', 'innerRadius'],
line: ['from', 'to', 'radius', 'radialSegments'], torus: ['tubeRadius', 'segments', 'sides', 'arc', 'start'],
lathe: ['profile', 'segments', 'startAngle', 'sweep'],
extrude: ['contour', 'holes', 'depth', 'steps', 'bevel', 'bevelThickness', 'bevelSegments'],
tube: ['path', 'radius', 'segments', 'radialSegments', 'closed'],
sdf: ['root', 'resolution'],
curve: ['points', 'shape', 'splines', 'closed', 'kind', 'weights', 'order', 'knots', 'knotMode', 'trim', 'grow', 'radius', 'taper', 'profile', 'resolution', 'radialSegments'],
text: ['text', 'size', 'depth', 'font', 'align', 'curveSegments'],
mesh: ['base', 'edits', 'stack', 'smoothAngle', 'shapeKeys'],
terrain: ['size', 'resolution', 'seed', 'amplitude', 'holes'],
cloud: ['seed', 'puffs', 'width', 'height', 'flatBase', 'resolution', 'levels', 'upBias', 'unionSoftness'],
fragment: ['source', 'seed', 'cells', 'index', 'impact', 'impactRadius'],
dented: ['source', 'impacts', 'stiffness', 'maxDepth', 'radius'],
};
// A line is a two-point curve; both ends must be finite and apart.
function lineEnds(value) {
const ends = [value.from, value.to];
for (const end of ends) vector(end, 3, 'line end');
if (ends[0].every((component, axis) => component === ends[1][axis])) {
throw invalidField('to', value.to, `a point different from from ${JSON.stringify(value.from)}, such as [0, 1, 0]`);
}
return ends;
}
// A sharp box under a mesh keeps its subdivisions as a grid on each face, welded by the mesh, so edits have vertices to move (#2201).
function meshBaseSplitsBox(base) {
return base.type === 'box' && base.bevel === 0 && base.subdivisions !== undefined && base.subdivisions !== null;
}
function geometryEstimate(value, scope = PENDING_CUTTER_SCOPE) {
if (!Object.hasOwn(GEOMETRY_FIELDS, value.type)) {
throw invalidField('type', value.type, `one of ${Object.keys(GEOMETRY_FIELDS).join(', ')}`, TypeError);
}
knownKeys(value, ['id', 'type', ...GEOMETRY_FIELDS[value.type]], 'geometry');
function detail(field, fallback, minimum, maximum) {
return integer(value[field] ?? fallback, minimum, maximum, field);
}
function points(input, size, minimum, field = 'points') {
if (!Array.isArray(input) || input.length < minimum || input.length > 4096) {
throw invalidField(field, Array.isArray(input) ? `${input.length} points` : input, `a list of ${minimum} to 4096 points of ${size} numbers, such as ${JSON.stringify(Array.from({ length: minimum }, (_, index) => Array.from({ length: size }, () => index)))}`);
}
for (const point of input) {
vector(point, size, 'geometry point');
}
return input.length;
}
for (const field of GEOMETRY_FIELDS[value.type]) {
// Terrain checks its own numbers (a whole resolution from 2 to 256), so its message names the real range; null is not absent there, so it still fails below.
if (value.type === 'terrain' && ['size', 'resolution', 'amplitude'].includes(field) && value[field] !== null) continue;
if (value.type === 'cloud' && value[field] !== null) continue;
if (value[field] !== undefined && !['profile', 'contour', 'holes', 'path', 'closed', 'base', 'edits', 'stack', 'shapeKeys', 'points', 'taper', 'text', 'font', 'align', 'from', 'to', 'shape', 'splines', 'kind', 'weights', 'order', 'knots', 'knotMode', 'trim', 'grow', 'root', 'source', 'impact', 'impacts'].includes(field)) {
finite(value[field], field);
}
}
switch (value.type) {
case 'box':
return value.bevel === 0 ? 24 : 6 * (2 * detail('subdivisions', 6, 1, 128) + 2) ** 2;
case 'cylinder':
return (detail('segments', 80, 3, 2048) + 1) * 2 * (detail('bevelSegments', 6, 1, 128) + 1) + 2 * ((value.segments ?? 80) + 2);
case 'sphere':
return (detail('segments', 64, 3, 2048) + 1) * (detail('rings', 40, 2, 2048) + 1);
case 'grid':
case 'plane':
return (detail('segments', 16, 1, 64) + 1) ** 2;
case 'cone':
return (detail('segments', 64, 3, 2048) + 1) * 2 + 2 * ((value.segments ?? 64) + 2);
case 'icoSphere':
return 10 * 4 ** detail('subdivisions', 2, 0, 7) + 2;
case 'circle':
return value.innerRadius > 0 ? (detail('segments', 64, 3, 2048) + 1) * 2 : detail('segments', 64, 3, 2048) + 2;
case 'line': {
const sides = detail('radialSegments', 8, 3, 128);
lineEnds(value);
return 2 * sides * 2 + 2 * (sides + 1);
}
case 'torus':
checkTorusShape(value.tubeRadius, value.arc);
return (detail('segments', 96, 3, 2048) + 1) * (detail('sides', 24, 3, 128) + 1) + 2 * ((value.sides ?? 24) + 2);
case 'lathe': {
const profileCount = points(value.profile, 2, 2, 'profile');
agentSceneModule('modeling').checkLatheProfile(value.profile);
return (detail('segments', 64, 3, 2048) + 1) * profileCount;
}
case 'tube':
points(value.path, 3, value.closed ? 3 : 2, 'path');
if (value.closed !== undefined && typeof value.closed !== 'boolean') {
throw invalidField('closed', value.closed, 'true or false', TypeError);
}
agentSceneModule('modeling').checkTubeInputs(value.path, value.radius ?? 0.1, value.closed ?? false);
return (detail('segments', 64, 3, 2048) + 1) * (detail('radialSegments', 12, 3, 128) + 1);
case 'curve': {
if (['shape', 'splines', 'kind', 'weights', 'order', 'knots', 'knotMode', 'trim', 'grow'].some(field => value[field] !== undefined)) {
return agentSceneModule('modeling').curveGeometryVertexCount(value);
}
const knots = value.points;
if (!Array.isArray(knots) || knots.length < 2 || knots.length > CURVE_TEXT_LIMITS.maxCurvePoints) {
throw invalidField('points', Array.isArray(knots) ? `${knots.length} points` : knots, `a list of 2 to ${CURVE_TEXT_LIMITS.maxCurvePoints} points, such as [[0, 0, 0], [0, 1, 0]]`);
}
const curveChecks = agentSceneModule('modeling');
curveChecks.checkCurveRadius(value.radius ?? 0.05);
curveChecks.checkClosedFlag(value.closed ?? false);
const sides = value.profile === undefined ? detail('radialSegments', 8, 3, 128) : points(value.profile, 2, 3, 'profile');
const rings = (value.closed ? knots.length : knots.length - 1) * detail('resolution', 12, 1, 64) + 1;
return rings * sides * 2 + 2 * (sides + 1);
}
case 'sdf':
return agentSceneModule('modeling').sdfVertexEstimate(value);
case 'text': {
if (typeof value.text !== 'string') throw invalidField('text', value.text, 'a string, such as "Hello"', TypeError);
const visible = [...value.text].filter(character => !/\s/.test(character)).length;
const isDefaultFont = value.font === undefined || value.font === 'default';
const perSegment = isDefaultFont ? CURVE_TEXT_LIMITS.verticesPerCharacterSegment : CURVE_TEXT_LIMITS.verticesPerCustomCharacterSegment;
return visible * perSegment * detail('curveSegments', 4, 1, 16);
}
case 'terrain':
return agentSceneModule('terrain').terrainVertexEstimate(value);
case 'cloud':
return agentSceneModule('modeling').cloudVertexEstimate(value);
case 'extrude': {
const holes = value.holes ?? [];
if (!Array.isArray(holes) || holes.length > 128) {
throw invalidField('holes', Array.isArray(holes) ? `${holes.length} rings` : holes, 'a list of at most 128 rings of points, such as []');
}
const count = points(value.contour, 2, 3, 'contour') + holes.reduce((total, hole) => total + points(hole, 2, 3, 'holes'), 0);
if (count > 4096) {
throw invalidField('contour', `${count} points`, 'a contour and holes with at most 4096 points in total; simplify them');
}
agentSceneModule('modeling').checkExtrudeRings(value.contour, holes);
const beveled = (value.bevel ?? 0) > 0 || (value.bevelThickness ?? value.bevel ?? 0) > 0;
return 6 * (count + holes.length * 2 - 2) + 6 * count * (detail('steps', 1, 1, 256) + (beveled ? detail('bevelSegments', 3, 1, 32) * 2 : 0));
}
case 'fragment':
return fragmentEstimate(value, scope);
case 'dented':
return agentSceneModule('vehicleDamage').dentedVertexEstimate(value, scope.definitions, source => geometryEstimate(source, { definitions: scope.definitions, chain: [] }));
case 'mesh': {
const base = value.base;
if (!base || typeof base !== 'object' || Array.isArray(base) || base.type === 'mesh' || Object.hasOwn(base, 'id')) {
throw invalidField('base', base, 'a primitive or profile record without an id, such as { "type": "box" } (box, cylinder, sphere, torus, lathe, extrude, tube, grid or plane)', TypeError);
}
let estimate = meshBaseSplitsBox(base) ? 6 * (integer(base.subdivisions, 1, 128, 'subdivisions') + 1) ** 2 : geometryEstimate({ id: 'base', ...base });
const cutterScope = meshCutterScope(value, scope);
let referencedWork = 0;
for (const edit of agentSceneModule('mesh').normalizeMeshEdits(value.edits ?? [])) {
if (edit.op !== 'boolean') continue;
const cutterVertices = cutterEstimate(edit.cutter, cutterScope);
estimate += cutterVertices;
if (isCutterReference(edit.cutter)) referencedWork += cutterVertices;
}
if (referencedWork > MAX_CUTTER_WORK_VERTICES) {
throw invalidField('cutter.geometry', `${referencedWork} estimated cutter vertices in ${cutterScope.chain.join(' -> ')}`, `cutter geometries that total at most ${MAX_CUTTER_WORK_VERTICES} estimated vertices; use fewer segments or fewer referenced cutters`);
}
// Stack nodes multiply the mesh: arrays by their count, mirror and solidify at most by two.
for (const node of agentSceneModule('mesh').normalizeMeshStack(value.stack ?? [])) estimate *= node.op === 'array' ? node.count : 2;
if (value.shapeKeys !== undefined) agentSceneModule('mesh').normalizeShapeKeys(value.shapeKeys);
if (value.smoothAngle !== undefined && (value.smoothAngle < 0 || value.smoothAngle > 180)) {
throw invalidField('smoothAngle', value.smoothAngle, 'degrees from 0 to 180, such as 30');
}
// Edits can grow the mesh; the real size is checked against maxVertices after generation.
return estimate * 2;
}
}
}
// One Voronoi piece of the geometry named by `source`. Its size is only bounded by the source, so it is checked against maxVertices once built.
function fragmentEstimate(value, scope) {
if (typeof value.source !== 'string') {
throw invalidField('source', value.source, 'the ID of a convex geometry in geometries, such as "wall"', TypeError);
}
const cells = integer(value.cells, 2, 64, 'cells');
integer(value.index, 0, cells - 1, 'index');
integer(value.seed ?? 1, 0, 4294967295, 'seed');
if (value.impact !== undefined) vector(value.impact, 3, 'impact');
if (value.impactRadius !== undefined && !(value.impactRadius > 0)) {
throw invalidField('impactRadius', value.impactRadius, 'a distance above 0 in the source local space, such as 0.5');
}
if (!scope.definitions) return 16 * cells;
const source = scope.definitions.get(value.source);
if (!source || source.type === 'fragment') {
const reason = source ? 'a geometry that is not itself a fragment' : `the ID of a geometry in geometries, one of ${[...scope.definitions.keys()].slice(0, 8).join(', ') || 'none yet'}`;
throw invalidField(`geometries.${value.id}.source`, value.source, reason);
}
return geometryEstimate(source, { definitions: scope.definitions, chain: [] }) + 16 * cells;
}
function hasInstancedNodes(nodes) {
return !Array.isArray(nodes) || nodes.some(node => node && typeof node === 'object' && Object.hasOwn(node, 'instances'));
}
function isCutterReference(cutter) {
return Object.hasOwn(cutter, 'geometry');
}
function meshCutterScope(meshDefinition, scope) {
return scope && { definitions: scope.definitions, chain: scope.chain.length ? scope.chain : [meshDefinition.id] };
}
function cutterEstimate(cutter, scope) {
if (isCutterReference(cutter)) return referencedCutterEstimate(cutter, scope);
if (cutter.type === 'mesh' || Object.hasOwn(cutter, 'id')) {
throw invalidField('cutter', cutter, 'a primitive or profile record without an id, such as { "type": "box" } (box, cylinder, sphere, torus, lathe, extrude or tube), or { "geometry": "<recipe geometry id>" }', TypeError);
}
return geometryEstimate({ id: 'cutter', ...cutter });
}
// A cutter naming a recipe geometry. scope.chain lists the meshes on the way here, the first being the mesh being built.
function referencedCutterEstimate(cutter, scope) {
if (Object.keys(cutter).length !== 1 || typeof cutter.geometry !== 'string') {
throw invalidField('cutter', cutter, 'only { "geometry": "<recipe geometry id>" }; put translation, rotation and scale on the boolean edit', TypeError);
}
if (!scope) {
throw invalidField('cutter.geometry', cutter.geometry, 'a primitive or profile record such as { "type": "box" }; only recipe meshes can name another geometry');
}
const chain = [...scope.chain, cutter.geometry];
if (chain.indexOf(cutter.geometry) !== chain.length - 1) {
throw invalidField('cutter.geometry', chain.join(' -> '), `a geometry that does not cut with itself; remove ${cutter.geometry} from the cutters of ${scope.chain[scope.chain.length - 1]} or give it another cutter`);
}
if (chain.length - 1 > MAX_CUTTER_DEPTH) {
throw invalidField('cutter.geometry', chain.join(' -> '), `a chain of at most ${MAX_CUTTER_DEPTH} cutter geometries; build the inner cutters into one geometry`);
}
if (!scope.definitions) return 0;
const definition = scope.definitions.get(cutter.geometry);
if (!definition) {
throw invalidField('cutter.geometry', chain.join(' -> '), `the ID of a geometry in geometries, one of ${[...scope.definitions.keys()].join(', ') || 'none yet'}; add ${cutter.geometry} or pick one of them`);
}
return geometryEstimate(definition, { definitions: scope.definitions, chain });
}
function namesCutterGeometry(edit) {
return edit?.op === 'boolean' && typeof edit.cutter?.geometry === 'string';
}
// The records of the cutter geometries a mesh names, nested ones included: what its result depends on beyond its own record.
function cutterDependencySignature(meshDefinition, definitions) {
const parts = [];
for (const edit of meshDefinition.edits ?? []) {
if (!namesCutterGeometry(edit)) continue;
const definition = definitions.get(edit.cutter.geometry);
parts.push(JSON.stringify(definition), cutterDependencySignature(definition, definitions));
}
return parts.join('|');
}
// Validates the cutter chain (cycles, depth, missing IDs, work) before returning its signature, so the signature walk ends.
function checkedCutterDependencies(meshDefinition, definitions) {
if (!(meshDefinition.edits ?? []).some(namesCutterGeometry)) return '';
geometryEstimate(meshDefinition, { definitions, chain: [] });
return cutterDependencySignature(meshDefinition, definitions);
}
/** Cache identity of a geometry record: its own fields plus the cutter geometries it depends on. */
function geometrySignature(definition, definitions) {
if (definition.type === 'fragment') {
// The pieces depend on the source record, so editing the source changes the key. Estimating first rejects a missing or fragment source.
geometryEstimate(definition, { definitions, chain: [] });
return `${JSON.stringify(definition)}|source|${geometrySignature(definitions.get(definition.source), definitions)}`;
}
if (definition.type === 'dented') {
geometryEstimate(definition, { definitions, chain: [] });
return `${JSON.stringify(definition)}|source|${geometrySignature(definitions.get(definition.source), definitions)}`;
}
const dependencies = definition.type === 'mesh' ? checkedCutterDependencies(definition, definitions) : '';
return dependencies ? `${JSON.stringify(definition)}|cutters|${dependencies}` : JSON.stringify(definition);
}
function geometryDefinitions(geometries) {
return new Map(geometries.map(definition => [definition.id, definition]));
}
function cutterScopeOf(geometries) {
return { definitions: geometryDefinitions(geometries), chain: [] };
}
/** Render geometry of a boolean cutter record, checked like the cutters of recipe meshes. Used by imported-part edits. */
export function generateCutterGeometry(cutter, maxVertices) {
cutterEstimate(cutter);
return generateGeometry(cutter, maxVertices);
}
function generateGeometry(value, maxVertices, scope) {
switch (value.type) {
case 'box':
return box(value.bevel, value.subdivisions);
case 'cylinder':
return cylinder(value.segments, value.bevel, value.bevelSegments);
case 'sphere':
return sphere(value.segments, value.rings);
case 'grid':
case 'plane':
return grid(value.segments);
case 'cone':
return cone(value.radiusTop, value.radiusBottom, value.segments);
case 'icoSphere':
return icoSphere(value.subdivisions);
case 'circle':
return circle(value.segments, value.innerRadius);
case 'line':
return agentSceneModule('modeling').curve(lineEnds(value), { radius: value.radius, radialSegments: value.radialSegments, resolution: 1, maxVertices });
case 'torus':
return torus(value.tubeRadius, value.segments, value.sides, value.arc, value.start);
case 'lathe':
return agentSceneModule('modeling').lathe(value.profile, { ...value, maxVertices });
case 'extrude':
return agentSceneModule('modeling').extrude(value.contour, { ...value, maxVertices });
case 'tube':
return agentSceneModule('modeling').tube(value.path, { ...value, maxVertices });
case 'sdf':
return agentSceneModule('modeling').sdfGeometry(value, maxVertices);
case 'curve':
return agentSceneModule('modeling').curveGeometry(value, maxVertices);
case 'text':
return agentSceneModule('text').text(value.text, { ...value, maxVertices });
case 'terrain':
return agentSceneModule('terrain').generateTerrainGeometry(value, maxVertices);
case 'cloud':
return agentSceneModule('modeling').cloudGeometry(value, maxVertices);
case 'fragment': {
if (!scope) throw invalidField('type', 'fragment', 'a geometry inside a recipe, where its source geometry is found by ID');
const source = scope.definitions.get(value.source);
return agentSceneModule('fracture').fragmentGeometry(value, geometrySignature(source, scope.definitions),
() => generateGeometry(source, maxVertices, { definitions: scope.definitions, chain: [] }));
}
case 'dented': {
if (!scope) throw invalidField('type', 'dented', 'a geometry inside a recipe, where its source geometry is found by ID');
const { source, id, type, ...dent } = value;
return agentSceneModule('vehicleDamage').dentGeometry(generateGeometry(scope.definitions.get(source), maxVertices, { definitions: scope.definitions, chain: [] }), dent);
}
case 'mesh': {
const cutterScope = meshCutterScope(value, scope);
const dependencies = scope ? checkedCutterDependencies(value, scope.definitions) : '';
return agentSceneModule('mesh').generateMeshGeometry(() => meshBaseSplitsBox(value.base) ? box(0, value.base.subdivisions, true) : generateGeometry(value.base, maxVertices), value.edits ?? [], {
maxVertices, smoothAngle: value.smoothAngle,
stack: value.stack ?? [], shapeKeys: value.shapeKeys ?? [],
// The edits only name a cutter geometry, so that geometry's own record joins the key: editing it changes the key.
cacheKey: dependencies ? `${JSON.stringify(value.base)}|cutters|${dependencies}` : JSON.stringify(value.base),
resolveCutter: cutter => {
cutterEstimate(cutter, cutterScope);
if (!isCutterReference(cutter)) return generateGeometry(cutter, maxVertices);
const chain = [...cutterScope.chain, cutter.geometry];
return generateGeometry(scope.definitions.get(cutter.geometry), maxVertices, { definitions: scope.definitions, chain });
},
});
}
}
}
/** Render geometry of a candidate recipe's geometry by ID, for an operation that needs the real mesh (fracture-node). */
function generateOperationGeometry(candidate, geometryId, limits) {
const definitions = geometryDefinitions(candidate.geometries);
const definition = definitions.get(geometryId);
if (!definition) {
throw invalidField('node', geometryId, `a node whose geometry exists; add the geometry ${geometryId} first`);
}
geometryEstimate(definition, { definitions, chain: [] });
return generateGeometry(definition, Math.min(limits.maxVertices, 1_000_000), { definitions, chain: [] });
}
function compile(recipe, geometries, localBounds, limits) {
const materials = new Map(recipe.materials.map(material => [material.id, material]));
const graph = createSceneGraph(recipe.nodes.map(node => {
if (node.geometry !== undefined && (!geometries.has(node.geometry) || !materials.has(node.material))) {
const missingField = geometries.has(node.geometry) ? 'material' : 'geometry';
throw invalidField(`nodes.${node.id}.${missingField}`, node[missingField], `one of ${(geometries.has(node.geometry) ? [...materials.keys()] : [...geometries.keys()]).join(', ')}`);
}
return { name: node.id, parent: node.parent,
matrix: node.assetPart ? mat4.clone(node.assetPart.matrix) : mat4.fromRotationTranslationScale(mat4.create(), node.rotation, node.translation, node.scale),
geometry: geometries.get(node.geometry), material: materials.get(node.material) };
}), limits);
validateGraph(graph, localBounds);
return graph;
}
function validateGraph(graph, localBounds) {
const normal = mat3.create();
for (const node of graph.nodes) {
if (!mat3.normalFromMat4(normal, node.worldMatrix) || !normal.every(Number.isFinite)) {
throw new RangeError(`Node ${node.name} normal transform exceeds Float32 range.`);
}
if (node.geometry) {
const bounds = localBounds.get(node.geometry);
const matrix = node.worldMatrix;
for (let corner = 0; corner < 8; corner++) {
const pointX = corner & 1 ? bounds.max[0] : bounds.min[0];
const pointY = corner & 2 ? bounds.max[1] : bounds.min[1];
const pointZ = corner & 4 ? bounds.max[2] : bounds.min[2];
for (let axis = 0; axis < 3; axis++) {
// Bound every multiplication and possible addition order, before cancellation.
const absoluteSum = Math.abs(matrix[axis] * pointX) + Math.abs(matrix[4 + axis] * pointY) +
Math.abs(matrix[8 + axis] * pointZ) + Math.abs(matrix[12 + axis]);
if (!Number.isFinite(Math.fround(absoluteSum))) {
throw new RangeError(`Node ${node.name} world geometry bounds exceed Float32 range.`);
}
}
}
}
}
}
function boundsFor(geometry, matrix) {
const minimum = [Infinity, Infinity, Infinity];
const maximum = [-Infinity, -Infinity, -Infinity];
const positions = geometry.positions;
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 };
}
// An armature's nodes come first and are regenerated from it each time, so edits go through armatures, not through bone nodes.
function addArmatures(recipe, limits) {
if (!Object.hasOwn(recipe, 'armatures')) {
for (const node of recipe.nodes) {
if (node.skin) {
throw invalidField(`nodes.${node.id}.skin`, node.skin, 'a skin only when the recipe has armatures; add an armatures list or remove skin');
}
}
return;
}
const userNodes = new Map(recipe.nodes.map(node => [node.id, node]));
const resolveBounds = (armature, nodeId) => {
const node = userNodes.get(nodeId);
if (!node?.geometry) {
throw invalidField(`armatures.${armature.id}.fit`, nodeId, 'the ID of a mesh node with a geometry, such as one scene_inspect lists');
}
const definition = recipe.geometries.find(geometry => geometry.id === node.geometry);
const bounds = boundsFor(generateGeometry(definition, Math.min(limits.maxVertices, 1_000_000), cutterScopeOf(recipe.geometries)), mat4.create());
const toArmature = mat4.invert(mat4.create(), restWorldMatrix(armature.id, userNodes, [armature]));
const toWorld = restWorldMatrix(node.id, userNodes);
return transformedBounds(bounds, mat4.multiply(mat4.create(), toArmature, toWorld));
};
recipe.armatures = normalizeArmatures(recipe.armatures, { resolveBounds });
const derived = recipe.armatures.flatMap(armatureNodes);
for (const node of derived) {
if (userNodes.has(node.id)) {
throw invalidField(`armatures.${node.id}`, node.id, 'a bone node ID no other node uses; give the armature a prefix, such as "rig-"');
}
}
if (new Set(derived.map(node => node.id)).size !== derived.length) {
throw invalidField('armatures', recipe.armatures.map(armature => armature.id), 'armatures that generate different node IDs; give one a prefix, such as "rig-"');
}
for (const node of recipe.nodes) {
if (node.skin && !recipe.armatures.some(armature => armature.id === node.skin.armature)) {
throw invalidField(`nodes.${node.id}.skin.armature`, node.skin.armature, `one of ${recipe.armatures.map(armature => armature.id).join(', ')}`);
}
}
recipe.nodes = [...derived, ...recipe.nodes];
}
const DEFAULT_MATERIAL_ID = 'default';
/**
* A node that names a geometry and no material gets the material "default" (neutral grey, every field at its default),
* added to the recipe when it is missing, so the normalized and exported recipe stays explicit.
*/
function withDefaultMaterial(recipe) {
const materials = recipe.materials;
const nodes = Array.isArray(recipe.nodes) ? recipe.nodes : [];
const unpainted = nodes.filter(node => node?.geometry !== undefined && node.material === undefined);
if (unpainted.length === 0 || !Array.isArray(materials)) {
return materials;
}
for (const node of unpainted) {
node.material = DEFAULT_MATERIAL_ID;
}
const alreadyDefined = materials.some(material => material?.id === DEFAULT_MATERIAL_ID);
return alreadyDefined ? materials : [...materials, { id: DEFAULT_MATERIAL_ID }];
}
// A name that matches no node would leave the light lighting nothing without a sign, so it fails and says what to do.
function checkLightLinkNames(recipe) {
if (!environmentLinksLights(recipe.environment)) {
return;
}
const unknown = agentSceneModule('lightLinking').unknownLightLinkNames(recipe.environment, recipe.nodes);
if (unknown.length > 0) {
throw invalidField('environment.keyAffects', unknown.slice(0, 4), 'node IDs that exist in nodes in every affects list; scene_inspect lists them');
}
}
// A typo in lines.nodes would turn nothing off without a sign. A node that exists but is hidden stays valid.
function checkLineNodeNames(recipe) {
const lines = recipe.environment?.lines;
if (!lines?.nodes) {
return;
}
const unknown = agentSceneModule('lineArt').unknownLineNodeNames(lines, recipe.nodes);
if (unknown.length > 0) {
throw invalidField('environment.lines.nodes', unknown.slice(0, 4), `node IDs that exist in nodes${unknown.length > 4 ? ` (${unknown.length - 4} more are unknown too)` : ''}; scene_inspect lists them. After remove-node, drop that node's entry from lines.nodes in the same call`);
}
// A group that draws nothing itself (an expanded instances node, a plain group) would do nothing without a sign.
// A placed asset, vegetation and crowd nodes are groups too, but their parts name them in `group`.
const drawsNothing = recipe.nodes.find(node => Object.hasOwn(lines.nodes, node.id) && node.geometry === undefined && !node.asset && !node.vegetation);
if (drawsNothing) {
const childIds = recipe.nodes.filter(node => node.parent === drawsNothing.id).map(node => node.id);
throw invalidField(`environment.lines.nodes.${drawsNothing.id}`, drawsNothing.id, `the ID of a node that draws a part; ${JSON.stringify(drawsNothing.id)} is a group with no geometry of its own. ${childIds.length > 0 ? `Name its children instead, such as ${childIds.slice(0, 3).join(', ')}` : 'It has no children, so remove its entry from lines.nodes'}`);
}
}
// Every light's affects list in light order: the mask of a part depends on these lists and nothing else of the environment.
function lightLinksKey(environment) {
const lights = [...environment.pointLights, ...(environment.spotLights ?? []), ...(environment.areaLights ?? [])];
return JSON.stringify([environment.keyAffects ?? null, ...lights.map(light => light.affects ?? null)]);
}
// A part that a light skips needs its own material object with the light mask, but it must still read every other
// field from the live material, so motion tracks keep driving it. One wrapper per material and mask keeps batches.
function linkedMaterial(liveMaterial, lightMask, wrappers) {
const byMask = wrappers.get(liveMaterial) ?? new Map();
wrappers.set(liveMaterial, byMask);
if (!byMask.has(lightMask)) {
const wrapper = {};
for (const field of Object.keys(liveMaterial)) {
Object.defineProperty(wrapper, field, { enumerable: true, get: () => liveMaterial[field] });
}
Object.defineProperty(wrapper, 'lightMask', { enumerable: true, value: lightMask });
byMask.set(lightMask, Object.freeze(wrapper));
}
return byMask.get(lightMask);
}
// Nodes the normalizer returned that nothing rewrites afterwards; a staged recipe is read-only, so a later edit that shares them skips checking them again.
const NORMALIZED_NODES = new WeakSet();
function normalizeRecipe(input, limits, { alreadyCopied = false } = {}) {
let recipe = alreadyCopied ? input : copiedJson(input, limits.maxRecipeBytes);
knownKeys(recipe, ['format', 'schemaVersion', 'geometries', 'materials', 'nodes', 'armatures', 'camera', 'environment', 'effects', 'shadow', 'motion', 'physics', 'cloth', 'timeline', 'particles', 'bake', 'postPasses', 'game'], 'recipe');
recipe.format = currentFormatName(recipe.format);
if (recipe.format !== 'crucible.scene' || recipe.schemaVersion !== 1) {
throw invalidField(recipe.format !== 'crucible.scene' ? 'format' : 'schemaVersion', recipe.format !== 'crucible.scene' ? recipe.format : recipe.schemaVersion, recipe.format !== 'crucible.scene' ? '"crucible.scene"' : '1');
}
// A scene with no mesh, or whose nodes all take the default material, has nothing to list: absent means empty.
// Placed assets generate their own geometries, materials and part nodes each time; an exported or checkpointed recipe may still carry them.
recipe.geometries ??= [];
recipe.materials ??= [];
if (Array.isArray(recipe.geometries)) recipe.geometries = recipe.geometries.filter(geometry => geometry?.type !== 'asset');
if (Array.isArray(recipe.materials)) recipe.materials = recipe.materials.filter(material => !material?.assetSource);
if (Array.isArray(recipe.nodes)) recipe.nodes = recipe.nodes.filter(node => !node?.assetPart);
recipe.geometries = resources(recipe.geometries, limits.maxGeometries, 'geometries', value => {
geometryEstimate(value);
const definition = { id: value.id, type: value.type === 'plane' ? 'grid' : value.type };
for (const field of GEOMETRY_FIELDS[value.type]) {
if (Object.hasOwn(value, field)) {
definition[field] = value[field];
}
}
return definition;
});
// Every geometry exists now, so cutter IDs, cycles, depth and work can be checked.
const definitionsById = geometryDefinitions(recipe.geometries);
recipe.geometries.forEach((definition, index) => {
if (definition.type === 'mesh') withFieldPrefix(`geometries[${index}]`, () => checkedCutterDependencies(definition, definitionsById));
});
recipe.materials = resources(withDefaultMaterial(recipe), limits.maxMaterials, 'materials', materialFrom);
const distinctPatterns = new Set(recipe.materials.filter(material => material.pattern).map(material => JSON.stringify(material.pattern)));
if (distinctPatterns.size > MAX_MATERIAL_PATTERNS) {
throw invalidField('materials', `${distinctPatterns.size} different patterns`, `at most ${MAX_MATERIAL_PATTERNS} different material patterns; reuse one and tint it with color`);
}
recipe.nodes = withoutArmatureNodes(recipe.nodes);
if (hasInstancedNodes(recipe.nodes)) recipe.nodes = agentSceneModule('mesh').expandInstancedNodes(recipe.nodes, {
maxNodes: limits.maxNodes,
resolveSurface: id => {
const definition = recipe.geometries.find(geometry => geometry.id === id);
if (!definition) throw invalidField('instances.surface', id, `the ID of a geometry in geometries, such as ${recipe.geometries[0]?.id ?? 'ground'}`);
return generateGeometry(definition, Math.min(limits.maxVertices, 1_000_000), cutterScopeOf(recipe.geometries));
},
}, recipe.geometries);
recipe.nodes = resources(recipe.nodes, limits.maxNodes, 'nodes', nodeFrom, { alreadyNormalized: NORMALIZED_NODES, isShareable: node => NODE_KEYS_NEEDING_OWN_COPY.every(key => node[key] === undefined) });
addArmatures(recipe, limits);
if (recipe.nodes.some(node => node.relations !== undefined)) {
recipe.nodes = agentSceneModule('relations').normalizeRelations(recipe.nodes);
}
recipe.camera = cameraFrom(recipe.camera);
const look = {};
for (const field of ['environment', 'effects', 'shadow']) {
if (Object.hasOwn(recipe, field)) {
look[field] = recipe[field];
}
}
Object.assign(recipe, normalizeAgentLook(look));
if (recipe.camera.fStop !== undefined && recipe.effects?.depthOfField.blur > 0) {
throw invalidField('camera.fStop', recipe.camera.fStop, 'a camera without effects.depthOfField.blur above 0; set blur to 0 or remove fStop');
}
checkLightLinkNames(recipe);
checkLineNodeNames(recipe);
if (recipe.effects?.distortion || recipe.effects?.flash) agentSceneModule('postSteps').checkAirStepNodes(recipe);
if (Object.hasOwn(recipe, 'motion')) {
recipe.motion = recipe.motion === null || recipe.motion === undefined ? null : agentSceneModule('motion').normalizeAgentMotion(recipe.motion, recipe);
}
if (Object.hasOwn(recipe, 'physics')) {
recipe.physics = agentSceneModule('physics').normalizeAgentPhysics(recipe.physics, recipe);
}
if (Object.hasOwn(recipe, 'cloth')) {
recipe.cloth = agentSceneModule('cloth').normalizeAgentCloth(recipe.cloth, recipe);
}
if (Object.hasOwn(recipe, 'timeline')) {
if (recipe.timeline === null) {
delete recipe.timeline;
} else {
recipe.timeline = agentSceneModule('timeline').normalizeFilmTimeline(recipe.timeline, recipe, { checkCamera: shotCameraOverrides => cameraOverridesFrom(recipe.camera, shotCameraOverrides) });
}
}
if (Object.hasOwn(recipe, 'particles')) {
recipe.particles = agentSceneModule('particles').normalizeAgentParticles(recipe.particles, recipe);
}
if (Object.hasOwn(recipe, 'bake')) {
recipe.bake = recipe.bake === null ? null : agentSceneModule('bake').normalizeAgentBake(recipe.bake);
}
if (Object.hasOwn(recipe, 'postPasses')) recipe.postPasses = agentSceneModule('userPass').normalizeUserPasses(recipe.postPasses ?? []);
if (Object.hasOwn(recipe, 'game')) {
if (recipe.game === null) delete recipe.game;
else recipe.game = agentSceneModule('game').normalizeGameSetup(recipe.game, recipe.nodes);
}
if (alreadyCopied) {
// The input was checked JSON and each step above returns checked JSON, so only the size can have grown.
assertWithinRecipeBytes(new TextEncoder().encode(JSON.stringify(recipe)).length, limits.maxRecipeBytes);
return recipe;
}
recipe = copiedJson(recipe, limits.maxRecipeBytes);
return recipe;
}
// A shot camera is a partial camera: it must be valid on top of the recipe camera, and only its own fields are kept.
function cameraOverridesFrom(baseCamera, overrides) {
cameraFrom({ ...baseCamera, ...overrides });
return structuredClone(overrides);
}
function geometryStats(records) {
let vertices = 0;
let geometryBytes = 0;
let estimatedGeometryBytes = 0;
for (const record of records) {
vertices += record.vertices;
geometryBytes += record.geometryBytes;
estimatedGeometryBytes += record.estimatedVertices * 56;
}
return { vertices, geometryBytes, estimatedGeometryBytes };
}
function batchSignature(material) {
// Textures are fixed per renderer, so a changed pattern rebuilds it like a changed tag does.
// Transmission moves a material to the pass that sees the opaque scene, which is fixed per renderer.
return `${material.tag}|${material.alphaMode}|${material.opacity}|${material.transmission > 0}|${material.doubleSided}|${JSON.stringify(material.pattern ?? material.map ?? null)}|${JSON.stringify(material.snippet)}`;
}
function materialHandle(snapshot, sequence, images) {
const holder = { snapshot, sequence, images };
const output = {};
for (const field of ['id', 'tag', ...MATERIAL_FIELDS]) {
Object.defineProperty(output, field, {
enumerable: true,
configurable: true,
get() {
return holder.snapshot[field];
},
});
}
for (const field of PATTERN_TEXTURE_FIELDS) {
Object.defineProperty(output, field, {
enumerable: true,
// Baked on first read, so validating or inspecting a recipe never pays for it.
get() {
if (field === 'map' && holder.sequence) return holder.sequence.descriptor;
return holder.snapshot.pattern ? agentSceneModule('patterns').materialPatternTextures(holder.snapshot.pattern, holder.images)[field] : undefined;
},
});
}
return { holder, output: Object.freeze(output) };
}
function immutableMaterial(snapshot) {
for (const field of ['color', 'emissiveColor', 'absorption', 'aov']) {
if (snapshot[field]) {
Object.freeze(snapshot[field]);
}
}
return Object.freeze(snapshot);
}
const NO_ASSETS = Object.freeze({ placements: [], animators: [], geometryParts: new Map(), materialOutputs: new Map(), partExtras: new Map() });
// A placed asset's material is the decoded one, shared by every placement that uses the same overrides.
// The fields a motion track drives on a placed asset's material; every other field keeps its decoded value, textures included.
const ANIMATED_ASSET_FIELDS = ['color', 'emissiveColor', 'emission', 'metallic', 'roughness'];
// A decoded material is frozen, so a handled override gets a view of it that reads the animated fields from the live snapshot.
function liveAssetOutput(decoded, holder) {
const output = {};
for (const field of Object.keys(decoded)) {
Object.defineProperty(output, field, { enumerable: true, configurable: true, get: () => decoded[field] });
}
for (const field of ANIMATED_ASSET_FIELDS) {
Object.defineProperty(output, field, {
enumerable: true,
configurable: true,
get() {
const value = holder.snapshot[field];
// Same rule as materialOutput: emission with no emissive colour glows white.
if (field === 'emissiveColor' && holder.snapshot.emission > 0 && !value?.some(component => component > 0)) return Object.freeze([1, 1, 1]);
return value;
},
});
}
return Object.freeze(output);
}
function assetMaterialHandle(snapshot, output, ...candidates) {
const reusable = candidates.find(handle => handle?.source === output);
if (reusable) return reusable;
const holder = { snapshot };
return { holder, output: snapshot.animatable === true ? liveAssetOutput(output, holder) : output, source: output };
}
function retainedMatrices(parts) {
for (const part of parts) {
if (part.matrix.length !== 16 || part.matrix.byteLength !== 64) {
throw new RangeError('Retained render matrices must not be detached.');
}
}
}
function cameraPoseFrom(pose) {
const camera = cameraFrom({
eye: Array.from(pose.eye), target: Array.from(pose.target), up: Array.from(pose.up),
...(pose.focalLength === undefined ? { fov: pose.fov } : {}), near: pose.near, far: pose.far,
...Object.fromEntries(CAMERA_LENS_FIELDS.filter(field => pose[field] !== undefined).map(field => [field, pose[field]])),
});
const view = mat4.lookAt(mat4.create(), camera.eye, camera.target, camera.up);
for (const aspect of [1 / 16, 16]) {
const projection = applyProjection(mat4.create(), camera, aspect);
const combined = mat4.multiply(mat4.create(), projection, view);
if (![projection, combined].every(matrix => matrix.every(Number.isFinite))) {
throw new RangeError('Motion camera matrices exceed the supported Float32 aspect range.');
}
}
return camera;
}
// Physics holds its last pose after its duration, so a seek past the end is the resting state.
function simulatedPose(stagedState, time) {
return time === null ? null : stagedState.physicsSampler?.sample(Math.min(time, stagedState.physicsSampler.duration));
}
/** The local transform of a node at a sampled motion and simulated pose: a body, then a track, then the rest value. */
function localTransformOf(node, sampled, simulated) {
const patch = sampled?.nodes.get(node.id);
const bodyPatch = simulated?.get(node.id);
return {
translation: bodyPatch?.translation ?? patch?.translation ?? node.translation,
rotation: bodyPatch?.rotation ?? patch?.rotation ?? node.rotation,
scale: patch?.scale ?? node.scale,
};
}
/** What a bake-motion operation samples: the committed scene's local node transforms at any time, without touching the pose. */
function motionBakeSource(stagedState) {
const nodesById = new Map(stagedState.recipe.nodes.map(node => [node.id, node]));
return {
animated: Boolean(stagedState.motionSampler || stagedState.physicsSampler),
motionDuration: stagedState.recipe.motion?.duration ?? 0,
physicsDuration: stagedState.physicsSampler?.duration ?? 0,
sampleLocalTransforms(time, ids) {
const sampled = stagedState.motionSampler?.sample(time) ?? null;
const simulated = simulatedPose(stagedState, time);
return new Map(ids.map(id => [id, localTransformOf(nodesById.get(id), sampled, simulated)]));
},
};
}
// Candidate buffers are private. A failed seek cannot publish half a pose to render handles.
function stagePose(stagedState, time) {
const sampled = time === null ? null : stagedState.motionSampler?.sample(time);
const hiddenNodes = hiddenNodeIds(stagedState.recipe, sampled);
const simulated = simulatedPose(stagedState, time);
const graph = stagedState.poseGraph ?? stagedState.graph;
if (stagedState.poseGraph) {
for (const node of stagedState.recipe.nodes) {
const { translation, rotation, scale } = localTransformOf(node, sampled, simulated);
if (Array.from(scale).some(component => !Number.isFinite(Math.fround(component)) || Math.fround(component) <= 0)) {
throw new RangeError('Motion scale must remain positive at Float32 precision.');
}
if (node.assetPart) {
graph.getNode(node.id).localMatrix.set(node.assetPart.matrix);
continue;
}
mat4.fromRotationTranslationScale(graph.getNode(node.id).localMatrix, rotation, translation, scale);
}
graph.update();
validateGraph(graph, stagedState.localBounds);
}
stageSkinPoses(stagedState.skinStages, graph);
const materialUpdates = [];
for (const material of stagedState.recipe.materials) {
const patch = sampled?.materials.get(material.id);
let snapshot = material;
if (patch) {
const definition = { ...material, ...patch };
for (const field of ['color', 'emissiveColor']) {
if (definition[field]) {
definition[field] = Array.from(definition[field]);
}
}
// A placed asset's material carries decoded fields that materialFrom does not know; only the driven fields change.
snapshot = immutableMaterial(material.assetSource ? definition : materialFrom(definition));
}
materialUpdates.push({ holder: stagedState.materialHandles.get(material.id).holder, snapshot });
}
const camera = sampled?.camera ? cameraPoseFrom(sampled.camera) : stagedState.recipe.camera;
retainedMatrices(stagedState.parts);
const clothGeometries = sampledGeometries(stagedState, time, sampled);
// Staged last: a pose pending on a decoded asset must be committed or discarded, so nothing above may throw after it.
const assetClips = stagedState.assetRuntime.animators.length ? agentSceneModule('assets').stageAssetClips(stagedState.assetRuntime, graph, time) : null;
const movedLook = stagedState.motionSampler && agentSceneModule('motion').motionMovesLook(sampled) ? sampled : null;
return { graph, materialUpdates, camera, time, clothGeometries, assetClips, hiddenNodes, movedLook, morphs: sampled?.morphs ?? null };
}
/** A mesh stack built with every ocean node's `time` set to `oceanTime`: the sea the renderer draws at that moment of an oceanTime track. */
function oceanTimeGeometry(recipe, maxGeometryVertices, geometryId, oceanTime, wakeField) {
const definition = recipe.geometries.find(candidate => candidate.id === geometryId);
const stack = definition.stack.map(node => (node.op === 'ocean' ? { ...node, ...wakeField, time: oceanTime } : node));
return Object.freeze(generateGeometry({ ...definition, stack }, maxGeometryVertices, cutterScopeOf(recipe.geometries)));
}
/**
* Geometries of mesh stacks whose ocean time a geometry track drives, keyed by node ID. Each one is built from the cached edits with
* every ocean node's `time` set to the sampled value, so it equals the still of a recipe that writes that time into the node. The last
* result of each geometry is kept, so a repeated time reuses the geometry and the renderer sees no change.
*/
function oceanTimeGeometries(stagedState, sampled, time) {
const patches = sampled?.geometries;
if (!patches?.size) {
return new Map();
}
const frames = stagedState.oceanFrames ??= new Map();
const geometries = new Map();
for (const [geometryId, patch] of patches) {
let frame = frames.get(geometryId);
const wakeField = stagedState.physicsSampler?.wakeField?.(geometryId, time);
const key = wakeField ? `${patch.oceanTime}|${time}` : patch.oceanTime;
if (frame?.key !== key) {
frame = { key, geometry: oceanTimeGeometry(stagedState.recipe, stagedState.maxGeometryVertices, geometryId, patch.oceanTime, wakeField) };
frames.set(geometryId, frame);
}
for (const node of stagedState.recipe.nodes) {
if (node.geometry !== geometryId) continue;
// A water part draws the ocean's foam group as foam, as the first build of the part does.
const material = stagedState.recipe.materials?.find(candidate => candidate.id === node.material);
const drawn = material && frame.geometry.vertexGroups?.foam ? agentSceneModule('mesh').waterFoamGeometry(frame.geometry, material) : frame.geometry;
geometries.set(node.id, drawn);
}
}
return geometries;
}
// Cloth and particles replace the geometry of their own nodes at a sampled time; no node belongs to both.
function sampledGeometries(stagedState, time, sampled) {
if (time === null) {
return null;
}
const geometries = oceanTimeGeometries(stagedState, sampled, time);
for (const sampler of [stagedState.clothSampler, stagedState.particleSampler]) {
sampler?.sample(time)?.forEach((geometry, nodeId) => geometries.set(nodeId, geometry));
}
return geometries.size ? geometries : null;
}
function partFlagsOf(node) {
const flags = Object.fromEntries(PART_FLAG_FIELDS.filter(flag => node[flag] !== undefined).map(flag => [flag, node[flag]]));
if (node.rayVisibility !== undefined) flags.rayVisibility = node.rayVisibility;
return flags;
}
function sameRayVisibility(first, second) {
return JSON.stringify(first ?? null) === JSON.stringify(second ?? null);
}
function sameRenderFlags(part, node, usesVisibility, assetExtras) {
return PART_FLAG_FIELDS.every(flag => part[flag] === (node[flag] ?? assetExtras?.[flag])) && sameRayVisibility(part.rayVisibility, node.rayVisibility) && Boolean(part.visibility) === usesVisibility;
}
function recipeUsesVisibility(recipe) {
return recipe.nodes.some(node => node.visible !== undefined) || Boolean(recipe.motion?.tracks?.some(track => track.kind === 'node' && track.property === 'visible'));
}
/** Node IDs hidden at a pose: a node set invisible by its field or a sampled track, and everything under it. */
function hiddenNodeIds(recipe, sampled) {
const hidden = new Set();
if (!recipeUsesVisibility(recipe)) return hidden;
const byId = new Map(recipe.nodes.map(node => [node.id, node]));
const hiddenOwn = node => {
const keyed = sampled?.nodes.get(node.id)?.visible;
return keyed === undefined ? node.visible === false : keyed < 0.5;
};
for (const node of recipe.nodes) {
for (let cursor = node, depth = 0; cursor && depth < 256; cursor = byId.get(cursor.parent), depth++) {
if (hiddenOwn(cursor)) {
hidden.add(node.id);
break;
}
}
}
return hidden;
}
// Cloth keeps one geometry per sheet that every sample rewrites, so the parts of a later seek are the previous ones and the
// renderer sees no topology change. Particles still bring a new geometry per time, so those parts are replaced.
function partsWithCloth(restParts, clothGeometries, previousParts) {
if (!clothGeometries) {
return restParts;
}
const next = restParts.map((part, index) => {
const geometry = clothGeometries.get(part.name);
return !geometry ? part : previousParts[index]?.geometry === geometry ? previousParts[index] : Object.freeze({ ...part, geometry });
});
return next.every((part, index) => part === previousParts[index]) ? previousParts : Object.freeze(next);
}
// A shape key weighs what its morph track samples at this time, or its starting value when no track names it.
function publishShapeKeyWeights(part, sampledMorphs) {
const { morphTargetNames, morphTargetValues, morphGrowth } = part.geometry;
if (!morphTargetNames || !part.morph) return;
if (morphGrowth) {
const growth = sampledMorphs?.get(morphGrowth.name)?.weight ?? morphGrowth.value;
agentSceneModule('modeling').growthWeights(morphGrowth.steps, growth).forEach((weight, index) => {
part.morph.weights[index] = weight;
});
return;
}
morphTargetNames.forEach((name, index) => {
part.morph.weights[index] = sampledMorphs?.get(name)?.weight ?? morphTargetValues[index];
});
}
/** Returns true when the parts handed to a renderer changed, which the caller counts as a topology change. */
function publishPose(stagedState, pose) {
for (const part of stagedState.restParts) {
if (part.visibility) part.visibility.visible = !pose.hiddenNodes.has(part.name);
Float32Array.prototype.set.call(part.matrix, pose.graph.getNode(part.name).worldMatrix);
publishShapeKeyWeights(part, pose.morphs);
}
for (const update of pose.materialUpdates) {
update.holder.snapshot = update.snapshot;
}
publishSkinPoses(stagedState.skinStages);
if (pose.assetClips) {
pose.assetClips.commit();
for (const part of stagedState.restParts) {
const matrix = pose.assetClips.matrices.get(part.name);
if (matrix) Float32Array.prototype.set.call(part.matrix, matrix);
}
}
for (const sequence of stagedState.sequences) sequence.seek(pose.time);
stagedState.renderCamera = pose.camera;
stagedState.movedLook = pose.movedLook;
stagedState.motionTime = pose.time;
const sampledParts = partsWithCloth(stagedState.restParts, pose.clothGeometries, stagedState.parts);
const partsChanged = sampledParts !== stagedState.parts;
stagedState.parts = partsChanged && stagedState.rankFlushParts ? stagedState.rankFlushParts(sampledParts) : sampledParts;
return partsChanged;
}
// The recipe an agent wrote: without the geometries, materials and part nodes that placed assets generate.
// The recipe without the nodes, geometries and materials a placed asset generates. Arrays are new, entries are shared.
function recipeWithoutAssetOutput(recipe) {
return {
...recipe,
nodes: recipe.nodes.filter(node => !node.assetPart),
geometries: recipe.geometries.filter(geometry => geometry.type !== 'asset'),
materials: recipe.materials.filter(material => !material.assetSource),
};
}
function authoredRecipe(recipe) {
return structuredClone(recipeWithoutAssetOutput(recipe));
}
// Node keys whose values the recipe normalizer may rebuild or rewrite in place, so a shared node could not be read-only.
const NODE_KEYS_NEEDING_OWN_COPY = ['assetPart', 'asset', 'vegetation', 'relations', 'skin', 'instances', 'armature'];
/**
* A copy of the staged recipe for a batch of plain field edits that clones only what the batch can change: the touched
* nodes, the materials and the small sections. Untouched nodes and the geometries stay shared with the staged recipe, which
* is read-only once committed and which the normalizer only reads from. Returns null when the recipe holds anything
* the normalizer could rewrite in place (placed assets, armatures, relations, instances), so the caller clones it all.
*/
function fieldEditCandidate(recipe, operations) {
const sharesSafely = !Object.hasOwn(recipe, 'armatures') &&
recipe.geometries.every(geometry => geometry.type !== 'asset') &&
recipe.materials.every(material => !material.assetSource) &&
recipe.nodes.every(node => NODE_KEYS_NEEDING_OWN_COPY.every(key => node[key] === undefined));
if (!sharesSafely) return null;
const touchedNodes = new Set(operations.filter(operation => operation.type === 'set-node').map(operation => operation.id));
const candidate = {};
for (const [key, value] of Object.entries(recipe)) {
if (key === 'geometries') candidate[key] = [...value];
else if (key === 'nodes') candidate[key] = value.map(node => (touchedNodes.has(node.id) ? structuredClone(node) : node));
else candidate[key] = structuredClone(value);
}
return candidate;
}
// The mesh geometry an edit names; `remedy` tells what to do when it is another type.
function meshGeometryTarget(candidate, operation, remedy) {
identifier(operation.geometry);
const target = candidate.geometries.find(geometry => geometry.id === operation.geometry);
if (!target) {
throw invalidField('geometry', operation.geometry, `one of ${[...candidate.geometries.map(known => known.id)].join(', ')}`);
}
if (target.type !== 'mesh') {
throw invalidField('geometry', operation.geometry, `the ID of a mesh geometry, but it is a ${target.type}. ${remedy(target.type)}`, TypeError);
}
return target;
}
function removeNode(candidate, operation) {
knownKeys(operation, ['type', 'id', 'recursive'], 'operation');
identifier(operation.id);
const recursive = operation.recursive === undefined ? false : operation.recursive;
if (typeof recursive !== 'boolean') {
throw invalidField('recursive', recursive, 'true or false', TypeError);
}
if (!candidate.nodes.some(node => node.id === operation.id)) {
throw invalidField('id', operation.id, 'the ID of a node in nodes; scene_inspect lists them');
}
const children = new Map();
for (const node of candidate.nodes) {
const siblings = children.get(node.parent) ?? [];
siblings.push(node.id);
children.set(node.parent, siblings);
}
if (!recursive && (children.get(operation.id)?.length ?? 0) > 0) {
throw invalidField('recursive', recursive, 'true for a node with children, such as true; or remove the children first');
}
const removed = new Set([operation.id]);
const pending = [operation.id];
if (recursive) {
for (let cursor = 0; cursor < pending.length; cursor++) {
for (const child of children.get(pending[cursor]) ?? []) {
if (!removed.has(child)) {
removed.add(child);
pending.push(child);
}
}
}
}
candidate.nodes = candidate.nodes.filter(node => !removed.has(node.id));
return removed;
}
/** A bounded CPU authoring session. Render adapters must treat geometry as immutable. */
export function createAgentScene(input, inputLimits = {}, options = {}) {
const limits = resolveLimits(inputLimits);
const assetOutputCache = new Map();
// The on-demand modules this scene's recipe and edits named. Default stages (flush ranking, floor sky) run only for these.
const requestedModules = new Set(defaultStageModulesNamed(input));
let state = null;
let revision = 0;
let topologyRevision = 0;
// Undo revisions the latest stage released to fit the vertex budget; the edit's answer tells the agent.
let releasedRevisionCount = 0;
let physicsBake = null;
let clothBake = null;
let particleBake = null;
let lightBake = null;
// Why the last stage's rebake could not run (a size limit), for the staged state to report.
let skippedBake = null;
let skippedReflections = null;
let lightLinkCache = null;
let objectReflectionCache = null;
// Puts the staged graph's matrices back when an edit that moved them in place is refused after the move.
let pendingGraphRestore = null;
const skinCache = new Map();
const checkpoints = new Map();
// The states before the last edits, oldest first, each with the revision number it had.
const revisionHistory = [];
function snapshotState() {
return {
// The staged recipe is read-only once committed and a restore copies the snapshot's recipe, so the snapshot shares it.
recipe: recipeWithoutAssetOutput(state.recipe),
geometryRecords: new Map(state.geometryRecords),
materialHandles: new Map(state.materialHandles),
restParts: state.restParts,
sourceRestParts: state.sourceRestParts,
};
}
function drawnNodeGeometry(id, label) {
identifier(id);
const node = state.recipe.nodes.find(value => value.id === id);
const geometry = node && state.geometries.get(node.geometry);
if (!geometry) throw invalidField(`path.${label}`, id, 'the ID of a node with a drawn geometry; scene_inspect lists node IDs');
return { geometry, worldMatrix: state.graph.getNode(id).worldMatrix };
}
// The route is computed over the authored pose of the ground and of the nodes to avoid, like the bounds in scene_inspect.
const pathQuery = query => agentSceneModule('navigation').resolvePathQuery(query, drawnNodeGeometry, boundsFor);
function ownedGeometryRecords() {
const records = new Set(state?.geometryRecords.values() ?? []);
const snapshots = [...checkpoints.values(), ...revisionHistory.map(entry => entry.snapshot)];
for (const snapshot of snapshots) {
for (const record of snapshot.geometryRecords.values()) {
records.add(record);
}
}
return records;
}
function geometryBudgetError({ residentStats, pendingVertices }, plans, budget, heldCheckpoints) {
const largest = plans.filter(plan => !plan.existing).sort((first, second) => second.estimatedVertices - first.estimatedVertices)[0];
const largestNote = largest === undefined ? 'no new geometry is added' : `largest new geometry "${largest.definition.id}" has ${largest.estimatedVertices}`;
return invalidField('geometry.vertices', residentStats.vertices + pendingVertices, `a geometry preflight peak of at most ${budget.maxVertices} vertices and ${budget.maxGeometryBytes} bytes (this needs ${residentStats.geometryBytes + pendingVertices * 56} bytes): ${residentStats.vertices} vertices are already held by the active scene, checkpoints and staged resources and ${pendingVertices} are new; ${largestNote}. Reduce detail${heldCheckpoints ? ' or release checkpoints' : ''}`);
}
// The edit only moves nodes of a plain scene (no relations, placed assets, armatures or motion) and every geometry is
// resident: the committed state's graph is moved in place instead of being built again.
function canMoveStagedGraph(recipe, movedNodeIds, assetRuntime) {
return Boolean(movedNodeIds && state && !state.poseGraph && assetRuntime === NO_ASSETS && !recipe.armatures &&
state.recipe.nodes.length === recipe.nodes.length && !recipe.nodes.some(node => node.relations?.length || node.assetPart || node.asset || node.vegetation));
}
function graphWithMovedNodes(recipe, movedNodeIds, localBounds) {
if (movedNodeIds.size === 0) return state.graph;
const matrices = new Map();
for (const node of recipe.nodes) {
if (movedNodeIds.has(node.id)) matrices.set(node.id, mat4.fromRotationTranslationScale(mat4.create(), node.rotation, node.translation, node.scale));
}
pendingGraphRestore = state.graph.replaceLocalMatrices(matrices);
validateGraph(state.graph, localBounds);
return state.graph;
}
function stage(inputRecipe, preferred = null, removedNodes = new Set(), removedMaterials = new Set(), inputIsOwnedJson = false, movedNodeIds = null) {
releasedRevisionCount = 0;
const recipe = normalizeRecipe(inputRecipe, limits, { alreadyCopied: inputIsOwnedJson });
const placedRuntime = recipe.nodes.some(node => node.asset)
? agentSceneModule('assets').expandAssetPlacements(recipe, options.assets, limits, assetOutputCache, recipe.nodes.some(node => node.asset?.drive) ? agentSceneModule('drive').createAssetDrive : null)
: NO_ASSETS;
// Grown vegetation travels the placed-asset channel; its module returns the placed runtime with its own parts added.
const assetRuntime = recipe.nodes.some(node => node.vegetation)
? agentSceneModule('vegetation').expandVegetation(recipe, limits, assetOutputCache, placedRuntime)
: placedRuntime;
// Placed assets and grown vegetation add part nodes, so the part names are checked after the expansion, like the render binds them.
if (recipe.environment.localVolumes) {
const partNodeIds = recipe.nodes.filter(node => node.geometry !== undefined).map(node => node.id);
checkLocalVolumePartNames(recipe.environment.localVolumes, partNodeIds);
}
if (state) {
retainedMatrices(state.parts);
}
const definitionsById = geometryDefinitions(recipe.geometries);
const planGeometry = () => {
const ownedRecords = ownedGeometryRecords();
const availableRecords = new Map();
for (const record of ownedRecords) {
availableRecords.set(record.signature, record);
}
const plans = recipe.geometries.map(definition => {
const signature = geometrySignature(definition, definitionsById);
const preferredRecord = preferred?.geometryRecords.get(definition.id);
const activeRecord = state?.geometryRecords.get(definition.id);
const existing = [preferredRecord, activeRecord, availableRecords.get(signature)]
.find(record => record?.signature === signature);
return { definition, signature, existing, estimatedVertices: definition.type === 'asset' ? 0 : geometryEstimate(definition, { definitions: definitionsById, chain: [] }) };
});
const residentStats = geometryStats(ownedRecords);
const pendingVertices = plans.filter(plan => !plan.existing).reduce((total, plan) => total + plan.estimatedVertices, 0);
const overBudget = residentStats.vertices + pendingVertices > limits.maxVertices ||
residentStats.geometryBytes + pendingVertices * 56 > limits.maxGeometryBytes;
return { plans, residentStats, pendingVertices, overBudget };
};
let planned = planGeometry();
// Automatic undo history never blocks an edit: drop the oldest kept revisions before refusing for budget.
while (planned.overBudget && revisionHistory.length > 0) {
revisionHistory.shift();
releasedRevisionCount++;
planned = planGeometry();
}
let { residentStats } = planned;
const { plans, pendingVertices } = planned;
if (planned.overBudget) {
throw geometryBudgetError(planned, plans, limits, checkpoints.size);
}
// Validate references, hierarchy and matrix arithmetic before generating any new resource.
const placeholders = new Map();
const placeholderBounds = new Map();
for (const plan of plans) {
const geometry = plan.existing?.geometry ?? Object.freeze({});
placeholders.set(plan.definition.id, geometry);
placeholderBounds.set(geometry, plan.existing?.bounds ?? { min: [0, 0, 0], max: [0, 0, 0] });
}
// With every geometry resident and no relations to solve, the compile below sees the same inputs and checks the same things.
const everyGeometryResident = plans.every(plan => plan.existing);
const compiledBelow = everyGeometryResident && !recipe.nodes.some(node => node.relations?.length);
const reusesGraph = everyGeometryResident && canMoveStagedGraph(recipe, movedNodeIds, assetRuntime);
if (!compiledBelow && !reusesGraph) compile(recipe, placeholders, placeholderBounds, limits);
const geometryRecords = new Map();
for (const plan of plans) {
let record = plan.existing;
if (!record && plan.definition.type === 'asset') {
// A decoded asset geometry is shared by every placement. Its size is bounded by the asset decoder, not by this scene's budget.
const geometry = assetRuntime.geometryParts.get(plan.definition.id);
record = Object.freeze({ signature: plan.signature, geometry, bounds: boundsFor(geometry, mat4.create()), vertices: 0, geometryBytes: 0, estimatedVertices: 0 });
} else if (!record) {
const geometry = Object.freeze(generateGeometry(plan.definition, Math.min(limits.maxVertices, 1_000_000), { definitions: definitionsById, chain: [] }));
const geometryBytes = Object.values(geometry).reduce((total, array) => total + array.byteLength, 0);
const vertices = geometry.positions.length / 3;
if (plan.definition.type === 'mesh' || plan.definition.type === 'fragment') {
// Edits can grow a mesh past its estimate. Undo history never blocks an edit, so release the oldest revisions before refusing.
while (revisionHistory.length > 0 && residentStats.vertices + pendingVertices - plan.estimatedVertices + vertices > limits.maxVertices) {
revisionHistory.shift();
releasedRevisionCount++;
residentStats = geometryStats(ownedGeometryRecords());
}
if (residentStats.vertices + pendingVertices - plan.estimatedVertices + vertices > limits.maxVertices) {
if (plan.definition.type === 'fragment') {
throw invalidField(`geometries.${plan.definition.id}`, `${vertices} render vertices`, 'pieces that fit maxVertices across the scene; use fewer cells or a coarser source geometry');
}
throw new RangeError(`Mesh ${plan.definition.id} has ${vertices} render vertices after its edits, which exceeds maxVertices across the scene. Reduce detail or edits.`);
}
} else if (vertices > plan.estimatedVertices || geometryBytes > plan.estimatedVertices * (56 + TERRAIN_SKY_VISIBILITY_BYTES)) {
throw new RangeError('Generated geometry exceeds its conservative preflight bound.');
}
record = Object.freeze({
signature: plan.signature, geometry,
bounds: boundsFor(geometry, mat4.create()),
vertices, geometryBytes, estimatedVertices: plan.estimatedVertices,
});
}
geometryRecords.set(plan.definition.id, record);
}
const geometries = new Map([...geometryRecords].map(([id, record]) => [id, record.geometry]));
const localBounds = new Map([...geometryRecords.values()].map(record => [record.geometry, record.bounds]));
if (recipe.nodes.some(node => node.relations?.length)) {
recipe.nodes = agentSceneModule('relations').solveRelations(recipe.nodes, (node, worldMatrix, region) => {
const geometry = geometries.get(node.geometry);
const regionGeometry = region === undefined ? geometry : agentSceneModule('mesh').taggedFacePositions(geometry, region);
return boundsFor(regionGeometry, worldMatrix);
});
}
const graph = (reusesGraph ? graphWithMovedNodes(recipe, movedNodeIds, localBounds) : compile(recipe, geometries, localBounds, limits));
const skinBindings = bindSkins({ recipe, graph, geometryRecords, cache: skinCache });
const materialHandles = new Map();
for (const material of recipe.materials) {
const snapshot = immutableMaterial(material);
const preferredHandle = preferred?.materialHandles.get(material.id);
const activeHandle = removedMaterials.has(material.id) ? null : state?.materialHandles.get(material.id);
// The renderer keeps tag, blending, opacity and sidedness per batch, so a handle is reused only when all match.
const existing = [preferredHandle, activeHandle].find(handle => handle && batchSignature(handle.holder.snapshot) === batchSignature(material));
const assetOutput = assetRuntime.materialOutputs.get(material.id);
const handle = assetOutput ? assetMaterialHandle(snapshot, assetOutput, preferredHandle, activeHandle) : existing ?? materialHandle(snapshot, material.map && agentSceneModule('assets').createTextureSequence(material.id, material.map, options.sequenceFrames), options.sequenceFrames);
materialHandles.set(material.id, handle);
}
const activeParts = new Map(state?.sourceRestParts.map(part => [part.name, part]) ?? []);
const preferredParts = new Map(preferred?.sourceRestParts.map(part => [part.name, part]) ?? []);
const usesVisibility = recipeUsesVisibility(recipe);
const nextParts = recipe.nodes.filter(node => node.geometry !== undefined).map(node => {
const binding = skinBindings.get(node.id);
const recipeMaterial = materialHandles.get(node.material);
const sourceGeometry = binding?.geometry ?? geometries.get(node.geometry);
const foamGeometry = sourceGeometry.vertexGroups?.foam ? agentSceneModule('mesh').waterFoamGeometry(sourceGeometry, recipeMaterial.output) : sourceGeometry;
const geometry = recipeMaterial.output.wear ? geometryWithSurfaceMasks(foamGeometry, recipeMaterial.output.wear, node.id) : foamGeometry;
// A graph with a vertexGroup node bakes with this mesh's weights, so its textures belong to the mesh.
const material = recipeMaterial.output.pattern?.graph ? agentSceneModule('patterns').materialViewForGeometry(recipeMaterial.output, geometry, node.id, recipeMaterial.holder.images) : recipeMaterial.output;
const assetExtras = assetRuntime.partExtras.get(node.id);
// Shape keys of a recipe mesh are morph targets with their own weights per part; an imported asset brings its own pose.
const shapeKeyMorph = geometry.morphTargetValues && !assetExtras?.morph ? { weights: Float32Array.from(geometry.morphTargetValues) } : undefined;
const activePart = removedNodes.has(node.id) ? null : activeParts.get(node.id);
const existing = [activePart, preferredParts.get(node.id)]
.find(part => part?.geometry === geometry && part.material === material && part.skin === (assetExtras?.skin ?? binding?.skin) && (assetExtras?.morph ? part.morph === assetExtras.morph : Boolean(part.morph) === Boolean(shapeKeyMorph)) && depthLayerOf(part) === depthLayerOf(node) && sameRenderFlags(part, node, usesVisibility, assetExtras));
return existing ?? Object.freeze({
name: node.id, geometry, material,
...(depthLayerOf(node) ? { depthLayer: depthLayerOf(node) } : {}),
...partFlagsOf(node),
// The renderer reads this holder every update, and publishPose rewrites it for each pose.
...(usesVisibility ? { visibility: { visible: true } } : {}),
matrix: new Float32Array(graph.getNode(node.id).worldMatrix),
...(binding ? { skin: binding.skin } : {}),
...(shapeKeyMorph ? { morph: shapeKeyMorph } : {}),
...assetExtras,
});
});
retainedMatrices(nextParts);
const sameParts = state && state.sourceRestParts.length === nextParts.length &&
state.sourceRestParts.every((part, index) => part === nextParts[index]);
const sourceRestParts = sameParts ? state.sourceRestParts : Object.freeze(nextParts);
const lightBakeResult = stageLightBake(recipe, sourceRestParts, graph);
const { reflected, restParts } = stageRestParts(recipe, sourceRestParts, lightBakeResult, graph);
const stagedState = {
recipe, geometryRecords, geometries, graph, materialHandles,
// Part identity decides what the next stage reuses, so it compares the parts as built, before any bake.
sourceRestParts,
parts: restParts, restParts,
// Parts a pose replaces (cloth, particles, ocean) are new objects with no flush rank, so the pose ranks them again.
rankFlushParts: parts => stageCoplanarOffsets(recipe, parts),
bakeSkipped: skippedBake,
reflectionSkipped: skippedReflections,
bakeReport: lightBakeResult ? agentSceneModule('bake').withLocalVolumeReport({ ...lightBakeResult.report, reused: lightBakeResult.reused }, recipe.environment.localVolumes) : null,
reflectionReport: reflected ? reflected.report : null,
// A renderer holding the deformed cloth parts of the old state needs the rest parts back as a topology change.
topologyChanged: Boolean(state && (restParts !== state.restParts || state.parts !== state.restParts)),
stats: geometryStats(geometryRecords.values()),
};
stagedState.assetRuntime = assetRuntime;
stagedState.maxGeometryVertices = Math.min(limits.maxVertices, 1_000_000);
stagedState.sequences = [...materialHandles.values()].map(handle => handle.holder.sequence).filter(Boolean);
stagedState.localBounds = localBounds;
stagedState.skinBindings = skinBindings;
stagedState.skinStages = createSkinStages(skinBindings);
stagedState.motionSampler = recipe.motion ? agentSceneModule('motion').compileAgentMotion(recipe.motion, recipe) : null;
stagedState.physicsSampler = stagePhysics(recipe, geometryRecords);
stagedState.clothSampler = stageCloth(recipe, geometryRecords, stagedState.motionSampler);
stagedState.particleSampler = stageParticles(recipe, geometryRecords, stagedState);
const animated = Boolean(stagedState.motionSampler || stagedState.physicsSampler || stagedState.clothSampler || stagedState.particleSampler || assetRuntime.animators.length);
stagedState.poseGraph = animated ? compile(recipe, geometries, localBounds, limits) : null;
stagedState.initialPose = stagePose(stagedState, animated ? 0 : null);
return stagedState;
}
// Parts a linked light skips carry a light mask in their material. The same parts and links give the same objects, so
// an edit that changes neither is not a topology change for the renderer.
function stageLightLinks(recipe, parts) {
if (!environmentLinksLights(recipe.environment)) {
return parts;
}
const { environment } = recipe;
const linksKey = lightLinksKey(environment);
if (lightLinkCache?.parts === parts && lightLinkCache.linksKey === linksKey) {
return lightLinkCache.linked;
}
const linking = agentSceneModule('lightLinking');
const masks = linking.lightMasksFor(parts, environment);
const wrappers = new Map();
const linked = Object.freeze(parts.map((part, index) => (masks[index] === ALL_LIGHTS_MASK ? part
: Object.freeze({ ...part, material: linkedMaterial(part.material, masks[index], wrappers) }))));
lightLinkCache = { parts, linksKey, linked };
return linked;
}
// The bake no longer matches the frame: motion moved a light, the sun or a part off the pose it was traced at.
// Only a scene with both a bake and motion pays for this check, and bake.rebake turns it off (it bakes each sampled pose).
function staleBakeProblems() {
return lightBake && state.recipe.bake && state.motionSampler ? agentSceneModule('bake').staleBakeProblems(state, lightBake.key) : [];
}
function stageRestParts(recipe, sourceRestParts, lightBakeResult, graph) {
const baked = lightBakeResult?.parts ?? sourceRestParts;
const reflected = stageObjectReflections(recipe, sourceRestParts, baked, graph);
return { reflected, restParts: stageCoplanarOffsets(recipe, stageLightLinks(recipe, stageFloorSky(recipe, reflected ? reflected.parts : baked))) };
}
// bake.rebake: a frame sampled at a pose the bake was not traced at is lit by a bake of that pose, cached by its key.
function rebakeAtPose(pose) {
const rebaked = lightBake && state.recipe.bake?.rebake && agentSceneModule('bake').bakeAtSampledPose(lightBake, state.recipe, pose);
if (rebaked) {
state.restParts = stageRestParts(state.recipe, state.sourceRestParts, rebaked, pose.graph).restParts;
state.bakeReport = agentSceneModule('bake').withLocalVolumeReport(rebaked.report, state.recipe.environment.localVolumes);
}
}
// A light bake costs seconds of ray tracing: it runs when the parts, the lights, the materials or the bake fields
// change, and every other edit, seek or camera move reuses the last result.
function stageLightBake(recipe, sourceRestParts, graph) {
skippedBake = null;
if (!recipe.bake) {
return null;
}
const worldMatrices = new Map(sourceRestParts.map(part => [part.name, new Float32Array(graph.getNode(part.name).worldMatrix)]));
const generatedGeometryGenerators = agentSceneModule('bake').bakeGenerators(recipe);
const key = agentSceneModule('bake').lightBakeKey(recipe, generatedGeometryGenerators, recipe.environment, worldMatrices);
if (lightBake?.key === key && lightBake.sourceRestParts === sourceRestParts) {
lightBake.currentKey = key;
return { ...lightBake, reused: true };
}
// The first build of a scene still fails loudly. A later edit stays applied: the old bake no longer fits the edited parts, so it is dropped.
const { baked, refusal } = agentSceneModule('bake').bakeUnlessRefused(Boolean(state), sourceRestParts, worldMatrices, recipe.environment, recipe.bake, generatedGeometryGenerators);
if (refusal) {
lightBake = null;
skippedBake = refusal;
return null;
}
lightBake = { key, currentKey: key, sourceRestParts, parts: baked.parts, report: baked.report };
return { ...lightBake, reused: false };
}
// Smooth metal parts get a probe of the scene around them (src/agent-reflections.js), unless environment.objectReflections
// is false. It runs only when that code is loaded, which a recipe with a metallic value of 0.5 or more does.
function stageObjectReflections(recipe, sourceRestParts, drawnParts, graph) {
skippedReflections = null;
if (recipe.environment.objectReflections === false || !agentSceneModuleLoaded('reflections')) {
return null;
}
objectReflectionCache = agentSceneModule('reflections').stageObjectReflections(objectReflectionCache, recipe, sourceRestParts, drawnParts, graph, agentEnvironmentMap(recipe.environment));
skippedReflections = objectReflectionCache.skipped;
return objectReflectionCache.result;
}
// A closed room a sun lights gets the sky each floor texel sees; the lazy module decides, keeps its result and honours environment.floorSkyTrace.
function stageFloorSky(recipe, parts) {
return agentSceneModuleActive('floorSky', requestedModules) ? agentSceneModule('floorSky').stageFloorSky(recipe.environment, parts) : parts;
}
// A scene that asks for no bake and looks like a closed room gets one diagnostic naming the bake. The ray test costs a
// few milliseconds, so it runs for scene_inspect only and is kept until the scene changes.
function isLitByLampsOnly(environment) {
const lampCount = (environment.pointLights?.length ?? 0) + (environment.spotLights?.length ?? 0) + (environment.areaLights?.length ?? 0);
const keyColor = environment.keyColor ?? [1, 1, 1];
const keyLight = (environment.keyIntensity ?? 1) * (keyColor[0] + keyColor[1] + keyColor[2]);
return lampCount > 0 && keyLight === 0;
}
let closedRoomCache = null;
function closedRoomProblems() {
if (state.recipe.bake) {
return [];
}
if (closedRoomCache?.revision !== revision) {
const worldMatrices = new Map(state.parts.map(part => [part, state.graph.getNode(part.name).worldMatrix]));
closedRoomCache = { revision, share: closedRoomShare(state.parts, worldMatrices) };
}
const { share } = closedRoomCache;
return share !== null && share >= CLOSED_ROOM_SHARE ? [closedRoomDiagnostic(share, isLitByLampsOnly(state.recipe.environment))] : [];
}
// Near-coplanar triangles are ranked at draw time (issue #751) unless environment.resolveCoplanar is false, once the
// coplanar code is loaded. The ranks sit beside the parts, so the parts and their geometry stay as they are. The search
// runs again only when the parts are new objects.
let flushCache = null;
function stageCoplanarOffsets(recipe, parts) {
if (!agentSceneModuleActive('coplanar', requestedModules)) {
return parts;
}
const coplanar = agentSceneModule('coplanar');
if (recipe.environment.resolveCoplanar === false) {
if (flushCache) {
coplanar.clearFlushParts(flushCache.parts);
}
flushCache = null;
return parts;
}
if (flushCache?.parts !== parts) {
const resolved = coplanar.resolveFlushParts(parts);
// Ranked parts batch apart, so the list they are staged in is a new one: the renderer then regroups, also when the
// ranking is switched on or off for parts that did not change.
flushCache = { parts, staged: resolved.ranked ? Object.freeze([...parts]) : parts, ...resolved };
}
return flushCache.staged;
}
// scene_inspect names what the ranking could not settle. A scene that opted out gets the pairs of parts that fight instead:
// that check is bounded, runs on inspect only and is kept until the scene changes.
let coplanarReportCache = null;
function coplanarProblems() {
if (!agentSceneModuleActive('coplanar', requestedModules)) {
return [];
}
if (state.recipe.environment.resolveCoplanar !== false) {
return agentSceneModule('coplanar').flushLeftoverDiagnostics(flushCache?.leftovers ?? []);
}
if (coplanarReportCache?.revision !== revision) {
const coplanar = agentSceneModule('coplanar');
coplanarReportCache = { revision, problems: coplanar.coplanarOverlapDiagnostics(coplanar.findCoplanarOverlaps(state.parts)) };
}
return coplanarReportCache.problems;
}
// A bake costs a solver run, so an unchanged section on unchanged geometry reuses the last one.
function stagePhysics(recipe, geometryRecords) {
if (!recipe.physics) {
return null;
}
const key = agentSceneModule('physics').physicsBakeKey(recipe, geometryRecords);
if (physicsBake?.key !== key) {
const geometries = new Map([...geometryRecords].map(([id, record]) => [id, record.geometry]));
physicsBake = { key, sampler: agentSceneModule('physics').bakeAgentPhysics(recipe.physics, recipe, geometries) };
}
return physicsBake.sampler;
}
// Same rule as physics: an unchanged cloth section on unchanged geometry and nodes reuses the last bake.
function stageCloth(recipe, geometryRecords, motionSampler) {
if (!recipe.cloth) {
return null;
}
const involved = new Set([...recipe.cloth.sheets, ...(recipe.cloth.colliders ?? [])].map(entry => entry.node));
const involvedNodes = recipe.nodes.filter(node => involved.has(node.id));
const followsMotion = recipe.cloth.sheets.some(sheet => sheet.pinTo) || (recipe.cloth.colliders ?? []).some(collider => collider.node === undefined);
const key = JSON.stringify([recipe.cloth, involvedNodes, involvedNodes.map(node => geometryRecords.get(node.geometry)?.signature), followsMotion ? [recipe.motion, recipe.nodes, recipe.armatures] : null]);
if (clothBake?.key !== key) {
const geometries = new Map([...geometryRecords].map(([id, record]) => [id, record.geometry]));
clothBake = { key, sampler: agentSceneModule('cloth').bakeAgentCloth(recipe.cloth, recipe, geometries, motionSampler) };
}
return clothBake.sampler;
}
// Particle launches are cheap to recompute, but an unchanged section on unchanged nodes still reuses them.
function stageParticles(recipe, geometryRecords, stagedState) {
if (!recipe.particles) {
return null;
}
const emitterMeshes = new Set(recipe.particles.systems.map(system => system.emitter?.mesh));
const involvedNodes = recipe.nodes.filter(node => emitterMeshes.has(node.id) || recipe.particles.systems.some(system => system.node === node.id));
const oceanTracks = (recipe.motion?.tracks ?? []).filter(track => track.kind === 'geometry' && track.property === 'oceanTime');
const key = JSON.stringify([recipe.particles, involvedNodes, involvedNodes.map(node => geometryRecords.get(node.geometry).signature), oceanTracks]);
if (particleBake?.key !== key) {
const geometries = new Map([...geometryRecords].map(([id, record]) => [id, record.geometry]));
// An emitter on a sea with an oceanTime track samples the sea at the ocean time of each particle's birth (#2152).
const sea = {
oceanTimeAt: (geometryId, time) => stagedState.motionSampler?.sample(time)?.geometries?.get(geometryId)?.oceanTime ?? null,
geometryAt: (geometryId, oceanTime) => oceanTimeGeometry(recipe, stagedState.maxGeometryVertices, geometryId, oceanTime),
};
particleBake = { key, sampler: agentSceneModule('particles').bakeAgentParticles(recipe.particles, recipe, geometries, sea) };
}
return particleBake.sampler;
}
function commit(stagedState, incrementRevision) {
// A pose that swaps in new parts (particles, cloth) is a topology change too: a renderer holding the old parts would
// otherwise try to update parts it never saw, which failed with "Unknown part identity" (#2204).
const posedPartsChanged = publishPose(stagedState, stagedState.initialPose);
if (stagedState.topologyChanged || posedPartsChanged) {
topologyRevision++;
}
if (incrementRevision && state) {
revisionHistory.push({ revision, snapshot: snapshotState() });
while (revisionHistory.length > REVISION_HISTORY_LIMIT) {
revisionHistory.shift();
}
}
state = stagedState;
if (incrementRevision) {
revision++;
}
return revision;
}
function expected(options) {
knownKeys(options, ['expectedRevision'], 'transaction options');
if (!Number.isSafeInteger(options.expectedRevision) || options.expectedRevision !== revision) {
throw invalidField('expectedRevision', options.expectedRevision, `the current revision, ${revision}; scene_inspect returns it`);
}
}
commit(stage(input), false);
return Object.freeze({
capabilities: AGENT_SCENE_CAPABILITIES,
limits,
get parts() {
return state.parts;
},
/** How many oldest undo revisions the latest edit released to fit maxVertices; 0 when none. */
get releasedRevisions() {
return releasedRevisionCount;
},
get revision() {
return revision;
},
get topologyRevision() {
return topologyRevision;
},
get camera() {
return structuredClone(state.renderCamera);
},
get motionTime() {
return state.motionTime;
},
/** Seconds each placed asset clip needs to play once, in placement order: the clips a render job can play on scene time. */
placedClipEnds() {
return state.assetRuntime.animators.length ? agentSceneModule('assets').placedClipEnds(state.assetRuntime) : [];
},
sequenceTextures() {
return state.sequences;
},
sampleMotion(time) {
if (time !== null && (!Number.isFinite(time) || time < 0 || time > 3600)) {
throw invalidField('time', time, 'null or a number of seconds from 0 to 3600, such as 0.5');
}
if (time !== null && !state.motionSampler && !state.physicsSampler && !state.clothSampler && !state.particleSampler && !state.assetRuntime.animators.length && !state.sequences.length && !state.recipe.environment.localVolumes?.some(volume => volume.frames)) {
throw invalidField('time', time, 'null, because this recipe has no motion, physics, cloth, particles, placed asset clip or grid volume frames to sample; add motion first');
}
const pose = stagePose(state, time);
rebakeAtPose(pose);
if (publishPose(state, pose)) {
topologyRevision++;
}
return state.motionTime;
},
/**
* Set the pose a game's animation graph computed for a placed asset: `nodeOverrides` (and optional `morphWeights`) as
* `asset.stagePose` takes them. The next `sampleMotion` draws it. Only the player and NPC nodes of the game section are posable.
*/
setAssetPose(nodeId, { nodeOverrides = [], morphWeights } = {}) {
const record = state.assetRuntime.animators.find(candidate => candidate.node === nodeId && candidate.pose);
if (!record) {
throw invalidField('nodeId', nodeId, 'a placed asset node that game.player.animation or game.npcs[].animation animates; other placed assets play their asset.clip or asset.drive');
}
record.pose = { nodeOverrides, morphWeights };
},
// After sampleMotion, the lights, sun and sky the motion tracks set at that time; the recipe keeps its authored values.
get environment() {
const environment = structuredClone(state.recipe.environment);
// The time a grid sequence plays at (#1045): the rasterizer and the path tracer both pick the frame from it.
if (environment.localVolumes?.some(volume => volume.frames)) environment.volumeTime = state.motionTime;
return state.movedLook ?agentSceneModule('motion').motionEnvironment(environment, state.movedLook) : environment;
},
/** World bounds ({ name, min, max }) of the visible mesh parts in the current pose; parts with no known bounds are left out. */
worldBounds() {
const bounds = [];
// A bake or a skin replaces a drawn part's geometry, so the bounds come from the part as built, in the drawn pose.
const drawnParts = new Map(state.restParts.map(part => [part.name, part]));
for (const sourcePart of state.sourceRestParts) {
const part = drawnParts.get(sourcePart.name);
if (!part || part.visibility?.visible === false) continue;
// Measured from the geometry itself: a water part with foam or a wear mask draws a copy the cached local bounds do not list.
bounds.push({ name: part.name, ...boundsFor(sourcePart.geometry, part.matrix) });
}
return bounds;
},
/** The bake-stale warning, or none: see `staleBakeProblems` in `agent-bake.js`. */
bakeStaleness: staleBakeProblems,
/** The z-fighting the draw-time ranking could not settle, as coplanar-overlap findings; none when the scene opted out (the renderer reports its pairs) or has none. */
flushLeftovers() {
return state.recipe.environment.resolveCoplanar === false ? [] : coplanarProblems();
},
get postPasses() {
return structuredClone(state.recipe.postPasses ?? []);
},
get effects() {
const effects = structuredClone(state.recipe.effects);
const moved = state.movedLook?.effects ? agentSceneModule('motion').motionEffects(effects, state.movedLook) : effects;
return moved.distortion || moved.flash ? agentSceneModule('postSteps').placeAirSteps(moved, state.motionTime, state.parts) : moved;
},
get shadow() {
return structuredClone(state.recipe.shadow);
},
exportRecipe() {
return authoredRecipe(state.recipe);
},
/** Bone nodes at rest and a clip baked from motion, as `exportGlb` options. Leaves the pose where it was. */
rigExport(options = {}) {
if (!state.recipe.armatures) {
return { nodes: [], clips: [] };
}
const exported = bakeRigExport(state.recipe, state.graph, state.motionSampler, options);
publishPose(state, stagePose(state, state.motionTime));
return exported;
},
/** Gives a scene created without placed assets the pool of decoded catalog assets, so a later edit can place the first one. */
provideAssets(pool) {
options = { ...options, assets: pool };
},
apply(inputOperations, options = {}) {
expected(options);
if (!Array.isArray(inputOperations) || inputOperations.length === 0 || inputOperations.length > limits.maxOperations) {
throw invalidField('operations', Array.isArray(inputOperations) ? `${inputOperations.length} operations` : inputOperations, `a list of 1 to ${limits.maxOperations} operations, such as [{ "type": "set-camera", "fov": 50 }]`);
}
const operations = copiedJson(inputOperations, limits.maxRecipeBytes);
for (const name of defaultStageModulesNamed(operations)) requestedModules.add(name);
const onlyFieldEdits = operations.every(operation => FIELD_EDIT_OPERATIONS.has(operation.type));
const candidate = (onlyFieldEdits && fieldEditCandidate(state.recipe, operations)) || authoredRecipe(state.recipe);
const removedNodes = new Set();
const removedMaterials = new Set();
const removals = [];
for (const operation of operations) {
const section = Object.hasOwn(NULLABLE_SECTION_OPERATIONS, operation.type) ? NULLABLE_SECTION_OPERATIONS[operation.type] : null;
if (operation.type === 'set-motion' && Object.hasOwn(operation, 'removeTracks')) {
candidate.motion = agentSceneModule('motionTrackRemoval').removeMotionTracks(operation, candidate.motion);
continue;
}
if (section) {
knownKeys(operation, ['type', section], 'operation');
if (!Object.hasOwn(operation, section)) {
throw invalidField(section, undefined, `a ${section} value, or null to clear it, in a ${operation.type} operation`, TypeError);
}
candidate[section] = operation[section];
if (candidate.armatures === null) delete candidate.armatures;
continue;
}
const lookField = Object.hasOwn(LOOK_OPERATION_FIELDS, operation.type) ? LOOK_OPERATION_FIELDS[operation.type] : null;
if (lookField) {
knownKeys(operation, ['type', lookField], 'operation');
const patch = operation[lookField];
// Spot and area lights, cascades and sun links are absent from a recipe until it sets them.
const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'localVolumes', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'specularAntiAliasing', 'sunAngularRadius', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'hdri', 'sky'] : lookField === 'effects' ? postStepSupport.fields : [];
knownKeys(patch, [...Object.keys(candidate[lookField]), ...optionalFields], lookField);
const nestedField = lookField === 'environment' ? 'volumeFog' : 'bloom';
const merged = { ...candidate[lookField], ...(lookField === 'environment' ? environmentPatchWithSetup(patch) : patch) };
if (nestedField && Object.hasOwn(patch, nestedField)) {
const nestedKeys = nestedField === 'volumeFog' ? [...Object.keys(candidate[lookField][nestedField]), ...VOLUME_FOG_FIELDS] : Object.keys(candidate[lookField][nestedField]);
knownKeys(patch[nestedField], nestedKeys, nestedField);
merged[nestedField] = { ...candidate[lookField][nestedField], ...patch[nestedField] };
}
// A preset starts the sky again from its own sun, so fields kept from the earlier sky never hide it.
if (patch.sky) {
const kept = candidate[lookField].sky;
const type = patch.sky.type ?? kept?.type ?? 'physical';
merged.sky = { ...!patch.sky.preset && kept?.type === type && kept, type, ...patch.sky };
}
// The sky's derived colours kept from an earlier sky or setup are not choices: only the patch's own values beat the sky.
if (lookField === 'environment' && merged.sky?.type === 'physical') {
for (const field of SKY_OVERRIDABLE_FIELDS) if (!Object.hasOwn(patch, field)) delete merged[field];
}
candidate[lookField] = merged;
continue;
}
const addition = Object.hasOwn(ADDITION_FIELDS, operation.type) ? ADDITION_FIELDS[operation.type] : null;
if (addition) {
const [collection, field] = addition;
knownKeys(operation, ['type', field], 'operation');
const record = operation[field];
identifier(record?.id);
if (operation.type === 'add-geometry') {
geometryEstimate(record);
} else if (operation.type === 'add-material') {
materialFrom(record);
} else {
nodeFrom(record);
}
if (candidate[collection].some(existing => existing.id === record.id)) {
throw invalidField(`${field}.id`, record.id, `an ID no ${collection} entry uses yet; pick a new ID, or remove the existing one first`);
}
candidate[collection].push(record);
continue;
}
if (operation.type === 'bake-motion') {
agentSceneModule('motionBake').bakeMotion(candidate, operation, motionBakeSource(state));
continue;
}
if (operation.type === 'fracture-node') {
const { id: fracturedId } = candidate.nodes.find(node => node.id === operation.node) ?? {};
agentSceneModule('fracture').fractureNode(candidate, operation, geometryId => generateOperationGeometry(candidate, geometryId, limits));
if (fracturedId !== undefined) removedNodes.add(fracturedId);
continue;
}
if (operation.type === 'add-explosion') {
const sourceGeometry = geometryId => generateOperationGeometry(candidate, geometryId, limits);
agentSceneModule('explosion').addExplosion(candidate, operation, { sourceGeometry, fractureNode: fracture => agentSceneModule('fracture').fractureNode(candidate, fracture, sourceGeometry) });
if (typeof operation.debris?.node === 'string') removedNodes.add(operation.debris.node);
continue;
}
if (operation.type === 'settle') {
agentSceneModule('settle').applySettle(candidate, operation);
continue;
}
if (operation.type === 'edit-mesh') {
knownKeys(operation, ['type', 'geometry', 'edits', 'replace'], 'operation');
const target = meshGeometryTarget(candidate, operation, type => `Add a mesh geometry with base: { type: '${type}', ... } to edit it.`);
if (operation.replace !== undefined && typeof operation.replace !== 'boolean') {
throw invalidField('replace', operation.replace, 'true or false', TypeError);
}
if (!Array.isArray(operation.edits)) {
throw invalidField('edits', operation.edits, 'an array of mesh edits, such as [{ "op": "extrude" }]', TypeError);
}
target.edits = operation.replace ? operation.edits : [...(target.edits ?? []), ...operation.edits];
agentSceneModule('mesh').normalizeMeshEdits(target.edits);
continue;
}
if (operation.type === 'set-mesh-stack') {
knownKeys(operation, ['type', 'geometry', 'stack', 'apply'], 'operation');
const target = meshGeometryTarget(candidate, operation, () => 'Only mesh geometries have a modifier stack.');
const stack = operation.stack ?? target.stack ?? [];
agentSceneModule('mesh').normalizeMeshStack(stack);
const applied = operation.apply ?? 0;
if (!Number.isInteger(applied) || applied < 0 || applied > stack.length) {
throw invalidField('apply', applied, `a whole number from 0 to the stack length ${stack.length}, such as 0`);
}
// Applying moves the first nodes into the edit log, as Blender's Apply modifier does.
target.edits = [...(target.edits ?? []), ...stack.slice(0, applied)];
target.stack = stack.slice(applied);
agentSceneModule('mesh').normalizeMeshEdits(target.edits);
continue;
}
if (operation.type === 'remove-node') {
for (const id of removeNode(candidate, operation)) {
removedNodes.add(id);
}
continue;
}
const removal = Object.hasOwn(REMOVAL_FIELDS, operation.type) ? REMOVAL_FIELDS[operation.type] : null;
if (removal) {
knownKeys(operation, ['type', 'id'], 'operation');
identifier(operation.id);
const index = candidate[removal].findIndex(record => record.id === operation.id);
if (index < 0) {
throw invalidField('id', operation.id, `the ID of an existing ${removal} entry; scene_inspect lists them`);
}
removals.push(operation);
candidate[removal].splice(index, 1);
if (operation.type === 'remove-material') {
removedMaterials.add(operation.id);
}
continue;
}
let target;
let fields;
if (operation.type === 'set-node') {
fields = NODE_FIELDS;
target = candidate.nodes.find(node => node.id === operation.id);
} else if (operation.type === 'set-material') {
fields = [...MATERIAL_FIELDS, 'map'];
target = candidate.materials.find(material => material.id === operation.id);
} else if (operation.type === 'set-camera') {
fields = CAMERA_FIELDS;
target = candidate.camera;
} else {
throw invalidField('type', operation.type, `one of ${AGENT_SCENE_CAPABILITIES.operations.join(', ')}`, TypeError);
}
knownKeys(operation, ['type', ...(operation.type === 'set-camera' ? [] : ['id']), ...fields], 'operation');
if (!target) {
throw invalidField('id', operation.id, `the ID of an existing ${operation.type === 'set-node' ? 'node' : 'material'}; scene_inspect lists them, or add it first with an add operation`);
}
if (operation.type === 'set-camera') {
applyCameraFields(target, operation);
} else {
for (const field of fields) {
if (Object.hasOwn(operation, field)) {
target[field] = operation[field];
}
}
}
}
assertRemovedResourcesUnused(candidate, removals);
// Plain field edits put only values the operation copy already checked into the candidate, so the recipe is not copied and checked a second time.
try {
return commit(stage(candidate, null, removedNodes, removedMaterials, onlyFieldEdits, onlyFieldEdits ? poseEditNodeIds(operations) : null), true);
} catch (error) {
pendingGraphRestore?.();
throw error;
} finally {
pendingGraphRestore = null;
}
},
inspect(options = {}) {
knownKeys(options, ['ids', 'limit', 'includeBounds', 'path'], 'inspection');
const maximum = integer(options.limit ?? Math.min(64, limits.maxNodes), 1, limits.maxNodes, 'inspection limit');
if (options.includeBounds !== undefined && typeof options.includeBounds !== 'boolean') {
throw invalidField('includeBounds', options.includeBounds, 'true or false', TypeError);
}
if (options.ids !== undefined && (!Array.isArray(options.ids) || options.ids.length > limits.maxNodes)) {
throw invalidField('ids', Array.isArray(options.ids) ? `${options.ids.length} IDs` : options.ids, `a list of at most ${limits.maxNodes} node IDs, such as ["body"]`);
}
const selected = options.ids === undefined ? state.recipe.nodes.filter(node => !node.assetPart) : options.ids.map(id => {
identifier(id);
const node = state.recipe.nodes.find(value => value.id === id);
if (!node) {
throw invalidField('ids', id, 'IDs of existing nodes; call scene_inspect without ids to list them');
}
return node;
});
const nodes = selected.slice(0, maximum).map(node => {
const geometry = state.geometries.get(node.geometry);
const result = {
id: node.id, label: node.label ?? node.id, parent: node.parent,
geometry: node.geometry ?? null, material: node.material ?? null,
vertices: geometry ? geometry.positions.length / 3 : 0,
triangles: geometry ? geometry.indices.length / 3 : 0,
};
if (options.includeBounds) {
result.bounds = geometry ? boundsFor(geometry, state.graph.getNode(node.id).worldMatrix) : null;
}
return result;
});
const resident = geometryStats(ownedGeometryRecords());
const diagnostics = [...recipeDiagnostics(state.recipe), ...closedRoomProblems(), ...staleBakeProblems(), ...(state.bakeSkipped ? [agentSceneModule('bake').bakeSkippedDiagnostic(state.bakeSkipped)] : []),...(state.reflectionSkipped ? [agentSceneModule('reflections').reflectionSkippedDiagnostic(state.reflectionSkipped)] : []), ...coplanarProblems(), ...(agentSceneModuleLoaded('unsupportedPart') ? agentSceneModule('unsupportedPart').unsupportedPartProblems(state.parts, state.recipe, revision) : []), ...(state.particleSampler?.diagnostics() ?? []), ...(state.assetRuntime.animators.length ? agentSceneModule('assets').placedClipDiagnostics(state.assetRuntime) : [])];
return {
revision, topologyRevision,
...(state.recipe.motion?.ik?.length ? { motionIk: agentSceneModule('motion').compileAgentMotion(state.recipe.motion, state.recipe).sweepIk() } : {}),
motion: state.recipe.motion ? { duration: state.recipe.motion.duration, loop: state.recipe.motion.loop, tracks: state.recipe.motion.tracks.length, time: state.motionTime } : null,
physics: state.physicsSampler ? state.physicsSampler.report() : null,
...(state.clothSampler ? { cloth: state.clothSampler.report() } : {}),
...(state.particleSampler ? { particles: state.particleSampler.report() } : {}),
...(state.assetRuntime.vegetation ? { vegetation: state.assetRuntime.vegetation } : {}),
...(state.assetRuntime.placements.length ? { assets: agentSceneModule('assets').describeAssetPlacements(state.assetRuntime, state.graph, geometry => state.localBounds.get(geometry)) } : {}),
...(state.sequences.length ? { textureSequences: state.sequences.map(sequence => sequence.describe()) } : {}),
...(state.bakeReport ? { bake: state.bakeReport } : {}),
...(state.recipe.postPasses?.length ? { postPasses: agentSceneModule('userPass').describeUserPasses(state.recipe.postPasses) } : {}),
...(state.reflectionReport ? { reflections: state.reflectionReport } : {}),
...(state.recipe.armatures ? { rig: rigReport(state.recipe, state.skinBindings) } : {}),
boundsSpace: 'authored-base-world',
...(diagnostics.length ? { diagnostics } : {}),
...(flushCache?.ranked ? { flush: { ranked: flushCache.ranked } } : {}),
counts: {
nodes: state.recipe.nodes.length, parts: state.parts.length,
geometries: state.geometries.size, materials: state.recipe.materials.length,
vertices: state.stats.vertices,
},
geometryBytes: state.stats.geometryBytes,
estimatedGeometryBytes: state.stats.estimatedGeometryBytes,
residentGeometryBytes: resident.geometryBytes,
residentGeometryVertices: resident.vertices,
look: {
world: state.recipe.environment.world,
pointLights: state.recipe.environment.pointLights.length,
spotLights: state.recipe.environment.spotLights?.length ?? 0,
areaLights: state.recipe.environment.areaLights?.length ?? 0,
volumeFogDensity: state.recipe.environment.volumeFog.density,
exposure: state.recipe.effects.exposure,
},
nodes, truncated: selected.length > nodes.length,
...(options.path === undefined ? {} : { path: pathQuery(options.path) }),
};
},
/** Polygon counts, parts, face tags and lint problems for recipe geometries (all, or the given IDs). */
inspectMeshes(options = {}) {
knownKeys(options, ['geometries'], 'mesh inspection');
const requested = options.geometries ?? [...state.geometries.keys()];
if (!Array.isArray(requested) || (options.geometries !== undefined && requested.length > MAX_MESH_REPORTS)) {
throw invalidField('geometries', Array.isArray(requested) ? `${requested.length} IDs` : requested, `a list of at most ${MAX_MESH_REPORTS} geometry IDs, such as ["block"]`);
}
const selected = requested.slice(0, MAX_MESH_REPORTS);
const meshes = selected.map(id => {
identifier(id);
const geometry = state.geometries.get(id);
if (!geometry) {
throw invalidField('geometries', id, `one of ${[...state.geometries.keys()].join(', ')}`);
}
return { geometry: id, ...agentSceneModule('mesh').meshReport(geometry) };
});
return { revision, meshes, truncated: requested.length > selected.length };
},
checkpoint() {
if (checkpoints.size >= limits.maxCheckpoints) {
throw invalidField('checkpoints', `${checkpoints.size} saved`, `at most ${limits.maxCheckpoints} saved checkpoints; release one with scene_release_checkpoint first`);
}
const handle = Object.freeze({});
checkpoints.set(handle, snapshotState());
return handle;
},
restore(handle, options = {}) {
expected(options);
const checkpoint = checkpoints.get(handle);
if (!checkpoint) {
throw invalidField('checkpointId', handle, 'a checkpointId that scene_checkpoint returned and you have not released');
}
return commit(stage(checkpoint.recipe, checkpoint), true);
},
/** Go back to an earlier revision that scene_apply or scene_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 commit(stage(entry.snapshot.recipe, entry.snapshot), true);
},
releaseCheckpoint(handle) {
if (!checkpoints.delete(handle)) {
throw invalidField('checkpointId', handle, 'a checkpointId that scene_checkpoint returned and you have not released');
}
},
});
}