3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { exportNativeSceneTables, nativeTexelTracerIfAvailable, splitExportForChunks } from './native-bake-page.js';
import { DELTA_MAXIMUM_BASELINE_BYTES, deltaPieces, planExportDelta } from './native-export-delta.js';
// The byte tables of the last chunked native export, held until the job runner has read them (releaseNativeExport).
let heldNativeExportTables = null;
// The ranges of those tables the job runner still lacks (a delta against its baseline), or null when it reads them whole.
let heldNativeExportRanges = null;
// The tables of the last export a job asked to keep, so the next frame can send only what changed since (#1861).
let nativeExportBaseline = null;
let nativeExportCount = 0;
import { buildWithKernels, kernelWorkersAvailable, kernelStats, resetKernelStats } from '../src/kernel-offload.js';
import { createAgentScene, applyCameraFields, loadAllAgentSceneModules, allAgentSceneModulesLoaded, needsMeshBooleans, loadMeshBooleans, meshBooleansLoaded, setManifoldModuleLoader, needsPhysics, needsBuoyancy, loadPhysicsEngine, physicsEngineLoaded, setPhysicsModuleLoader } from '../src/agent-scene.js';
import { CrucibleRenderer } from '../src/renderer.js';
import { skyOpenness } from '../src/closed-room.js';
import { fogSkyVisibility } from '../src/fog-sky-visibility.js';
import { installCameraEffects, effectsWithFStop } from '../src/camera-effects.js';
import { installRenderPasses } from '../src/render-passes.js';
import { installMeshBlend, normalizeBlend } from '../src/mesh-blend.js';
import { installCoplanarDiagnostics } from '../src/coplanar-overlap.js';
import { applyProjection } from '../src/camera.js';
import { mat4 } from 'gl-matrix';
import { listAddedControllerKinds, listAddedCameraRigKinds, listControllerKinds, listCameraRigKinds, unregisterControllerKind, unregisterCameraRigKind } from '../src/player.js';
import { fitAgentShadow, resolveAgentShadow, agentEnvironmentMap } from '../src/agent-look.js';
import { pathTraceEnvironment } from '../src/path-trace-terms.js';
import { agentSceneModule, agentSceneModuleLoaded } from '../src/agent-scene-modules.js';
import { agentGroundPlacement, createAgentGround, placeAgentGround, FLOOR_COLOR } from '../src/agent-ground.js';
import { groundBounceEnvironment } from '../src/ground-bounce.js';
import { createAgentAssetScene } from '../src/agent-asset.js';
import { parseGltf } from '../src/gltf.js';
import { assetCopyKey, recipeAssetNeeds } from '../src/agent-scene-assets.js';
import { clipDisplayName, resolveClipIndex } from '../src/clip-name.js';
import { exportGlb } from '../src/export.js';
import { matrixFrame } from '../src/export-skeleton.js';
import '../src/texture-update.js';
import { staleRevisionMessage } from '../src/agent-errors.js';
import { sampleMotionAtZeroForGround } from './motion-ground-sample.js';
import { updatePartVertices } from '../src/update-part-vertices.js';
import { rasterOptionsFor } from './agent-render-quality.mjs';
import { hasPatternTextures } from './agent-preview-textures.js';
import { TEXTURE_SEQUENCE_LIMITS } from '../src/texture-sequence-limits.js';
import { missingStreamedFrames, supplyStreamedFrame, retainStreamedWindow } from '../src/agent-texture-sequence.js';
import { imageLimitProblem } from '../src/image-header.js';
import { registerCatalogEnvironment, registerCatalogLook } from '../src/look-catalog.js';
import { registerVolumeGrid } from '../src/volume-grid.js';
import { parseRadianceHdr } from '../src/hdri.js';
import { parseCube } from '../src/view-transform.js';
import { weightTracksFromGltfAnimation } from '../src/export-skeleton.js';
import { clipFromGltfAnimation } from '../src/skeleton-pose.js';
import { sessionProblem, planSceneEviction } from '../src/agent-errors.js';
import { AGENT_SCENE_DEFAULT_LIMITS, MEMORY_CEILING_MIB } from '../src/agent-scene-capabilities.js';
import { describeApplication } from '../src/agent-apply-report.js';
import { framingProblems, placementProblems, textureProblems, exposureProblems, lumaShares } from '../src/frame-checks.js';
import { BRANCH_LIMITS, createBranchStore, printableLabel } from '../src/agent-branches.js';
import { agentAssetDecodeOptions, withCatalogLimitAdvice } from '../src/agent-asset-limits.js';
import { describeMarks, validateMarks } from '../src/agent-annotate.js';
import { sceneQueryFor, partMaterialsFor, summarizeWalkMap, walkOptionsFor, createQueryOnlyCache } from './agent-walkmap.js';
import { MOTION_NOT_SET_HINT, recipeMoves } from '../src/motion-hint.js';
// Open scenes by sessionId, least recently used first. One canvas serves them all, so at most one record owns a renderer;
// a call on another scene hands the canvas over (the scene data stays, the renderer is rebuilt).
const records = new Map();
// The scene whose renderer a render job holds; no scene gets a renderer until the job gives it back.
let leasedRecord = null;
const EVICTED_SESSIONS_KEPT = 32;
const evictedSessions = [];
// Why each remembered evicted scene was closed, so a later call with its ID can say it.
const evictionReasons = {};
let canvas = document.querySelector('canvas');
function sessionError(sessionId) {
const openSessionIds = [...records.keys()];
return new Error(sessionProblem(sessionId, openSessionIds.at(-1), { openSessionIds, evictedSessionIds: evictedSessions, evictionReasons }));
}
function lookupSession(sessionId) {
const record = records.get(sessionId);
if (!record) throw sessionError(sessionId);
// Re-insert so the Map order stays least to most recently used.
records.delete(sessionId);
records.set(sessionId, record);
return record;
}
function releaseOtherRenderers(keep) {
let released = false;
for (const other of records.values()) {
if (other === keep || !other.renderer) continue;
other.renderer.dispose();
other.renderer = null;
released = true;
}
if (released) resetCanvas();
}
function requireSession(sessionId) {
const record = lookupSession(sessionId);
if (record.renderer || leasedRecord) return record;
releaseOtherRenderers(record);
record.renderer = initializeRenderer(record.scene, record.options);
record.rendererTopology = record.scene.topologyRevision;
record.rendererTextured = sceneIsTextured(record.scene);
record.shadowKey = null;
return record;
}
function requireCheckpoint(record, checkpointId) {
if (record.checkpoints.has(checkpointId)) return;
const kept = [...record.checkpoints.keys()];
const reason = record.evictedCheckpointIds.includes(checkpointId)
? `was evicted as the oldest when more than ${AGENT_SCENE_DEFAULT_LIMITS.maxCheckpoints} were saved`
: 'is unknown or was released';
throw new Error(`checkpointId ${checkpointId} ${reason}. Pass a checkpointId that scene_checkpoint returned for sessionId ${record.sessionId}${kept.length ? `: ${kept.join(', ')}` : '; this scene has none, so call scene_checkpoint first'}.`);
}
function releaseRecord(record) {
try {
record.renderer?.dispose();
} finally {
record.asset?.dispose();
disposePlacedAssets(record.placedAssets);
}
record.checkpoints.clear();
record.branches.clear();
records.delete(record.sessionId);
}
function residentBytesOf(record) {
return record.scene.inspect().residentGeometryBytes ?? 0;
}
// Close the least recently used scenes until the new scene fits both caps, and name them and the cap to the caller.
function evictForNewScene(incomingBytes) {
const openScenes = [...records.values()].map(record => ({ sessionId: record.sessionId, bytes: residentBytesOf(record) }));
const { sessionIds, reason } = planSceneEviction(openScenes, incomingBytes);
for (const sessionId of sessionIds) {
releaseRecord(records.get(sessionId));
evictedSessions.push(sessionId);
evictionReasons[sessionId] = reason;
}
for (const forgottenId of evictedSessions.splice(0, Math.max(0, evictedSessions.length - EVICTED_SESSIONS_KEPT))) {
delete evictionReasons[forgottenId];
}
return { evicted: sessionIds, reason };
}
function bytesFromBase64(data) {
if (typeof Uint8Array.fromBase64 === 'function') return Uint8Array.fromBase64(data);
const binary = atob(data);
const bytes = new Uint8Array(binary.length);
for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
return bytes;
}
// Other catalog assets whose clips a motion layer retargets: only their clips and nodes are kept, so the decoded
// meshes and textures are released at once.
async function decodeMotionSources(encoded = {}) {
const decoded = {};
for (const [assetId, data] of Object.entries(encoded)) {
const source = await parseCatalogAsset(bytesFromBase64(data).buffer);
decoded[assetId] = { animations: source.animations, nodes: source.nodes };
source.dispose();
}
return decoded;
}
function validatePreviewCamera(camera) {
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 viewProjection = mat4.multiply(mat4.create(), projection, view);
if (![projection, viewProjection].every(matrix => matrix.every(Number.isFinite))) {
throw new RangeError('Camera matrices must remain finite for all supported preview aspect ratios.');
}
}
}
function candidateCamera(record, operations) {
const camera = record.scene.exportRecipe().camera;
for (const operation of operations) {
if (operation.type === 'set-camera') {
applyCameraFields(camera, operation);
}
}
return createAgentScene({ format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [], camera }).camera;
}
const EXPOSURE_PROBE_SIZE = 64;
let exposureProbe;
/** Luma shares of a 64 by 64 copy of the frame just drawn; the copy is a read of the drawing buffer, so call it in the draw's task. */
function sampleFrameShares() {
exposureProbe ??= Object.assign(document.createElement('canvas'), { width: EXPOSURE_PROBE_SIZE, height: EXPOSURE_PROBE_SIZE });
const context = exposureProbe.getContext('2d', { willReadFrequently: true });
context.drawImage(canvas, 0, 0, EXPOSURE_PROBE_SIZE, EXPOSURE_PROBE_SIZE);
return lumaShares(context.getImageData(0, 0, EXPOSURE_PROBE_SIZE, EXPOSURE_PROBE_SIZE).data);
}
/**
* Warnings about the frame just drawn from `camera`: framing, a stale bake and exposure (when `exposure` is given, the
* effects.exposure drawn with). Imported assets have no part bounds or bake, so they get the texture and exposure checks only.
* `placement` adds the floating and intersecting parts, which only scene_look reports: a render job would repeat them
* for every frame of a moving scene.
*/
function viewProblems(record, camera, exposure, { placement = false } = {}) {
const problems = [];
const boxes = record.scene.worldBounds?.();
if (boxes) {
problems.push(...framingProblems({ camera, aspect: canvas.width / canvas.height, boxes, reportPartsOutside: placement }));
if (placement) problems.push(...placementProblems({ boxes }));
}
if (record.scene.bakeStaleness) problems.push(...record.scene.bakeStaleness());
problems.push(...textureProblems({ parts: record.scene.parts }));
if (record.scene.flushLeftovers) problems.push(...record.scene.flushLeftovers());
problems.push(...(record.scene.inspect({}).diagnostics ?? []).filter(problem => problem.kind === 'particle-node-transform-ignored'));
if (exposure !== undefined) problems.push(...exposureProblems({ shares: sampleFrameShares(), exposure, environment: record.scene.environment }));
return problems;
}
function renderInfo(renderer, viewWarnings = []) {
const diagnostics = [...(renderer.diagnostics ?? []), ...viewWarnings];
const context = renderer.context;
const debug = context.getExtension('WEBGL_debug_renderer_info');
return {
graphics: context.getParameter(debug ? debug.UNMASKED_RENDERER_WEBGL : context.RENDERER),
estimatedBytes: renderer.memoryPlan.estimatedBytes,
bloom: renderer.memoryPlan.bloom,
requiredMemoryMiB: renderer.memoryPlan.requiredMemoryMiB,
width: canvas.width,
height: canvas.height,
samples: renderer.capabilities.samples,
hdr: renderer.capabilities.hdr,
depth: renderer.depth,
geometryBuffers: renderer.geometryBuffers?.size ?? 0,
materialTextures: renderer.textures ? [...renderer.textures.keys()].filter(Boolean).length : 0,
skinTextures: renderer.skinTextures?.size ?? 0,
morphTextures: renderer.morphTextures?.size ?? 0,
gpuBuffers: renderer.buffers?.length ?? 0,
drawBatches: renderer.batches?.length ?? 0,
...(diagnostics.length ? { diagnostics } : {}),
};
}
// Sequence frames arrive as catalog image bytes keyed by asset id. They are decoded here, without colour conversion or
// premultiplication, so the same file gives the same pixels in a preview and in a render job.
async function decodeSequenceFrame(id, base64) {
const bytes = bytesFromBase64(base64);
// The header size is checked first: createImageBitmap would decode every pixel of an oversized frame before its size is known.
const headerProblem = imageLimitProblem(bytes, `Sequence frame ${id.slice(0, 12)}`, TEXTURE_SEQUENCE_LIMITS);
if (headerProblem) throw new RangeError(headerProblem);
const bitmap = await createImageBitmap(new Blob([bytes]), { premultiplyAlpha: 'none', colorSpaceConversion: 'none' });
try {
if (bitmap.width > TEXTURE_SEQUENCE_LIMITS.maxSide || bitmap.height > TEXTURE_SEQUENCE_LIMITS.maxSide) {
throw new RangeError(`Sequence frame ${id.slice(0, 12)} is ${bitmap.width}x${bitmap.height}; frames are at most ${TEXTURE_SEQUENCE_LIMITS.maxSide} pixels on a side.`);
}
const surface = new OffscreenCanvas(bitmap.width, bitmap.height);
const context = surface.getContext('2d', { willReadFrequently: true });
context.drawImage(bitmap, 0, 0);
const { data } = context.getImageData(0, 0, bitmap.width, bitmap.height);
return { width: bitmap.width, height: bitmap.height, data };
} finally {
bitmap.close();
}
}
// HDRI and .cube files a recipe names, by bundled name or catalog ID: { kind: 'environment', base64 } or { kind: 'look', text }.
function registerLookData(lookData) {
for (const [reference, entry] of Object.entries(lookData ?? {})) {
if (entry.kind === 'environment') registerCatalogEnvironment(reference, parseRadianceHdr(bytesFromBase64(entry.base64)));
else registerCatalogLook(reference, parseCube(entry.text));
}
}
// Grid files (.67vg) a recipe's grid volumes name, base64 by file name. The page has no file access, so the server reads them and names them here;
// registering decodes each one and refuses a file over the grid byte limit.
function registerGridData(gridData) {
for (const [name, base64] of Object.entries(gridData ?? {})) registerVolumeGrid(name, bytesFromBase64(base64));
}
async function loadSequenceFrames(pool, sequenceData) {
for (const [id, base64] of Object.entries(sequenceData ?? {})) {
if (pool.has(id)) continue;
try {
pool.set(id, await decodeSequenceFrame(id, base64));
} catch (error) {
if (error instanceof RangeError) throw error;
throw new Error(`Sequence frame ${id.slice(0, 12)} is not a PNG, JPEG or WebP image the browser can decode.`);
}
const decodedBytes = [...pool.values()].reduce((total, frame) => total + frame.data.length, 0);
if (decodedBytes > TEXTURE_SEQUENCE_LIMITS.maxDecodedBytes) {
pool.delete(id);
throw new RangeError(`Sequence frames decode to more than ${TEXTURE_SEQUENCE_LIMITS.maxDecodedBytes / 1048576} MiB. Use fewer or smaller frames.`);
}
}
return pool;
}
// Each frame change is one updateTexture per renderer. A renderer starts on frame 0, the image its descriptor holds.
const uploadedFrames = new WeakMap();
function syncSequenceTextures(record) {
const uploaded = uploadedFrames.get(record.renderer) ?? new Map();
uploadedFrames.set(record.renderer, uploaded);
for (const { descriptor, index, image } of record.scene.sequenceTextures?.() ?? []) {
if ((uploaded.get(descriptor) ?? 0) === index) continue;
if (!record.renderer.textures.has(descriptor)) continue;
record.renderer.updateTexture(descriptor, { image });
uploaded.set(descriptor, index);
}
}
// Decodes the frames the host supplied for a motion time, hands them to their streamed sequences and drops the frames outside
// the window of that time. Returns the decoded bytes that stay.
async function loadStreamedFrames(scene, motionTime, sequenceData) {
const sequences = scene.sequenceTextures?.() ?? [];
for (const [id, base64] of Object.entries(sequenceData ?? {})) {
try {
supplyStreamedFrame(sequences, id, await decodeSequenceFrame(id, base64));
} catch (error) {
if (error instanceof RangeError) throw error;
throw new Error(`Sequence frame ${id.slice(0, 12)} is not a PNG, JPEG or WebP image the browser can decode.`);
}
}
return retainStreamedWindow(sequences, motionTime, TEXTURE_SEQUENCE_LIMITS.maxDecodedBytes);
}
function sceneIsTextured(scene) {
// A material snippet adds code to the colour and shadow programs, which only a new renderer compiles.
return hasPatternTextures(scene.parts) || (scene.sequenceTextures?.().length ?? 0) > 0 || scene.parts.some(part => part.material.snippet);
}
// replaceParts streams only untextured parts, so a topology change around pattern textures takes a new renderer.
// A material snippet is compiled alone first, so a compile error names the snippet's own lines and the running renderer stays.
function probeSnippets(scene) {
if (agentSceneModuleLoaded('materialSnippet')) agentSceneModule('materialSnippet').probeMaterialSnippets(scene.parts);
}
function rebuildRenderer(record) {
probeSnippets(record.scene);
record.renderer.dispose();
record.renderer = null;
resetCanvas();
record.renderer = initializeRenderer(record.scene, record.options);
record.shadowKey = null;
}
// While a motion time is sampled (a render job, a look at a time), the automatic floor is fixed by the pose at time 0, so
// shards flying out of a physics bake or a part driving away never resize it, flip it on or off, or move the horizon.
// A scene with no motion time reads its own pose each draw, as before.
const motionGrounds = new WeakMap();
function automaticGroundPlacement(scene) {
const frozen = motionGrounds.get(scene);
if (scene.motionTime != null && frozen?.revision === scene.revision) {
return frozen.placement;
}
return agentGroundPlacement(scene.parts, scene.environment);
}
function sampleMotionTime(scene, time) {
if (motionGrounds.get(scene)?.revision !== scene.revision) {
sampleMotionAtZeroForGround(scene, time);
motionGrounds.set(scene, { revision: scene.revision, placement: agentGroundPlacement(scene.parts, scene.environment) });
}
scene.sampleMotion(time);
}
// The automatic floor (src/agent-ground.js) follows the scene's lowest geometry. A renderer gains or loses it only
// through a new renderer, so a floor that appears or disappears (a part now forms one, or environment.ground changed) rebuilds.
function syncAutomaticGround(record) {
const placement = automaticGroundPlacement(record.scene);
if (Boolean(placement) !== Boolean(record.renderer.groundPart)) {
rebuildRenderer(record);
record.renderer.resize();
return;
}
if (placement) {
placeAgentGround(record.renderer.groundPart, placement);
record.renderer.updateParts([...record.scene.parts, record.renderer.groundPart]);
}
}
// The scene's environment lit by the sky map, with the light its floor bounces (src/ground-bounce.js): a floor part of the
// recipe gives its own colour, and the automatic floor gives its own.
function litEnvironment(parts, environment, hasAutomaticGround) {
const lit = groundBounceEnvironment(parts, { ...environment, map: agentEnvironmentMap(environment) }, { automaticAlbedo: hasAutomaticGround ? FLOOR_COLOR : null });
// A closed room a sun lights gets the lights of its sunlit patches (src/sun-bounce.js), once a recipe that names a sun has loaded the module.
return agentSceneModuleLoaded('floorSky') ? agentSceneModule('floorSky').withSunBounce(parts, lit) : lit;
}
// A renderer takes its cascades at construction, so a change of the count (or of the extent that picks it) rebuilds.
function syncShadowCascades(record) {
const count = cascadeCountFor(record.scene);
if (count !== (record.renderer.shadowCascades?.count ?? 0)) {
rebuildRenderer(record);
record.renderer.resize();
}
}
function draw(record, time = 0, camera = record.scene.camera, frameOptions = {}) {
if (!record.renderer) throw new Error('The scene renderer is leased to a render job.');
if (record.renderer.context.isContextLost()) {
throw new Error('The render context was lost. Export the recipe and dispose this session.');
}
// Shrink the existing target first so a smaller look can recover a staging-budget failure.
record.renderer.resize();
if (record.rendererTopology !== record.scene.topologyRevision) {
const textured = sceneIsTextured(record.scene);
// replaceParts refuses skinned and morphed parts, so an edited imported part takes a new renderer as well.
if (textured || record.rendererTextured || record.asset) {
rebuildRenderer(record);
} else {
record.renderer.replaceParts(record.scene.parts);
}
record.rendererTextured = textured;
record.rendererTopology = record.scene.topologyRevision;
record.renderer.resize();
} else {
record.renderer.updateParts(record.scene.parts);
}
// Cloth rewrites its geometry in place, so a seek only uploads the new positions and normals.
if (agentSceneModuleLoaded('cloth')) {
const { isLiveClothGeometry } = agentSceneModule('cloth');
for (const part of record.scene.parts) {
if (isLiveClothGeometry(part.geometry)) updatePartVertices(record.renderer, part, part.geometry.positions, part.geometry.normals);
}
}
syncAutomaticGround(record);
syncShadowCascades(record);
syncSequenceTextures(record);
const environment = record.scene.environment;
const effects = record.scene.effects;
const shadow = fitAgentShadow(record.scene.shadow, record.scene.parts);
const shadowKey = JSON.stringify([environment.lightDirection, shadow]);
if (record.shadowKey !== shadowKey) {
record.renderer.shadowBounds = resolveAgentShadow(shadow, environment.lightDirection);
record.renderer.shadowsDirty = true;
record.shadowKey = shadowKey;
}
record.renderer.world = environment.world;
syncMeshBlend(record);
const postPasses = record.scene.postPasses ?? [];
record.renderer.userPasses?.set(postPasses);
applyRecipeWindHeading(record.renderer, environment);
const { objectMotion, ...renderOptions } = frameOptions;
const frame = { ...camera, environment: litEnvironment(record.scene.parts, environment, Boolean(record.renderer.groundPart)), effects, exposure: effects.exposure, time, lines: environment.lines, ...windFrame(environment), ...renderOptions, effects: effectsWithFStop(renderOptions.effects ?? effects, camera) };
// Object motion blur, a mask by parts and a user pass with `objects` all read the object ID pass.
let needsObjectIds = Boolean(objectMotion) || postPasses.some(pass => pass.objects);
if (effects.colorBalance || effects.glare || effects.lensDistortion || effects.stylize || effects.composite) {
const postSteps = agentSceneModule('postSteps');
postSteps.installPostSteps(record.renderer);
needsObjectIds ||= postSteps.usesObjectMask(postSteps.resolvePostSteps(frame.effects));
}
if (objectMotion) {
// Object motion blur reads each pixel's part from the object ID pass, drawn first; the lit frame then smears along each part's motion.
const { installObjectMotionBlur, packObjectMotion } = agentSceneModule('objectMotionBlur');
if (!frame.pass) installObjectMotionBlur(record.renderer);
if (!frame.pass) record.renderer.render({ ...frame, pass: 'objectId', previousCamera: undefined });
frame.objectMotion = packObjectMotion(record.renderer, objectMotion.current, objectMotion.previous);
} else if (needsObjectIds && !frame.pass) {
// A mask by parts reads the same pass.
record.renderer.render({ ...frame, pass: 'objectId', previousCamera: undefined });
}
record.renderer.render(frame);
const error = record.renderer.context.getError();
if (error !== 0) {
throw new Error(`WebGL render failed with error ${error}.`);
}
}
// The radius of each node's `blend`, by part name. Checked again only when the scene revision changes; a bad value throws here
// with the field's message, which the render reports.
function syncMeshBlend(record) {
if (record.blendRevision === record.scene.revision && record.blendRenderer === record.renderer) return;
record.blendRevision = record.scene.revision;
record.blendRenderer = record.renderer;
const radii = new Map();
for (const node of record.scene.exportRecipe().nodes ?? []) {
if (node.blend !== undefined) radii.set(node.id, normalizeBlend(node.blend).radius);
}
record.renderer.meshBlend.radii = radii;
}
function renderStatus(record) {
const render = renderInfo(record.renderer);
record.lastRender = render;
return {
sessionId: record.sessionId,
revision: record.scene.revision,
topologyRevision: record.scene.topologyRevision,
render,
};
}
function status(record) {
const { sessionId, revision, topologyRevision, render } = renderStatus(record);
return { sessionId, revision, topologyRevision, inspection: record.scene.inspect(), render };
}
// The answer to an edit stays short: it holds no node list, because every answer stays in the agent's context.
// An agent that needs the node list calls scene_inspect. The scene's own warnings (closed room without a bake, stale bake,
// coplanar overlap, ignored material fields) still ride along, only when there are any.
function sceneDiagnostics(record) {
const { diagnostics } = record.scene.inspect();
return diagnostics?.length ? { diagnostics } : {};
}
// An edit that released old undo steps to fit the vertex budget says so, so the agent does not rely on them.
function undoReleaseNote(record) {
const released = record.scene.releasedRevisions ?? 0;
return released > 0 ? { undoNote: `Released ${released} oldest undo revision${released === 1 ? '' : 's'} to fit maxVertices; newer ones still undo.` } : {};
}
function mutationStatus(record) {
try {
draw(record);
return { ...renderStatus(record), ...sceneDiagnostics(record), ...undoReleaseNote(record), committed: true, renderSucceeded: true };
} catch (error) {
return {
sessionId: record.sessionId,
revision: record.scene.revision,
render: record.lastRender ?? null,
...sceneDiagnostics(record),
...undoReleaseNote(record),
committed: true,
renderSucceeded: false,
renderError: error.message,
};
}
}
// Draw the part labels onto a copy of the frame, so the preview canvas itself stays unmarked.
function labeledPng(labels) {
if (!labels) return canvas.toDataURL('image/png').split(',')[1];
const composed = document.createElement('canvas');
composed.width = canvas.width;
composed.height = canvas.height;
const context = composed.getContext('2d');
context.drawImage(canvas, 0, 0);
paintLabels(context, labels, 0, 0);
return composed.toDataURL('image/png').split(',')[1];
}
function resetCanvas() {
canvas.getContext('webgl2')?.getExtension('WEBGL_lose_context')?.loseContext();
const replacement = document.createElement('canvas');
canvas.replaceWith(replacement);
canvas = replacement;
}
// The cascade code is a loaded module, so a scene with one shadow map never runs it.
function cascadeCountFor(scene) {
return agentSceneModule('cascades').effectiveShadowCascades(scene.environment, fitAgentShadow(scene.shadow, scene.parts));
}
// Wind strength of the recipe; absent keeps the renderer default. The heading is applied by applyRecipeWindHeading.
function windFrame(environment) {
if (!environment.wind) return {};
return { wind: environment.wind.strength };
}
// The heading lives in the on-demand world material code, so the core renderer carries nothing for it.
function applyRecipeWindHeading(renderer, environment) {
if (!agentSceneModuleLoaded('worldMaterials') || (!environment.wind && !renderer.windHeading)) return;
agentSceneModule('worldMaterials').applyWindHeading(renderer, (environment.wind?.direction ?? 0) * Math.PI / 180);
}
function cascadesFor(scene) {
const count = cascadeCountFor(scene);
return count > 0 ? agentSceneModule('cascades').createCascadedShadows({ count }) : null;
}
function initializeRenderer(scene, { memoryBudgetMiB, backend, transparent = false, tier = 'realtime' }) {
probeSnippets(scene);
const placement = automaticGroundPlacement(scene);
const renderer = installCoplanarDiagnostics(installRenderPasses(installCameraEffects(new CrucibleRenderer(canvas, scene.parts, {
ground: placement ? createAgentGround(placement) : false,
hdr: true,
depth: true,
world: scene.environment.world,
environment: litEnvironment(scene.parts, scene.environment, Boolean(placement)),
shadowBounds: resolveAgentShadow(fitAgentShadow(scene.shadow, scene.parts), scene.environment.lightDirection),
shadowCascades: cascadesFor(scene),
skyOpenness,
fogSkyVisibility,
pixelRatio: 1,
...rasterOptionsFor(tier, backend),
memoryBudgetMiB,
maximumMemoryBudgetMiB: MEMORY_CEILING_MIB,
transparent,
// Every preview and job frame is read back or exported, so none may draw with the fallback post program of a build in flight (#1767).
exactFrames: true,
}))));
// Outlines, toon light and polylines draw only for a frame that carries environment.lines; user passes run last, on the finished frame.
// Mesh blend installs before line art, so its stage runs first and the lines draw over the blended colour; it blends only the
// parts whose nodes carry `blend` (syncMeshBlend), so a recipe without it draws as before.
return agentSceneModule('userPass').installUserPasses(agentSceneModule('lineArt').installLineArt(installMeshBlend(renderer)));
}
// Camera fields from a timeline shot on top of the sampled camera, checked with the scene's own camera rules.
function withCameraOverrides(camera, overrides) {
const merged = createAgentScene({ format: 'crucible.scene', schemaVersion: 1,
geometries: [], materials: [], nodes: [], camera: { ...camera, ...overrides } }).camera;
validatePreviewCamera(merged);
return merged;
}
// The camera at the start of the shutter interval, sampled from time so the same seek always gives the same blur.
function previousCameraFor(record, motionTime, forVelocity = false) {
const shutter = record.scene.effects.motionBlur.shutter || (forVelocity ? 1 / 24 : 0);
if (shutter <= 0 || motionTime === undefined || record.asset) return undefined;
record.scene.sampleMotion(Math.max(0, motionTime - shutter));
const previousCamera = record.scene.camera;
record.scene.sampleMotion(motionTime);
return previousCamera;
}
// The parts' world matrices now and at the start of the shutter, sampled from time like the previous camera. Only a scene that
// asks for object blur (and has motion to sample) pays for it; an imported asset animates by skin, which this does not follow.
function objectMotionFor(record, motionTime, forVelocity = false) {
const { shutter: blurShutter, objects } = record.scene.effects.motionBlur;
const shutter = blurShutter || (forVelocity ? 1 / 24 : 0);
if (!(shutter > 0 && (objects > 0 || forVelocity)) || motionTime === undefined || record.asset) return undefined;
const { sampleWorldMatrices } = agentSceneModule('objectMotionBlur');
const current = sampleWorldMatrices(record.scene.parts);
record.scene.sampleMotion(Math.max(0, motionTime - shutter));
const previous = sampleWorldMatrices(record.scene.parts);
record.scene.sampleMotion(motionTime);
return { current, previous };
}
function createPreview(scene, { sessionId, memoryBudgetMiB, backend, transparent = false, tier = 'realtime' }, asset, placedAssets, sequenceFrames) {
if (leasedRecord) throw new Error('The scene renderer is leased to a render job.');
validatePreviewCamera(scene.camera);
let renderer;
try {
releaseOtherRenderers(null);
renderer = initializeRenderer(scene, { memoryBudgetMiB, backend, transparent, tier });
const record = { scene, renderer, asset, placedAssets, sessionId, options: { memoryBudgetMiB, backend, transparent, tier },
checkpoints: new Map(), evictedCheckpointIds: [], branches: createBranchStore(), rendererTopology: scene.topologyRevision, rendererTextured: sceneIsTextured(scene), sequenceFrames };
draw(record);
const result = status(record);
if (backend === 'gpu' && /swiftshader|llvmpipe|software/i.test(result.render.graphics)) {
throw new Error('Hardware GPU rendering was requested, but the browser selected a software renderer.');
}
const { evicted, reason } = evictForNewScene(result.inspection.residentGeometryBytes ?? 0);
records.set(sessionId, record);
return evicted.length ? { ...result, evictedSessions: evicted, evictionReason: reason } : result;
} catch (error) {
renderer?.dispose();
// A throwing constructor may already own GPU objects without returning an instance.
resetCanvas();
throw error;
}
}
// Manifold is an optional peer dependency; the runtime serves it from the host's node_modules on this origin.
setManifoldModuleLoader(() => import(/* @vite-ignore */ new URL('/vendor/manifold.js', location.href).href));
// Rapier is the same kind of optional peer: its WASM travels inside the module served from /vendor/rapier.js.
setPhysicsModuleLoader(() => import(/* @vite-ignore */ new URL('/vendor/rapier.js', location.href).href));
// The preview bundle is one file, so the on-demand scene modules load together on the first call and later calls stay
// synchronous. The boolean engine is WebAssembly and loads asynchronously, once, only for calls that need it.
let queryOnly;
const ASSET_DECODE_LIMITS = agentAssetDecodeOptions();
// An agent cannot pass loadGltf options, so a limit error names the catalog limits instead of "Fix: pass { ... }".
async function parseCatalogAsset(buffer) {
try {
return await parseGltf(buffer, ASSET_DECODE_LIMITS);
} catch (error) {
throw withCatalogLimitAdvice(error);
}
}
function disposePlacedAssets(pool) {
for (const asset of pool?.values() ?? []) asset.dispose();
pool?.clear();
}
// A recipe that places catalog assets arrives with their bytes, keyed by asset id. Copy 0 serves every still placement and
// each placement that plays a clip takes a copy of its own, since a pose is state of one decoded asset.
async function loadPlacedAssets(pool, value, assetData) {
for (const { id, copies } of recipeAssetNeeds(value)) {
for (let copy = 0; copy < copies; copy++) {
const key = assetCopyKey(id, copy);
if (pool.has(key)) continue;
if (!assetData?.[id]) throw new Error(`Asset ${id.slice(0, 12)} was not supplied. Check asset_catalog for its id.`);
pool.set(key, await parseCatalogAsset(bytesFromBase64(assetData[id]).buffer));
}
}
}
function afterMeshBooleans(value, run) {
if (!allAgentSceneModulesLoaded()) return loadAllAgentSceneModules().then(() => afterMeshBooleans(value, run));
const loads = [];
if (!meshBooleansLoaded() && needsMeshBooleans(value)) loads.push(loadMeshBooleans());
if (needsPhysics(value) && (!physicsEngineLoaded() || needsBuoyancy(value))) loads.push(loadPhysicsEngine({ buoyancy: needsBuoyancy(value) }));
if (!loads.length) return run();
return Promise.all(loads).then(run);
}
// Heavy kernels (light bake, cloth, uv_unwrap, pattern textures) compute on a worker while the page stays responsive;
// the scene is built from the same bytes as on one thread. Reading each part's maps here makes pattern bakes run in the
// same pass, so the renderer later finds them baked.
// Where the work ran, for scene_inspect: kernels served by the worker and run inline (with the reason for any
// fallback), the time of the last scene build, and the longest main-thread task the browser reported since then.
// Long tasks are those over 50 ms, so 0 means none that long.
const longTaskObserver = typeof PerformanceObserver === 'function' && PerformanceObserver.supportedEntryTypes?.includes('longtask')
? new PerformanceObserver(() => {})
: null;
longTaskObserver?.observe({ type: 'longtask' });
const buildReport = { buildMilliseconds: 0, longestBlockMilliseconds: 0, longestLongTaskMilliseconds: 0, longTasks: 0 };
// The long task API skips work run by a remote-debugging call, so a timer also measures how long the page stayed
// unresponsive: the longest delay of a 20 ms tick is the longest stretch the main thread was busy.
const HEARTBEAT_MILLISECONDS = 20;
let lastHeartbeat = performance.now();
setInterval(() => {
const now = performance.now();
buildReport.longestBlockMilliseconds = Math.max(buildReport.longestBlockMilliseconds, Math.round(now - lastHeartbeat - HEARTBEAT_MILLISECONDS));
lastHeartbeat = now;
}, HEARTBEAT_MILLISECONDS);
function drainLongTasks() {
for (const entry of longTaskObserver?.takeRecords() ?? []) {
buildReport.longTasks++;
buildReport.longestLongTaskMilliseconds = Math.max(buildReport.longestLongTaskMilliseconds, Math.round(entry.duration));
}
}
function startBuildReport() {
drainLongTasks();
Object.assign(buildReport, { buildMilliseconds: 0, longestBlockMilliseconds: 0, longestLongTaskMilliseconds: 0, longTasks: 0 });
lastHeartbeat = performance.now();
resetKernelStats();
}
function finishBuildReport(startedAt) {
buildReport.buildMilliseconds = Math.round(performance.now() - startedAt);
}
function kernelReport() {
drainLongTasks();
return { ...kernelStats(), ...buildReport };
}
// The runtime can switch workers off (createAgentRuntime kernelWorkers: false) to measure what they buy.
function useKernelWorkers() {
return kernelWorkersAvailable() && globalThis.__crucibleKernelWorkers !== 'off';
}
// A recipe bake runs on the native tracer when the host offers it, on the GPU when the page has float render targets, and on
// the CPU everywhere else.
async function pageKernelsFor(recipe, backend) {
if (!recipe.bake || backend !== 'gpu') return undefined;
const { gpuBakeKernels } = await import('../src/agent-bake-gpu.js');
return gpuBakeKernels({ texelTracer: await nativeTexelTracerIfAvailable() });
}
async function buildSceneOffMainThread(recipe, options, backend) {
const pageKernels = await pageKernelsFor(recipe, backend);
return buildWithKernels(() => {
const scene = createAgentScene(recipe, {}, options);
for (const part of scene.parts) {
void part.material.map;
}
return scene;
}, { pageKernels });
}
function seekForExport(record, motionTime) {
if (record.asset) record.scene.sampleFrame({ motionTime });
else record.scene.sampleMotion(motionTime);
}
// The scene's parts already carry the current pose, including IK and node overrides, so skinned parts export it as is.
function posedExport(record) {
const rig = record.scene.rigExport?.() ?? { nodes: [], clips: [] };
const options = rig.nodes.length ? rig : {};
return { parts: record.scene.parts.map(withoutRoundoffShear), options: { ...options, nodePaths: nodePathsOf(record.scene.exportRecipe().nodes) } };
}
/** "parent > child" for each node that has a parent, so an export error says where the node sits. */
function nodePathsOf(nodes = []) {
const parentOf = new Map(nodes.map(node => [node.id, node.parent]));
const paths = {};
for (const node of nodes) {
const chain = [node.id];
for (let parent = node.parent; parent && chain.length <= nodes.length; parent = parentOf.get(parent)) chain.unshift(parent);
if (chain.length > 1) paths[node.id] = chain.join(' > ');
}
return paths;
}
// Chains of bone transforms leave world matrices with Float32 roundoff that the exporter reads as shear. Real shear
// (dot products above the tolerance) still reaches the exporter and fails there.
const ROUNDOFF_SHEAR_LIMIT = 1e-3;
function withoutRoundoffShear(part) {
if (part.skin) return part;
const columns = [0, 4, 8].map(offset => {
const column = [part.matrix[offset], part.matrix[offset + 1], part.matrix[offset + 2]];
const length = Math.hypot(...column);
return length === 0 ? column : column.map(value => value / length);
});
const dots = [[0, 1], [0, 2], [1, 2]].map(([first, second]) => Math.abs(columns[first].reduce((sum, value, axis) => sum + value * columns[second][axis], 0)));
if (Math.max(...dots) > ROUNDOFF_SHEAR_LIMIT) return part;
const { translation, rotation, scale } = matrixFrame(part.matrix);
return { ...part, matrix: mat4.fromRotationTranslationScale(mat4.create(), rotation, translation, scale) };
}
// A source clip animates the source skeleton, so the scene must not carry a pose of its own that the clip would fight.
function clipExport(record, clipReference) {
const { asset, scene } = record;
if (!asset) throw new Error('clip needs an imported asset scene. Recipe scenes export their current pose.');
const clipIndex = resolveClipIndex(asset.animations, clipReference);
const animation = asset.animations[clipIndex];
const recipe = scene.exportRecipe();
if (recipe.animation || recipe.nodeOverrides.length || recipe.motion) {
throw new Error('Exporting a clip needs the unposed asset: remove animation, node overrides and motion first, or export without clip for the current pose.');
}
const sourceClip = clipFromGltfAnimation(animation);
const name = clipDisplayName(animation, clipIndex);
const clip = { ...sourceClip, name, tracks: [...sourceClip.tracks, ...weightTracksFromGltfAnimation(animation)] };
// Edited parts export their edited geometry on the source part's own matrix, skin and morph.
const parts = asset.parts.map((part, index) => scene.parts[index].geometry === part.geometry ? part : { ...part, geometry: scene.parts[index].geometry });
return { parts, options: { nodes: asset.nodes, clips: [clip] } };
}
function bytesToBase64(bytes) {
if (typeof bytes.toBase64 === 'function') return bytes.toBase64();
const chunkSize = 0x8000;
let binary = '';
for (let offset = 0; offset < bytes.length; offset += chunkSize) {
binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
}
return btoa(binary);
}
// The feature images of the last denoise "oidn" trace, kept until finishPathTrace draws it.
let tracedFeatures;
let tracedExposure = 1;
function encodeTracedPng(rgba, width, height) {
const canvas = document.createElement('canvas');
canvas.width = width;
canvas.height = height;
canvas.getContext('2d').putImageData(new ImageData(rgba, width, height), 0, 0);
return canvas.toDataURL('image/png').split(',')[1];
}
// The review grid outlives the private scenes drawn into it, because each branch in a review is its own scene.
let reviewGrid;
function projectToScreen(matrix, point, width, height) {
const [x, y, z] = point;
const clipX = matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12];
const clipY = matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13];
const clipW = matrix[3] * x + matrix[7] * y + matrix[11] * z + matrix[15];
if (!(clipW > 0)) return null;
const normalizedX = clipX / clipW;
const normalizedY = clipY / clipW;
if (Math.abs(normalizedX) > 1 || Math.abs(normalizedY) > 1) return null;
return { x: Math.round((normalizedX * 0.5 + 0.5) * width), y: Math.round((1 - (normalizedY * 0.5 + 0.5)) * height) };
}
function meshProblemsByGeometry(scene, geometryIds) {
const result = new Map();
if (typeof scene.inspectMeshes !== 'function' || geometryIds.length === 0) return result;
const { meshes } = scene.inspectMeshes({ geometries: geometryIds.slice(0, 16) });
for (const mesh of meshes) {
const faceTags = Array.isArray(mesh.tags) ? mesh.tags : Object.keys(mesh.tags ?? {});
result.set(mesh.geometry, { problems: mesh.problems.map(problem => problem.kind), faceTags: faceTags.slice(0, 6) });
}
return result;
}
/** Name, material tag, face tags and lint problems of the visible parts, with the pixel they project to. */
function collectLabels(record, camera, width, height) {
const { scene } = record;
// Mesh reports of an imported asset are keyed by part ID (mesh-0); a recipe's are keyed by geometry ID.
const meshKeyOf = node => record.asset ? node.id : node.geometry;
const nodes = scene.inspect({ includeBounds: true }).nodes.filter(node => node.bounds);
// An imported asset's recipe has no materials list: its parts carry no tags.
const materialTags = new Map((scene.exportRecipe().materials ?? []).map(material => [material.id, material.tag]));
const view = mat4.lookAt(mat4.create(), camera.eye, camera.target, camera.up);
const matrix = mat4.multiply(mat4.create(), applyProjection(mat4.create(), camera, width / height), view);
const geometryIds = [...new Set(nodes.map(meshKeyOf))];
const meshInfo = meshProblemsByGeometry(scene, geometryIds);
const labels = [];
for (const node of nodes) {
const center = [0, 1, 2].map(axis => (node.bounds.min[axis] + node.bounds.max[axis]) / 2);
const position = projectToScreen(matrix, center, width, height);
if (!position || labels.length >= BRANCH_LIMITS.maximumLabels) continue;
const mesh = meshInfo.get(meshKeyOf(node));
labels.push({ id: node.id, name: printableLabel(node.label), tag: materialTags.get(node.material) ?? null,
faceTags: mesh?.faceTags ?? [], problems: mesh?.problems ?? [], x: position.x, y: position.y });
}
return labels;
}
function paintLabels(context, labels, offsetX, offsetY) {
context.font = '11px sans-serif';
context.textBaseline = 'middle';
for (const label of labels) {
const text = [label.name, label.tag === 'surface' ? null : label.tag,...(label.problems.length ? [`! ${label.problems.join(',')}`] : [])].filter(Boolean).join(' ');
const x = offsetX + label.x;
const y = offsetY + label.y;
context.fillStyle = label.problems.length ? '#ff8a65' : '#ffe082';
context.fillRect(x - 2, y - 2, 4, 4);
context.lineWidth = 3;
context.strokeStyle = 'rgba(16,20,22,0.85)';
context.strokeText(text, x + 5, y);
context.fillText(text, x + 5, y);
}
}
// Kinds an addon registers are checked against what its package.json declared; one it did not declare is taken back.
const addonKindRegistries = () => [
{ point: 'registerController', field: 'controllers', list: listControllerKinds, remove: unregisterControllerKind },
{ point: 'registerCameraRig', field: 'cameraRigs', list: listCameraRigKinds, remove: unregisterCameraRigKind },
];
function takeBackKinds(before, registries) {
for (const registry of registries) {
for (const kind of registry.list()) if (!before[registry.field].includes(kind)) registry.remove(kind);
}
}
async function loadAddonModule({ url, name, extensionPoints }) {
const { setAddedGameKinds } = await import('../src/game-setup.js');
setAddedGameKinds(() => ({ controllers: listAddedControllerKinds(), cameraRigs: listAddedCameraRigKinds() }));
const kindRegistries = addonKindRegistries();
const before = Object.fromEntries(kindRegistries.map(registry => [registry.field, registry.list()]));
try {
const entry = await import(/* @vite-ignore */ url);
if (typeof entry.registerAddon !== 'function') {
throw new TypeError(`${name} does not export a registerAddon function. Export registerAddon() that registers its kinds (docs/addons.md).`);
}
entry.registerAddon();
} catch (error) {
takeBackKinds(before, kindRegistries);
throw error;
}
const added = Object.fromEntries(kindRegistries.map(registry => [registry.field, registry.list().filter(kind => !before[registry.field].includes(kind))]));
const undeclared = kindRegistries.filter(registry => added[registry.field].length > 0 && !extensionPoints.includes(registry.point));
if (undeclared.length > 0) {
takeBackKinds(before, kindRegistries);
const used = undeclared.map(registry => `${registry.point} (${added[registry.field].join(', ')})`).join(', ');
throw new RangeError(`${name} registered ${used} but its package.json "crucible".extensionPoints does not declare it. Add the point to extensionPoints, or stop registering it.`);
}
return added;
}
window.__agentPreview = {
loadAddon: loadAddonModule,
reviewBegin({ width, height }) {
reviewGrid = document.createElement('canvas');
reviewGrid.width = width;
reviewGrid.height = height;
const context = reviewGrid.getContext('2d');
context.fillStyle = '#202428';
context.fillRect(0, 0, width, height);
return { width, height };
},
reviewShot({ sessionId, shot, index, width, height, columns, labels: withLabels = false }) {
const record = requireSession(sessionId);
const recipe = record.scene.exportRecipe();
const animation = shot.animation ?? recipe.animation ?? null;
if (record.asset) {
record.scene.sampleFrame({ animation, motionTime: shot.motionTime });
} else {
if (shot.animation !== undefined) throw new RangeError('Imported animation requires an asset scene.');
record.scene.sampleMotion(shot.motionTime);
}
const camera = createAgentScene({ format: 'crucible.scene', schemaVersion: 1,
geometries: [], materials: [], nodes: [], camera: { ...record.scene.camera, ...shot.camera } }).camera;
validatePreviewCamera(camera);
draw(record, shot.rendererTime, camera);
const render = renderInfo(record.renderer, viewProblems(record, camera, record.scene.effects.exposure));
if (render.width < 64 || render.height < 64) throw new Error('Render budget reduced review below its minimum output size.');
const context = reviewGrid.getContext('2d');
const x = index % columns * width;
const y = Math.floor(index / columns) * (height + 24);
context.drawImage(canvas, x, y + 24, width, height);
context.fillStyle = '#e4e7e9';
context.font = '12px sans-serif';
context.textBaseline = 'middle';
context.fillText(shot.label.replace(/[\r\n\t]/g, ' '), x + 8, y + 12, width - 16);
const labels = withLabels ? collectLabels(record, camera, width, height) : undefined;
if (labels) paintLabels(context, labels, x, y + 24);
return { label: shot.label, camera, animation: record.asset ? animation : null,
motionTime: record.scene.motionTime ?? null, rendererTime: shot.rendererTime,
requestedWidth: width, requestedHeight: height, ...render, ...(labels ? { labels } : {}) };
},
reviewResult() {
return { data: reviewGrid.toDataURL('image/png').split(',')[1], mimeType: 'image/png' };
},
snapshot({ sessionId, expectedRevision }) {
const record = requireSession(sessionId);
if (record.scene.revision !== expectedRevision) throw new Error(staleRevisionMessage('render snapshot', expectedRevision, record.scene.revision));
return { sourceRevision: record.scene.revision, recipe: record.scene.exportRecipe(),
clips: record.asset ? record.asset.animations.map(clip => ({ duration: clip.duration })) : record.scene.placedClipEnds().map(duration => ({ duration })) };
},
// The part and material names an ID matte can name, read from the loaded scene so a job submit can refuse a name no frame will contain.
matteTargets({ sessionId }) {
const { passSupport } = requireSession(sessionId).renderer;
return { objectNames: passSupport.objectNames(), materialNames: Object.keys(passSupport.cryptomatteManifest().materials) };
},
suspend({ sessionId }) {
const record = lookupSession(sessionId);
if (leasedRecord) throw new Error('Scene renderer is already suspended.');
releaseOtherRenderers(null);
resetCanvas();
leasedRecord = record;
return { sessionId, revision: record.scene.revision, suspended: true };
},
resume({ sessionId }) {
const record = lookupSession(sessionId);
if (leasedRecord !== record) throw new Error('Scene renderer is already active.');
leasedRecord = null;
try {
record.renderer = initializeRenderer(record.scene, record.options);
record.rendererTopology = record.scene.topologyRevision;
record.rendererTextured = sceneIsTextured(record.scene);
record.shadowKey = null;
draw(record);
return status(record);
} catch (error) {
record.renderer?.dispose();
record.renderer = null;
resetCanvas();
throw error;
}
},
// Streamed texture sequences: the catalog IDs of the frames a motion time still needs, and the frames the host sends for it.
sequenceFramesNeeded({ sessionId, motionTime }) {
return missingStreamedFrames(requireSession(sessionId).scene.sequenceTextures?.() ?? [], motionTime);
},
async loadSequenceFrames({ sessionId, motionTime, sequenceData }) {
return { decodedBytes: await loadStreamedFrames(requireSession(sessionId).scene, motionTime, sequenceData) };
},
// `pass` draws one render pass instead of the lit image. Object ID frames also list the part behind each ID.
// `camera` overrides camera fields and `depthOfField` the blur and focus distance (a timeline shot); `brightness` scales exposure for a dip through black.
frame({ sessionId, animation, motionTime, rendererTime = 0, pass, passDepthRange, passFloat = false, floatOutput = false, camera: cameraOverrides, depthOfField: depthOfFieldOverrides, brightness = 1, diagnose = false }) {
const record = requireSession(sessionId);
if (!Number.isFinite(brightness) || brightness < 0 || brightness > 1) throw new RangeError('Invalid frame brightness.');
if (!Number.isFinite(rendererTime) || rendererTime < 0 || rendererTime > 3600) throw new RangeError('Invalid render time.');
if (record.asset && (animation !== undefined || motionTime !== undefined)) {
record.scene.sampleFrame({ ...(animation === undefined ? {} : { animation }),
...(motionTime === undefined ? {} : { motionTime }) });
} else if (motionTime !== undefined) {
sampleMotionTime(record.scene, motionTime);
}
const shotCamera = cameraOverrides ? withCameraOverrides(record.scene.camera, cameraOverrides) : undefined;
const forVelocity = pass === 'velocity';
const sampledPreviousCamera = (!pass || forVelocity) ? previousCameraFor(record, motionTime, forVelocity) : undefined;
const previousCamera = sampledPreviousCamera && cameraOverrides ? withCameraOverrides(sampledPreviousCamera, cameraOverrides) : sampledPreviousCamera;
const objectMotion = (!pass || forVelocity) ? objectMotionFor(record, motionTime, forVelocity) : undefined;
const exposure = record.scene.effects.exposure * brightness;
const shotEffects = depthOfFieldOverrides
? { ...record.scene.effects, depthOfField: { ...record.scene.effects.depthOfField, ...depthOfFieldOverrides } }
: undefined;
const outputFramebuffer = floatOutput && !pass ? record.floatModule.outputFor(record, canvas).framebuffer : undefined;
const drawFrame = () => draw(record, rendererTime, shotCamera, { pass, passDepthRange, passFloat, previousCamera, outputFramebuffer, ...(motionTime === undefined ? {} : { passTime: motionTime }), ...(objectMotion ? { objectMotion } : {}),
...(brightness === 1 ? {} : { exposure }), ...(shotEffects ? { effects: shotEffects } : {}) });
const wireframe = pass === 'wireframe' ? record.wireframeModule.withWireframe(record.renderer, drawFrame) : drawFrame();
// The first lit frame of a job is checked; a pass or a fade has no exposure to judge.
const checkLitFrame = diagnose && !pass && !floatOutput && brightness === 1;
const info = renderInfo(record.renderer, pass ? [] : viewProblems(record, shotCamera ?? record.scene.camera, checkLitFrame ? record.scene.effects.exposure : undefined));
return pass === 'wireframe' ? { ...info, wireframe }
: pass === 'objectId' ? { ...info, objectNames: record.renderer.passSupport.objectNames(), objectNodes: record.renderer.passSupport.objectNodes() }
: pass === 'cryptomatte' ? { ...info, cryptomatte: record.renderer.passSupport.cryptomatteManifest() }
: info;
},
// Reads the last frame as RGBA float32, rows bottom to top, cropped to `region` (pixels from the top left): the lit image
// when it was drawn with floatOutput, a pass when it was drawn with passFloat. Base64 of the float bytes.
// 16-bit PNG and EXR output load their module here, so a scene that never asks for them does not carry it.
async prepareFloatOutput({ sessionId }) {
requireSession(sessionId).floatModule = await import('../src/float-output.js');
},
// The wireframe pass draws its edges with this module, loaded here so a scene that never asks for it does not carry it.
async prepareWireframe({ sessionId }) {
requireSession(sessionId).wireframeModule = await import('../src/wireframe-pass.js');
},
readFloat({ sessionId, source, region }) {
const record = requireSession(sessionId);
return record.floatModule.readFrame(record, canvas, source, region);
},
// Offline path trace of the scene at one instant. The tracer loads here, on first use, and not with the preview.
async pathTrace({ sessionId, animation, motionTime, options }) {
const record = requireSession(sessionId);
if (record.asset && (animation !== undefined || motionTime !== undefined)) {
record.scene.sampleFrame({ ...(animation === undefined ? {} : { animation }),
...(motionTime === undefined ? {} : { motionTime }) });
} else if (motionTime !== undefined) {
record.scene.sampleMotion(motionTime);
}
const { renderPathTracedImage } = await import('../src/path-tracer.js');
const environment = record.scene.environment;
const result = await renderPathTracedImage({
parts: record.scene.parts,
// The scene's motion blur shutter also blurs a grid volume that carries velocity (#1759), in the trace as in the rasterizer.
environment: { ...pathTraceEnvironment(environment), ...(record.scene.effects.motionBlur.shutter > 0 ? { volumeShutter: record.scene.effects.motionBlur.shutter } : {}) },
camera: record.scene.camera,
}, { ...options, exposure: record.scene.effects.exposure });
tracedExposure = record.scene.effects.exposure;
// An external denoiser (denoise "oidn") works on the traced features outside the page; finishPathTrace then draws its result.
if (result.report.denoiser === 'oidn') {
tracedFeatures = result.features;
const features = {};
for (const name of ['color', 'albedo', 'normal']) {
const values = result.features[name];
features[name] = bytesToBase64(new Uint8Array(values.buffer, values.byteOffset, values.byteLength));
}
return { features, report: result.report };
}
return { data: encodeTracedPng(result.rgba, result.width, result.height), report: result.report };
},
// The scene at one instant packed into the tables the native ray query tracer reads (renderer.backend "native"). The job
// runner traces them outside the page; each table comes back as base64 bytes. With `chunked` the answer holds a `chunks`
// manifest instead of the tables, which stay here for nativeExportBlob, so no one message bounds the scene.
async exportNativeScene({ sessionId, animation, motionTime, options, chunked = false, maximumTriangles, deltaBase, keepBaseline = false }) {
const record = requireSession(sessionId);
if (record.asset && (animation !== undefined || motionTime !== undefined)) {
record.scene.sampleFrame({ ...(animation === undefined ? {} : { animation }),
...(motionTime === undefined ? {} : { motionTime }) });
} else if (motionTime !== undefined) {
record.scene.sampleMotion(motionTime);
}
const { instancing, kernel, ...packOptions } = options;
const [{ createCamera, describeIgnoredFeatures }, { buildTraceScene, resolveTexture }, pack, { buildNativeInput }, { buildJobNativeInput, buildFlattenedJobNativeInput }, gridVolumeInput] = await Promise.all([
import('../src/path-tracer.js'), import('../src/path-tracer-scene.js'), import('../src/path-tracer-gpu-pack.js'),
import('@codepawlhq/cook/pack-input'), import('@codepawlhq/cook/job-input'), import('@codepawlhq/cook/grid-volume-input'),
]);
const environment = pathTraceEnvironment(record.scene.environment);
// The "cycles" kernel gets FORMAT-v2 tables with whole materials, and copies of one geometry stay instances; the legacy kernel reads flattened v1 triangles.
const camera = createCamera(record.scene.camera, options.width, options.height);
heldNativeExportTables = null;
heldNativeExportRanges = null;
const baseline = nativeExportBaseline;
nativeExportBaseline = null;
const packed = exportNativeSceneTables({ parts: record.scene.parts, environment, camera, options: packOptions, kernel, instancing: instancing === true,
transport: chunked ? 'chunks' : 'message', maximumTriangles,
modules: { buildTraceScene, resolveTexture, buildNativeInput, buildJobNativeInput, buildFlattenedJobNativeInput, pack, gridVolumeInput } });
let exported = packed;
if (chunked) {
const split = splitExportForChunks(packed);
heldNativeExportTables = split.tables;
exported = split.manifest;
// With the baseline the job runner holds, send the ranges that changed since it. Any other baseline (a reloaded page, a
// job that asked for none) sends every table whole, so a frame never depends on a copy that is not there.
if (deltaBase !== undefined && baseline && baseline.id === deltaBase) {
heldNativeExportRanges = planExportDelta(baseline.tables, split.tables);
exported = { ...exported, chunks: { ...exported.chunks, delta: { base: deltaBase, ranges: heldNativeExportRanges } } };
}
const keptBytes = Object.values(split.tables).reduce((total, bytes) => total + bytes.byteLength, 0);
if (keepBaseline && keptBytes <= DELTA_MAXIMUM_BASELINE_BYTES) {
nativeExportBaseline = { id: `export-${++nativeExportCount}`, tables: split.tables };
exported = { ...exported, exportId: nativeExportBaseline.id };
}
}
return { ...exported, ignored: describeIgnoredFeatures(record.scene.parts, environment, 'cpu', { kernelMaterials: exported.wholeMaterials, clipStart: camera.clipStart }) };
},
// The tables of the chunked export that exportNativeScene holds, back to back in manifest order, as one Blob. The job runner
// reads it over DevTools (IO.read), which costs about half of an evaluate that returns the bytes as base64 (#1861).
nativeExportBlob() {
if (!heldNativeExportTables) {
throw new Error('nativeExportBlob: no chunked native export is held. Call exportNativeScene with chunked: true first.');
}
return new Blob(heldNativeExportRanges ? deltaPieces(heldNativeExportTables, heldNativeExportRanges) : Object.values(heldNativeExportTables));
},
// Lets go of the held export once the job runner has every table.
releaseNativeExport() {
heldNativeExportTables = null;
heldNativeExportRanges = null;
},
// The PNG of linear pixels (three floats each, base64) that a denoiser outside the page returned, or of the wavelet
// filter over the kept features when none came back.
async finishPathTrace({ width, height, linear }) {
const { toneMapToRgba8 } = await import('../src/path-tracer.js');
let pixels;
if (linear) {
const binary = atob(linear);
const bytes = new Uint8Array(binary.length);
for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
pixels = new Float32Array(bytes.buffer);
} else {
const { denoiseRadiance } = await import('../src/path-tracer-denoise.js');
pixels = denoiseRadiance({ width, height, ...tracedFeatures });
}
tracedFeatures = undefined;
return { data: encodeTracedPng(toneMapToRgba8(pixels, width, height, { exposure: tracedExposure }), width, height) };
},
async createWithAssets(input) {
const pool = new Map();
try {
await loadAllAgentSceneModules();
await loadPlacedAssets(pool, input.recipe, input.assetData);
const sequenceFrames = await loadSequenceFrames(new Map(), input.sequenceData);
// Placed assets are decoded on this thread, so the scene is built here and not on the kernel worker.
return await afterMeshBooleans(input.recipe, () => {
startBuildReport();
const startedAt = performance.now();
const scene = createAgentScene(input.recipe, {}, { assets: pool, sequenceFrames });
finishBuildReport(startedAt);
return createPreview(scene, input, undefined, pool, sequenceFrames);
});
} catch (error) {
disposePlacedAssets(pool);
throw error;
}
},
create(input) {
registerLookData(input.lookData);
registerGridData(input.gridData);
if (recipeAssetNeeds(input.recipe).length) return this.createWithAssets(input);
// Only a recipe with image sequences waits for its frames to decode; any other create stays synchronous.
const build = sequenceFrames => {
startBuildReport();
const startedAt = performance.now();
if (!useKernelWorkers()) {
const scene = createAgentScene(input.recipe, {}, { sequenceFrames });
finishBuildReport(startedAt);
return createPreview(scene, input, undefined, undefined, sequenceFrames);
}
return buildSceneOffMainThread(input.recipe, { sequenceFrames }, input.backend).then(scene => {
finishBuildReport(startedAt);
return createPreview(scene, input, undefined, undefined, sequenceFrames);
});
};
return afterMeshBooleans(input.recipe, () => (input.sequenceData ? loadSequenceFrames(new Map(), input.sequenceData).then(build) : build(new Map())));
},
async createAsset(input) {
const bytes = bytesFromBase64(input.data);
let asset;
try {
// Labels, mesh reports and motion read the on-demand modules on any asset, not only one with mesh edits.
await loadAllAgentSceneModules();
asset = await parseCatalogAsset(bytes.buffer);
return createPreview(createAgentAssetScene(asset, input.recipe, { sources: await decodeMotionSources(input.sources) }), input, asset);
} catch (error) {
asset?.dispose();
throw error;
}
},
inspect({ sessionId, ...options }) {
return { sessionId, ...requireSession(sessionId).scene.inspect(options), kernels: kernelReport() };
},
inspectMeshes({ sessionId, ...options }) {
const scene = requireSession(sessionId).scene;
if (typeof scene.inspectMeshes !== 'function') {
throw new TypeError('mesh_inspect needs a procedural recipe scene or an imported asset scene.');
}
if (!allAgentSceneModulesLoaded()) return loadAllAgentSceneModules().then(() => this.inspectMeshes({ sessionId, ...options }));
return { sessionId, ...scene.inspectMeshes(options) };
},
async queryOnlyWalkMap({ data, ...input }) {
queryOnly ??= createQueryOnlyCache(parseGltf);
return queryOnly.walkMap({ ...input, bytes: data === undefined ? undefined : bytesFromBase64(data) });
},
async walkMap({ sessionId, clearance = 2, groundRange, keepOut, streetY, includeCells = false, ...options }) {
const record = requireSession(sessionId);
if (!allAgentSceneModulesLoaded()) await loadAllAgentSceneModules();
const started = performance.now();
const query = sceneQueryFor(record);
const map = query.walkMap(walkOptionsFor(options, keepOut, streetY));
return { sessionId, revision: record.scene.revision, ...summarizeWalkMap(map, { clearance, groundRange, keepOut, includeCells }), skippedParts: query.skipped.length, milliseconds: Math.round(performance.now() - started) };
},
apply(input) {
registerLookData(input.lookData);
registerGridData(input.gridData);
if (input.sequenceData) {
const { sequenceFrames } = requireSession(input.sessionId);
if (!sequenceFrames) throw new Error('This scene was created from an imported asset and has no image sequences.');
return loadSequenceFrames(sequenceFrames, input.sequenceData).then(() => this.apply({ ...input, sequenceData: undefined }));
}
if (input.sources) {
const { scene } = requireSession(input.sessionId);
return decodeMotionSources(input.sources).then(decoded => {
scene.provideMotionSources?.(decoded);
return afterMeshBooleans(input.operations, () => this.applyLoaded(input));
});
}
if (input.assetNeeds || recipeAssetNeeds(input.operations).length) return this.applyWithAssets(input);
return afterMeshBooleans(input.operations, () => this.applyLoaded(input));
},
async applyWithAssets(input) {
const record = requireSession(input.sessionId);
if (!record.placedAssets) {
if (typeof record.scene.provideAssets !== 'function') {
throw new Error('This session holds an imported asset, which cannot place other assets. Create a scene with scene_create, then add the asset node with scene_apply.');
}
record.placedAssets = new Map();
record.scene.provideAssets(record.placedAssets);
}
await loadAllAgentSceneModules();
await loadPlacedAssets(record.placedAssets, input.assetNeeds ?? input.operations, input.assetData);
return afterMeshBooleans(input.operations, () => this.applyLoaded(input));
},
applyLoaded({ sessionId, operations, expectedRevision }) {
const record = requireSession(sessionId);
validatePreviewCamera(candidateCamera(record, operations));
let fogDensity = record.scene.environment.volumeFog.density;
for (const operation of operations) {
if (operation.type === 'set-environment' && Object.hasOwn(operation.environment?.volumeFog ?? {}, 'density')) {
fogDensity = operation.environment.volumeFog.density;
}
}
if (fogDensity > 0 && !record.renderer.capabilities.hdr) {
throw new Error('Volumetric fog requires HDR support; this preview cannot enable it.');
}
const before = typeof record.scene.exportRecipe === 'function' ? record.scene.exportRecipe() : null;
record.scene.apply(operations, { expectedRevision });
const report = before ? describeApplication(before, record.scene.exportRecipe(), operations) : {};
return { ...mutationStatus(record), ...report };
},
editMesh({ sessionId, expectedRevision, geometry, edits, replace }) {
const record = requireSession(sessionId);
if (typeof record.scene.inspectMeshes !== 'function') {
throw new TypeError('mesh_edit needs a procedural recipe scene or an imported asset scene.');
}
const operation = { type: 'edit-mesh', geometry, edits, ...(replace === undefined ? {} : { replace }) };
return afterMeshBooleans(edits, () => {
const status = this.applyLoaded({ sessionId, operations: [operation], expectedRevision });
const [mesh] = record.scene.inspectMeshes({ geometries: [geometry] }).meshes;
return { ...status, mesh };
});
},
setMeshStack({ sessionId, expectedRevision, geometry, stack, apply }) {
const record = requireSession(sessionId);
if (typeof record.scene.inspectMeshes !== 'function' || record.asset) {
throw new TypeError('mesh_stack supports procedural recipe scenes. Imported parts take mesh_edit with a mesh ID such as mesh-0.');
}
const operation = { type: 'set-mesh-stack', geometry, ...(stack === undefined ? {} : { stack }), ...(apply === undefined ? {} : { apply }) };
const status = this.applyLoaded({ sessionId, operations: [operation], expectedRevision });
const [mesh] = record.scene.inspectMeshes({ geometries: [geometry] }).meshes;
return { ...status, mesh };
},
look({ sessionId, motionTime, labels: withLabels = false }) {
const record = requireSession(sessionId);
if (motionTime !== undefined) {
if (typeof record.scene.sampleMotion !== 'function') {
throw new RangeError('Procedural motion time is unavailable for imported assets.');
}
sampleMotionTime(record.scene, motionTime);
}
// The post pass clock is the pose's motion time, as in a render job frame, so a pass anchored to a moving part stays on it.
const poseTime = record.scene.motionTime ?? undefined;
draw(record, 0, record.scene.camera, poseTime === undefined ? {} : { passTime: poseTime });
const render = renderInfo(record.renderer, viewProblems(record, record.scene.camera, record.scene.effects.exposure, { placement: true }));
record.lastRender = render;
const labels = withLabels ? collectLabels(record, record.scene.camera, canvas.width, canvas.height) : undefined;
return {
data: labeledPng(labels),
mimeType: 'image/png',
metadata: { sessionId, revision: record.scene.revision, topologyRevision: record.scene.topologyRevision,
motionTime: record.scene.motionTime ?? null, ...render, ...(labels ? { labels } : {}),
...(motionTime === undefined && recipeMoves(record.scene.exportRecipe()) ? { hints: [MOTION_NOT_SET_HINT] } : {}) },
};
},
// The findings of a view without drawing it, for a job whose frames the page does not draw (the path tracer). Exposure is
// left out because it reads the drawn frame.
findings({ sessionId, animation, motionTime }) {
const record = requireSession(sessionId);
if (record.asset && (animation !== undefined || motionTime !== undefined)) {
record.scene.sampleFrame({ ...(animation === undefined ? {} : { animation }), ...(motionTime === undefined ? {} : { motionTime }) });
} else if (motionTime !== undefined) {
record.scene.sampleMotion(motionTime);
}
return { diagnostics: viewProblems(record, record.scene.camera, undefined, { placement: true }) };
},
// One frame for scene_ask_user: the look, plus the camera it was drawn with so the marks can be turned into rays later.
annotateFrame({ sessionId, motionTime }) {
const frame = this.look({ sessionId, motionTime });
const camera = Object.fromEntries(Object.entries(requireSession(sessionId).scene.camera)
.map(([field, value]) => [field, ArrayBuffer.isView(value) ? Array.from(value) : value]));
return { ...frame, width: canvas.width, height: canvas.height, camera };
},
async pickMarks({ sessionId, camera, marks, width, height, motionTime }) {
const record = requireSession(sessionId);
// The marks were made at this time: put the scene back there so a look taken since does not move the parts under the pins.
if (motionTime !== undefined) sampleMotionTime(record.scene, motionTime);
if (!allAgentSceneModulesLoaded()) await loadAllAgentSceneModules();
const clean = validateMarks(marks, { width, height });
const query = sceneQueryFor(record);
return { revision: record.scene.revision, marks: describeMarks(clean, camera, { width, height, raycast: ray => query.raycast(ray), partMaterials: partMaterialsFor(record) }) };
},
checkpoint({ sessionId, checkpointId }) {
const record = requireSession(sessionId);
// The oldest checkpoint goes first when the scene is at its limit; the answer names it so the agent can drop it from its notes.
const evictedCheckpointIds = [];
while (record.checkpoints.size >= AGENT_SCENE_DEFAULT_LIMITS.maxCheckpoints) {
const [oldestId, oldest] = record.checkpoints.entries().next().value;
record.scene.releaseCheckpoint(oldest.handle);
record.checkpoints.delete(oldestId);
record.evictedCheckpointIds.push(oldestId);
evictedCheckpointIds.push(oldestId);
}
record.evictedCheckpointIds.splice(0, Math.max(0, record.evictedCheckpointIds.length - EVICTED_SESSIONS_KEPT));
const handle = record.scene.checkpoint();
record.checkpoints.set(checkpointId, { handle, fogDensity: record.scene.environment.volumeFog.density });
return { sessionId, checkpointId, revision: record.scene.revision, ...(evictedCheckpointIds.length ? { evictedCheckpointIds } : {}) };
},
restore({ sessionId, checkpointId, revision, expectedRevision }) {
const record = requireSession(sessionId);
if (revision !== undefined) {
record.scene.restoreRevision(revision, { expectedRevision });
return mutationStatus(record);
}
requireCheckpoint(record, checkpointId);
const checkpoint = record.checkpoints.get(checkpointId);
if (checkpoint.fogDensity > 0 && !record.renderer.capabilities.hdr) {
throw new Error('Volumetric fog requires HDR support; this preview cannot restore it.');
}
record.scene.restore(checkpoint.handle, { expectedRevision });
return mutationStatus(record);
},
releaseCheckpoint({ sessionId, checkpointId }) {
const record = requireSession(sessionId);
requireCheckpoint(record, checkpointId);
record.scene.releaseCheckpoint(record.checkpoints.get(checkpointId).handle);
record.checkpoints.delete(checkpointId);
return { sessionId, checkpointId, released: true };
},
/** Apply operations to a scratch copy and store the result as a branch. The source scene and its revision stay as they are. */
branchApply({ sessionId, name, operations, expectedRevision }) {
return afterMeshBooleans(operations, () => {
const record = requireSession(sessionId);
if (record.asset) throw new TypeError('Branches support procedural recipe scenes.');
if (record.scene.revision !== expectedRevision) throw new Error(staleRevisionMessage('branch', expectedRevision, record.scene.revision));
const baseRecipe = record.scene.exportRecipe();
const scratch = createAgentScene(baseRecipe);
validatePreviewCamera(candidateCamera(record, operations));
scratch.apply(operations, { expectedRevision: scratch.revision });
const { shared } = record.branches.fork(name, { recipe: scratch.exportRecipe(), baseRecipe, operations, baseRevision: expectedRevision });
return { sessionId, branch: name, sourceRevision: record.scene.revision, shared,
branches: record.branches.names(), snapshots: record.branches.snapshotCount() };
});
},
branchRecipe({ sessionId, name }) {
const record = requireSession(sessionId);
const branch = record.branches.get(name);
return { recipe: branch.recipe, stale: branch.baseKey !== JSON.stringify(record.scene.exportRecipe()) };
},
/** Keep one branch: replay its operations on the live scene (one revision), then drop every branch. */
keepBranch({ sessionId, name, expectedRevision }) {
const record = requireSession(sessionId);
const branch = record.branches.get(name);
if (branch.baseKey !== JSON.stringify(record.scene.exportRecipe())) {
throw new Error(`The scene changed since branch ${name} was forked. Fork it again from the current revision.`);
}
const status = this.applyLoaded({ sessionId, operations: branch.operations, expectedRevision });
record.branches.clear();
return { ...status, kept: name };
},
exportRecipe({ sessionId }) {
const record = requireSession(sessionId);
return { sessionId, revision: record.scene.revision, recipe: record.scene.exportRecipe() };
},
exportGlb({ sessionId, clip, motionTime, maxTextureSize, maximumBytes }) {
const record = requireSession(sessionId);
if (motionTime !== undefined) seekForExport(record, motionTime);
const { parts, options } = clip === undefined ? posedExport(record) : clipExport(record, clip);
const binary = exportGlb(parts, { ...options, ...(maxTextureSize === undefined ? {} : { maxTextureSize }) });
if (binary.byteLength > maximumBytes) {
throw new RangeError(`The GLB is ${binary.byteLength} bytes, above the ${maximumBytes} byte limit. Lower maxTextureSize or simplify the scene.`);
}
return { sessionId, revision: record.scene.revision, bytes: binary.byteLength,
parts: parts.length, clips: options.clips?.length ?? 0, data: bytesToBase64(new Uint8Array(binary)) };
},
dispose({ sessionId }) {
releaseRecord(lookupSession(sessionId));
return { sessionId, disposed: true };
},
};