3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import test from 'node:test';
import assert from 'node:assert/strict';
import { constants, setPriority } from 'node:os';
import { Matrix4, Vector3 } from 'three';
import { parseGltf } from '../src/gltf.js';
import { skinnedStripAsset } from './fixtures/skinned-strip.js';
import { createTexturedRigFixture } from '../scripts/agent-asset-fixture.mjs';
setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);
function snapshot(parts) {
return parts.map(part => ({ matrix: [...part.matrix],
palette: [...part.skin?.jointMatrices ?? []], world: [...part.skin?.jointWorldMatrices ?? []],
weights: [...part.morph?.weights ?? []] }));
}
function skinnedPosition(part, vertex) {
const position = new Vector3().fromArray(part.geometry.positions, vertex * 3);
const output = new Vector3();
let total = 0;
for (let influence = 0; influence < 4; influence++) {
total += part.geometry.skinWeights[vertex * 4 + influence];
}
for (let influence = 0; influence < 4; influence++) {
const offset = vertex * 4 + influence;
const matrix = new Matrix4().fromArray(part.skin.jointMatrices, part.geometry.skinIndices[offset] * 16);
output.addScaledVector(position.clone().applyMatrix4(matrix), part.geometry.skinWeights[offset] / total);
}
return output.applyMatrix4(new Matrix4().fromArray(part.matrix));
}
test('source hierarchy metadata is detached and staged joint deformation leaves published resources unchanged', async () => {
const asset = await parseGltf(skinnedStripAsset());
const metadata = asset.nodes;
assert.deepEqual(metadata.map(node => node.id), ['node-0', 'node-1', 'node-2', 'node-3']);
assert.equal(metadata.find(node => node.id === 'node-3').parent, 'node-2');
assert.equal(metadata.find(node => node.id === 'node-3').joint, true);
assert.deepEqual(metadata.find(node => node.id === 'node-1').meshIds, ['mesh-0']);
metadata[0].translation[0] = 99;
assert.equal(asset.nodes[0].translation[0], 1);
const part = asset.parts[0];
const before = snapshot(asset.parts);
const originalVertex = skinnedPosition(part, 5);
const palette = part.skin.jointMatrices;
const transaction = asset.stagePose({ animation: null, nodeOverrides: [
{ id: 'node-3', rotation: [0, 0, Math.SQRT1_2, Math.SQRT1_2] },
] });
assert.deepEqual(snapshot(asset.parts), before);
assert.notEqual(transaction.parts[0].matrix, part.matrix);
assert.ok(skinnedPosition(transaction.parts[0], 5).distanceTo(originalVertex) > 0.5);
assert.equal(transaction.parts[0].geometry, part.geometry);
assert.equal(transaction.parts[0].material, part.material);
transaction.commit();
assert.equal(part.skin.jointMatrices, palette);
assert.ok(skinnedPosition(part, 5).distanceTo(originalVertex) > 0.5);
asset.stagePose({ animation: null }).commit();
assert.deepEqual(snapshot(asset.parts), before);
asset.dispose();
});
test('discard and failed poses restore private clip state for independent backward seeks', async () => {
const asset = await parseGltf(skinnedStripAsset());
asset.applyAnimation(0.75);
const expected = snapshot(asset.parts);
const transaction = asset.stagePose({ animation: { clip: 0, time: 1.5 }, nodeOverrides: [
{ id: 'node-0', translation: [8, 2, 0] },
] });
assert.throws(() => asset.stagePose({ animation: null }), /pending/);
transaction.discard();
assert.deepEqual(snapshot(asset.parts), expected);
assert.throws(() => transaction.commit(), /settled/);
assert.throws(() => asset.stagePose({ animation: null, nodeOverrides: [
{ id: 'node-3', rotation: [0, 0, 1, 0] },
] }), /singular/);
assert.deepEqual(snapshot(asset.parts), expected);
assert.throws(() => asset.stagePose({ animation: null, nodeOverrides: [
{ id: 'node-0', scale: [3e38, 3e38, 3e38] },
] }), /finite|singular/);
assert.deepEqual(snapshot(asset.parts), expected);
for (const time of [1.5, 0, 1.25, 0.75]) asset.applyAnimation(time);
assert.deepEqual(snapshot(asset.parts), expected);
asset.dispose();
});
test('strict pose boundaries reject malformed fields, identifiers, scale and quaternions without changing state', async () => {
const asset = await parseGltf(skinnedStripAsset());
const expected = snapshot(asset.parts);
for (const input of [
{ unknown: true }, { animation: { clip: 99, time: 0 } }, { animation: { clip: 0, time: -1 } },
{ nodeOverrides: [{ id: 'missing', translation: [0, 0, 0] }] },
{ nodeOverrides: [{ id: 'node-3', matrix: [] }] },
{ nodeOverrides: [{ id: 'node-3' }] },
{ nodeOverrides: [{ id: 'node-3', rotation: [0, 0, 0, 0] }] },
{ nodeOverrides: [{ id: 'node-3', scale: [1, 0, 1] }] },
{ nodeOverrides: [{ id: 'node-3', translation: [Infinity, 0, 0] }] },
{ nodeOverrides: [{ id: 'node-3', translation: [0, 0, 0] }, { id: 'node-3', scale: [1, 1, 1] }] },
{ nodeOverrides: Array(2) },
{ nodeOverrides: Array.from({ length: 257 }, () => ({ id: 'node-3', scale: [1, 1, 1] })) },
]) {
assert.throws(() => asset.stagePose(input));
assert.deepEqual(snapshot(asset.parts), expected);
}
let accessed = false;
const input = {};
Object.defineProperty(input, 'animation', { enumerable: true, get() { accessed = true; return null; } });
assert.throws(() => asset.stagePose(input), /unsupported/);
assert.equal(accessed, false);
const pending = asset.stagePose({ animation: null });
asset.dispose();
assert.throws(() => pending.commit(), /disposed/);
assert.throws(() => asset.stagePose({ animation: null }), /disposed/);
});
test('shared scene clones and grouped primitives keep source node IDs distinct from traversal mesh IDs', async () => {
const asset = await parseGltf(skinnedStripAsset(document => {
delete document.nodes[1].skin;
delete document.meshes[0].primitives[0].attributes.JOINTS_0;
delete document.meshes[0].primitives[0].attributes.WEIGHTS_0;
document.scenes = [{ nodes: [0] }, { nodes: [0] }];
document.scene = 1;
document.meshes[0].primitives.push(structuredClone(document.meshes[0].primitives[0]));
}));
assert.equal(asset.parts.length, 2);
assert.deepEqual(asset.nodes.find(node => node.id === 'node-1').meshIds, ['mesh-0', 'mesh-1']);
assert.equal(new Set(asset.nodes.map(node => node.id)).size, asset.nodes.length);
asset.stagePose({ nodeOverrides: [{ id: 'node-1', translation: [2, 0, 0] }] }).commit();
assert.equal(asset.parts[0].matrix[12], 3);
assert.equal(asset.parts[1].matrix[12], 3);
asset.dispose();
});
test('selected cloned scenes bind authored joint edits to their actual skin skeleton', async () => {
for (const scene of [0, 1]) {
const asset = await parseGltf(skinnedStripAsset(document => {
document.scenes = [{ nodes: [0] }, { nodes: [0] }];
document.scene = scene;
}));
assert.equal(asset.nodes.find(node => node.id === 'node-3').joint, true);
const original = skinnedPosition(asset.parts[0], 5);
asset.stagePose({ nodeOverrides: [{ id: 'node-3', rotation: [0, 0, Math.SQRT1_2, Math.SQRT1_2] }] }).commit();
assert.ok(skinnedPosition(asset.parts[0], 5).distanceTo(original) > 0.5);
asset.dispose();
}
});
test('reflected and sheared source nodes remain uneditable while decoded base poses remain usable', async () => {
for (const matrix of [
[-1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
[1, 0, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
]) {
const asset = await parseGltf(skinnedStripAsset(document => {
delete document.nodes[1].skin;
delete document.meshes[0].primitives[0].attributes.JOINTS_0;
delete document.meshes[0].primitives[0].attributes.WEIGHTS_0;
document.nodes[1].matrix = matrix;
}));
assert.equal(asset.nodes.find(node => node.id === 'node-1').editable, false);
const expected = snapshot(asset.parts);
assert.throws(() => asset.stagePose({ nodeOverrides: [{ id: 'node-1', translation: [1, 0, 0] }] }), /TRS/);
asset.stagePose({ animation: null }).commit();
assert.deepEqual(snapshot(asset.parts), expected);
asset.dispose();
}
});
test('skin and morph candidates retain palettes and weights through authored poses', async () => {
const asset = await parseGltf(skinnedStripAsset((document, append) => {
const positions = append(new Float32Array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0.25, 0, 0, 0.25, 0]), 'VEC3');
Object.assign(document.accessors[positions], { min: [0, 0, 0], max: [0, 0.25, 0] });
document.meshes[0].primitives[0].targets = [{ POSITION: positions }];
document.nodes[1].weights = [0.5];
}));
const part = asset.parts[0];
const weights = part.morph.weights;
const palette = part.skin.jointMatrices;
const transaction = asset.stagePose({ animation: { clip: 0, time: 0.5 }, nodeOverrides: [{ id: 'node-3', translation: [0.25, 1, 0] }] });
const candidate = transaction.parts[0];
transaction.commit();
const next = asset.stagePose({ animation: null });
assert.equal(next.parts[0].skin.jointMatrices, candidate.skin.jointMatrices);
assert.equal(next.parts[0].morph.weights, candidate.morph.weights);
next.commit();
assert.equal(part.morph.weights, weights);
assert.equal(part.skin.jointMatrices, palette);
assert.deepEqual([...weights], [0.5]);
asset.dispose();
});
test('textured rig parsing preserves texture descriptors across staged poses', async context => {
const previousSelf = globalThis.self;
const previousBitmap = globalThis.createImageBitmap;
globalThis.self = globalThis;
globalThis.createImageBitmap = async () => ({ width: 2, height: 2, close() {} });
context.after(() => {
if (previousSelf === undefined) delete globalThis.self;
else globalThis.self = previousSelf;
if (previousBitmap === undefined) delete globalThis.createImageBitmap;
else globalThis.createImageBitmap = previousBitmap;
});
const bytes = await createTexturedRigFixture();
const asset = await parseGltf(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
const map = asset.parts[0].material.map;
assert.ok(map);
const transaction = asset.stagePose({ nodeOverrides: [{ id: 'node-3', translation: [0.1, 1, 0] }] });
assert.equal(transaction.parts[0].material.map, map);
transaction.commit();
assert.equal(asset.parts[0].material.map, map);
asset.dispose();
});