Skip to content

3D engine that AI agents drive

8.7 KB
Raw Blame

Imported asset authoring

crucible/addons/agent-asset is an optional addon available since 0.5.0. It wraps one decoded parseGltf() asset in a JSON authoring session. It preserves renderer geometry, texture descriptors, skins, morph targets, and their typed arrays. The module performs CPU validation and creates no GPU resources.

import { parseGltf } from 'crucible/addons/gltf';
import { createAgentAssetScene } from 'crucible/addons/agent-asset';

const asset = await parseGltf(glbBytes);
const scene = createAgentAssetScene(asset, {
  format: 'crucible.asset',
  schemaVersion: 1,
  assetId: sha256Hex,
});
const checkpoint = scene.checkpoint();
scene.apply([
  { type: 'set-root', translation: [0, 1, 0] },
  { type: 'set-animation', clip: 0, time: 0.5 },
], { expectedRevision: scene.revision });
scene.restore(checkpoint, { expectedRevision: scene.revision });
scene.releaseCheckpoint(checkpoint);

Recipe and IDs

The recipe requires format: 'crucible.asset', schemaVersion: 1, and a 64-character SHA256 hexadecimal assetId. The caller binds that digest to the decoded bytes. This helper validates its spelling and retains it in lowercase. It does not hash or fetch assets. Ordinary finite JSON is required: unknown keys, accessors, sparse arrays, cycles, and non-JSON objects reject.

Field Default and meaning
root.translation [0,0,0], applied to all decoded world matrices
root.rotation [0,0,0,1], XYZW quaternion; nonzero input is normalized
root.scale [1,1,1], positive values representable at Float32 precision
animation null, the pose captured when the session was created
animation.clip Integer index into decoded animation clips
animation.time Absolute seconds, from zero through that clip's duration
materialOverrides [], unique overrides keyed by material-N
camera Automatically frames conservative authored base bounds when omitted
environment, effects, shadow Complete defaults from agent look

The camera uses a 45-degree perspective lens, square aspect assumption, and 20% fit padding when generated. Its target follows the initial root and decoded node pose. Skin deformation and morph displacement are excluded from that fit. Later root or animation edits preserve the canonical camera. Use set-camera to change the view. Explicit cameras use the same defaults and validation as agent scenes.

Parts receive stable IDs mesh-0, mesh-1, and so on in decoded order. Labels remain display metadata. Geometry IDs identify shared decoded geometry. Material IDs material-0, material-1, and so on identify unique decoded material objects in first-use order. Overrides accept color, metallic, roughness, emission, and emissiveColor, with the agent scene material domains.

Other glTF material fields and texture descriptors retain their decoded values. These commands do not edit alpha modes, maps, skin bindings, vertices, indices, mesh membership, or morph target definitions.

Release 0.8.0 adds source-node and character motion. Hierarchy inspection exposes joints separately from rendered mesh primitives.

Commands and transactions

apply(operations, {expectedRevision}) requires 1 to 256 commands. The expected revision must equal the current revision. Commands form one atomic transaction. Invalid input, stale revision, invalid pose, or numeric overflow prevents publication. The recipe, revision, material values, adapter matrices, and accessible decoded pose arrays remain unchanged.

Command Fields
set-asset-node Existing editable source id plus local translation, rotation or scale
set-motion A complete motion record or explicit null
set-root Optional flat translation, rotation, scale
set-animation Optional clip, time; clip:null restores the captured pose
set-material Existing id plus optional editable material fields
set-camera Optional flat eye, target, up, fov, near, far
set-environment {environment: partial}
set-effects {effects: partial}
set-shadow {shadow: partial}

Animation seeks are absolute. Omitting time preserves time for the same clip. Changing the clip defaults time to zero. With clip:null, omit time.

Environment volumeFog and effects bloom merge partial nested records. A supplied pointLights list replaces the full list, including [] to clear it. edit-mesh (mesh_edit with a part ID such as mesh-10) edits the topology of one imported part with the same edit vocabulary as a recipe mesh; the log is kept in the recipe as meshEdits: [{ id, edits }]. The part becomes a welded polygon mesh with axis tags and a material-<n> tag on every face, and the edits run in the part's local space (imported parts are often tiny and rotated: mesh_inspect reports localToWorldScale and localAxesInWorld). New vertices take skin weights (four heaviest joints), morph deltas and vertex colours from the nearest original surface point; faces an edit leaves without UVs read the nearest original UV island. On a skinned or morphed part an edit that puts geometry farther than a quarter of the part's bounds diagonal from the original surface is rejected, because the transfer would be a guess. Edits are atomic, undone by checkpoint, and every output passes validateTopology. mesh_stack, relations and other geometry commands still reject.

parts is a frozen, stable list. Part objects, matrices, geometry, skin, morph, and material wrapper identities survive every successful transaction. Material factor getters read immutable snapshots. Map descriptors retain their original references. Part objects, geometry and topologyRevision change only when the edit log changes (parts is then a new frozen list whose matrices are the same arrays); renderer adapters take a new renderer for an edited asset, because skinned and morphed parts cannot be replaced in place. Pose, look and material edits keep every identity.

checkpoint() returns an opaque private handle. At most eight handles can be live. restore(handle, {expectedRevision}) publishes its recipe and increments revision. releaseCheckpoint(handle) frees the slot. Foreign and released handles reject. Checkpoints contain recipe snapshots, sharing existing asset resources rather than duplicating geometry or textures.

Recipes and operation JSON are bounded to 1 MiB, with at most 64 nesting levels. Construction rejects more than 4096 parts, 4096 unique materials, or 256 clips. Decoder resource budgets still belong to parseGltf(). Configure them before decoding.

Inspection and ownership

exportRecipe() and the camera/look getters return detached JSON. inspect({ids?, limit?, includeBounds?}) returns revision, topology revision, IDs, labels, counts, unique geometry bytes, animation metadata, and at most 64 nodes by default. The limit can be 1 to 256. Bounds requests scan at most two million authored base vertices across the selected visible nodes.

Returned bounds are explicitly labelled authored-base-world: actual base positions transformed by the current root and decoded mesh node matrix. Skin palettes and morph weights are preserved and validated for rendering, but inspection does not evaluate their vertex deformation. Geometry bytes count unique static typed arrays and morph delta arrays, excluding texture storage, pose buffers, renderer allocations, and GPU timing.

The session requires exclusive ownership of the decoded asset's animation state. Do not call its applyAnimation() separately or replace its parts, matrices, palettes, or morph weights while the session is active. Returning to animation:null restores captured public pose arrays. The decoder's private animation mixer is not exposed. Subsequent seeks use its absolute pose API. On failed staging, the adapter restores public arrays and, when available, replays the preceding successful clip to recover mixer state.

Parts and resource arrays are privileged renderer handles under the existing read-only geometry contract. External writes to geometry or texture data are unsupported. Detached adapter matrices or replaced decoded pose buffers reject before publication. The caller owns disposal: dispose the renderer first, then call asset.dispose() once. The session does not dispose shared imported data.

Two designs were considered: rebuilding imported assets from authoring JSON, and wrapping the decoder's retained resources. The retained adapter preserves maps and deformation resources while keeping the JSON surface small. Its fixed topology and honest base-bounds inspection make ownership and replay explicit without claiming Blender feature parity.