Skip to content

3D engine that AI agents drive

13.7 KB
Raw Blame
import assert from 'node:assert/strict';
import test from 'node:test';
import { mat3 } from 'gl-matrix';
import { Matrix4, Vector3 } from 'three';
import { createSurfaceAttachment } from '../src/surface-attachment.js';
import { createMorphPose } from '../src/morph.js';
import { createSkinPose } from '../src/skinning.js';
import { createMeshQueryIndex } from '../src/mesh-query.js';

const bind = { triangle: 0, barycentric: [0.2, 0.3, 0.5] };

function target() {
  return {
    geometry: { positions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]), normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]), indices: new Uint32Array([0, 1, 2]) },
    matrix: new Float32Array(new Matrix4().elements),
    material: { tag: 'standard' },
  };
}

function close(actual, expected, tolerance = 1e-6) {
  assert.equal(actual.length, expected.length);
  for (let component = 0; component < actual.length; component++) assert.ok(Math.abs(actual[component] - expected[component]) <= tolerance, `component ${component}: ${actual[component]} versus ${expected[component]}`);
}

function rigid(matrix) {
  const first = new Vector3().fromArray(matrix, 0);
  const second = new Vector3().fromArray(matrix, 4);
  const third = new Vector3().fromArray(matrix, 8);
  assert.ok(Math.abs(first.length() - 1) < 1e-6);
  assert.ok(Math.abs(second.length() - 1) < 1e-6);
  assert.ok(Math.abs(third.length() - 1) < 1e-6);
  assert.ok(Math.abs(first.dot(second)) < 1e-6);
  assert.ok(Math.abs(first.dot(third)) < 1e-6);
  assert.ok(new Vector3().crossVectors(first, second).distanceTo(third) < 1e-6);
}

function deformable() {
  const part = target();
  part.geometry.morphTargets = [{ positions: new Float32Array([0, 0, 1, 0, 0, 2, 0, 0, 3]) }];
  part.morph = createMorphPose(1);
  part.skin = createSkinPose(2);
  part.geometry.skinIndices = new Uint16Array([0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0]);
  part.geometry.skinWeights = new Float32Array([0.25, 0.25, 0, 0, 0.25, 0.25, 0, 0, 0.25, 0.25, 0, 0]);
  return part;
}

test('literal static binding is retained, rigid and compatible with original mesh-query hits', () => {
  const part = target();
  const attachment = createSurfaceAttachment(part, { ...bind, clearance: 0.125 });
  close(attachment.matrix.subarray(12, 15), [0.3, 0.5, 0.125]);
  rigid(attachment.matrix);
  assert.equal(attachment.update(), attachment.matrix);
  const index = createMeshQueryIndex(part.geometry);
  const hit = index.raycast(part.matrix, { origin: [0.25, 0.25, 1], direction: [0, 0, -1] });
  const fromHit = createSurfaceAttachment(part, { triangle: hit.triangle, barycentric: hit.barycentric });
  close(fromHit.matrix.subarray(12, 15), [0.25, 0.25, 0]);
  const twisted = createSurfaceAttachment(part, { ...bind, rotation: Math.PI / 2 });
  close(twisted.matrix.subarray(0, 3), [0, 1, 0]);
  close(twisted.matrix.subarray(4, 7), [-1, 0, 0]);
  index.dispose();
});

test('world affine transforms give rigid axes, geometric reflected winding, and constant world clearance', () => {
  for (const reflection of [1, -1]) {
    const part = target();
    const transform = new Matrix4().makeRotationX(0.4).multiply(new Matrix4().makeScale(reflection * 2, 3, 0.5));
    transform.elements[4] += 0.6;
    transform.setPosition(4, -2, 1);
    part.matrix.set(transform.elements);
    const attachment = createSurfaceAttachment(part, { ...bind, clearance: 0.2 });
    const vertices = [new Vector3(0, 0, 0), new Vector3(1, 0, 0), new Vector3(0, 1, 0)].map(point => point.applyMatrix4(new Matrix4().fromArray(part.matrix)));
    const firstEdge = vertices[1].clone().sub(vertices[0]);
    const normal = new Vector3().crossVectors(firstEdge, vertices[2].clone().sub(vertices[0])).normalize();
    const center = vertices[0].clone().multiplyScalar(0.2).addScaledVector(vertices[1], 0.3).addScaledVector(vertices[2], 0.5);
    close(attachment.matrix.subarray(8, 11), normal.toArray());
    close(attachment.matrix.subarray(0, 3), firstEdge.normalize().toArray());
    close(attachment.matrix.subarray(12, 15), center.addScaledVector(normal, 0.2).toArray());
    rigid(attachment.matrix);
  }
});

test('relative morph runs before normalized four-influence skin and mesh world transformation', () => {
  const part = deformable();
  part.morph.weights[0] = 1;
  part.skin.jointMatrices.set(new Matrix4().makeScale(1, 1, 2).elements, 0);
  part.skin.jointMatrices.set(new Matrix4().makeTranslation(0, 0, 4).elements, 16);
  part.matrix[12] = 3;
  const attachment = createSurfaceAttachment(part, bind);
  // Normalized .25+.25 influences become .5+.5. Z = (2*z + z+4)/2.
  close(attachment.matrix.subarray(12, 15), [3.3, 0.5, 5.45]);
  const expectedNormal = new Vector3(-1.5, -3, 1).normalize();
  close(attachment.matrix.subarray(8, 11), expectedNormal.toArray());
  rigid(attachment.matrix);
});

test('homogeneous normalized Float32 weights follow the post-divide geometric triangle', () => {
  const part = target();
  part.skin = createSkinPose(3);
  part.geometry.skinIndices = new Uint16Array([0, 1, 2, 0, 0, 1, 2, 0, 0, 1, 2, 0]);
  part.geometry.skinWeights = new Float32Array([0.1, 0.2, 0.3, 0, 0.1, 0.2, 0.3, 0, 0.1, 0.2, 0.3, 0]);
  part.skin.jointMatrices[28] = 3;
  part.skin.jointMatrices[44] = 6;
  part.matrix[12] = 2;
  const attachment = createSurfaceAttachment(part, bind);
  let total = 0;
  for (let influence = 0; influence < 4; influence++) total += part.geometry.skinWeights[influence];
  const first = Math.fround(part.geometry.skinWeights[0] / total);
  const second = Math.fround(part.geometry.skinWeights[1] / total);
  const third = Math.fround(part.geometry.skinWeights[2] / total);
  const sum = Math.fround(Math.fround(first + second) + third);
  const blendedTranslation = Math.fround(Math.fround(second * 3) + Math.fround(third * 6));
  const worldTranslation = Math.fround(blendedTranslation + Math.fround(2 * sum));
  close(attachment.matrix.subarray(12, 15), [worldTranslation / sum + 0.3, 0.5, 0], 2e-6);
});

test('different influences at each selected vertex change the geometric frame rather than a shared rigid skin pose', () => {
  const part = target();
  part.skin = createSkinPose(2);
  part.skin.jointMatrices[30] = 2;
  part.geometry.skinIndices = new Uint16Array([0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0]);
  part.geometry.skinWeights = new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 0.5, 0.5, 0, 0]);
  const attachment = createSurfaceAttachment(part, bind);
  close(attachment.matrix.subarray(12, 15), [0.3, 0.5, 1.1]);
  close(attachment.matrix.subarray(8, 11), new Vector3(-2, -1, 1).normalize().toArray());
  rigid(attachment.matrix);
});

test('arbitrary pose order returns the same matrices and makes no per-update matrix allocation', context => {
  const part = deformable();
  const attachment = createSurfaceAttachment(part, bind);
  const retained = attachment.matrix;
  context.mock.method(mat3, 'create', () => { throw new Error('Per-frame normal matrix allocation'); });
  const sample = time => {
    part.morph.weights[0] = time * 0.25;
    part.skin.jointMatrices[28] = time;
    part.matrix[13] = time * 0.5;
    assert.equal(attachment.update(), retained);
    return new Float32Array(retained);
  };
  const forward = [0, 1, 2].map(sample);
  assert.deepEqual(sample(2), forward[2]);
  assert.deepEqual(sample(0), forward[0]);
  assert.deepEqual(sample(1), forward[1]);
});

test('static channel contents use immutable-upload snapshots while replacements require rebinding', () => {
  const part = deformable();
  part.morph.weights[0] = 0.5;
  const attachment = createSurfaceAttachment(part, bind);
  const expected = new Float32Array(attachment.matrix);
  part.geometry.positions.fill(100);
  part.geometry.indices.fill(0);
  part.geometry.morphTargets[0].positions.fill(10);
  part.geometry.skinIndices.fill(1);
  part.geometry.skinWeights.fill(0);
  assert.deepEqual(attachment.update(), expected);
  const original = part.geometry.positions;
  part.geometry.positions = new Float32Array(original);
  assert.throws(() => attachment.update(), /identities changed/);
  assert.deepEqual(attachment.matrix, expected);
  part.geometry.positions = original;
  assert.deepEqual(attachment.update(), expected);
  const originalWeights = part.morph.weights;
  part.morph.weights = new Float32Array(originalWeights);
  assert.throws(() => attachment.update(), /identities changed/);
  part.morph.weights = originalWeights;
  assert.deepEqual(attachment.update(), expected);
});

test('option snapshots and restored target identities recover without changing the retained output', () => {
  const part = deformable();
  const barycentric = [0.2, 0.3, 0.5];
  const attachment = createSurfaceAttachment(part, { triangle: 0, barycentric, clearance: 0.1 });
  const expected = new Float32Array(attachment.matrix);
  barycentric.fill(0);
  assert.deepEqual(attachment.update(), expected);
  for (const field of ['matrix', 'skin', 'morph']) {
    const original = part[field];
    part[field] = field === 'matrix' ? new Float32Array(original) : { ...original };
    assert.throws(() => attachment.update(), /identities changed/);
    assert.deepEqual(attachment.matrix, expected);
    part[field] = original;
    assert.deepEqual(attachment.update(), expected);
  }
  const palette = part.skin.jointMatrices;
  part.skin.jointMatrices = new Float32Array(palette);
  assert.throws(() => attachment.update(), /identities changed/);
  part.skin.jointMatrices = palette;
  assert.deepEqual(attachment.update(), expected);
  part.material.tag = 'water';
  assert.throws(() => attachment.update(), /procedural/);
  part.material.tag = 'standard';
  assert.deepEqual(attachment.update(), expected);
});

test('invalid mutable poses and triangle collapse fail atomically and permit later recovery', () => {
  const part = deformable();
  const attachment = createSurfaceAttachment(part, bind);
  const expected = new Float32Array(attachment.matrix);
  part.morph.weights[0] = NaN;
  assert.throws(() => attachment.update(), /finite/);
  assert.deepEqual(attachment.matrix, expected);
  part.morph.weights[0] = 0;
  part.skin.jointMatrices[0] = 0;
  assert.throws(() => attachment.update(), /nonsingular/);
  part.skin.jointMatrices[0] = 1;
  part.matrix[12] = 1e20;
  assert.throws(() => attachment.update(), /collapses/);
  part.matrix[12] = 0;
  assert.deepEqual(attachment.update(), expected);
  const collapsing = target();
  collapsing.geometry.morphTargets = [{ positions: new Float32Array([0, 0, 0, -1, 0, 0, 0, -1, 0]) }];
  collapsing.morph = createMorphPose(1);
  const collapseAttachment = createSurfaceAttachment(collapsing, bind);
  collapsing.morph.weights[0] = 1;
  assert.throws(() => collapseAttachment.update(), /collapses/);
  assert.ok(collapseAttachment.matrix.every(Number.isFinite));
  collapsing.morph.weights[0] = 0;
  assert.deepEqual(collapseAttachment.update(), expected);
});

test('updates validate only referenced palette entries and selected vertices', () => {
  const part = target();
  part.skin = createSkinPose(100);
  part.geometry.skinIndices = new Uint16Array(12);
  part.geometry.skinWeights = new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]);
  const attachment = createSurfaceAttachment(part, bind);
  part.skin.jointMatrices[99 * 16] = NaN;
  assert.equal(attachment.update(), attachment.matrix);
  part.skin.jointMatrices[0] = NaN;
  assert.throws(() => attachment.update(), /finite/);
});

test('binding rejects malformed coordinates, work budgets, unsupported tags and deformation contracts', () => {
  for (const options of [{ triangle: -1 }, { triangle: 1 }, { barycentric: [0, 0, 0] }, { barycentric: [-0.1, 0.5, 0.6] }, { barycentric: [NaN, 0, 1] }, { clearance: -1 }, { rotation: Infinity }, { maxVertices: 2 }, { maxTriangles: 0 }, { unknown: true }]) assert.throws(() => createSurfaceAttachment(target(), { ...bind, ...options }));
  const nearSum = createSurfaceAttachment(target(), { ...bind, barycentric: [0.2, 0.3, 0.5000005] });
  assert.ok(nearSum.matrix.every(Number.isFinite));
  for (const tag of ['water', 'foliage', 'grass', 'fire', 'smoke']) {
    const part = target();
    part.material.tag = tag;
    assert.throws(() => createSurfaceAttachment(part, bind), /procedural/);
  }
  const terrain = target();
  terrain.material.tag = 'terrain';
  assert.ok(createSurfaceAttachment(terrain, bind));
  const skinnedTerrain = deformable();
  skinnedTerrain.material.tag = 'terrain';
  assert.throws(() => createSurfaceAttachment(skinnedTerrain, bind), /procedural/);
  const assembly = target();
  assembly.assembly = {};
  assert.throws(() => createSurfaceAttachment(assembly, bind), /assembly/);
  const noPose = target();
  noPose.geometry.morphTargets = [{ positions: new Float32Array(9) }];
  assert.throws(() => createSurfaceAttachment(noPose, bind), /pose/);
  const singular = target();
  singular.matrix[0] = 0;
  assert.throws(() => createSurfaceAttachment(singular, bind), /nonsingular/);
});

test('world clearance must remain outward and nonzero after Float32 rounding', () => {
  const part = target();
  assert.throws(() => createSurfaceAttachment(part, { ...bind, clearance: 1e-50 }), /clearance collapses/);
  part.matrix[14] = 1e6;
  part.matrix[0] = 100;
  part.matrix[5] = 100;
  assert.throws(() => createSurfaceAttachment(part, { ...bind, clearance: 0.001 }), /clearance collapses/);
  const attachment = createSurfaceAttachment(part, { ...bind, clearance: 1 });
  assert.equal(attachment.matrix[14], 1e6 + 1);
});

test('a zero-area triangle elsewhere in the mesh does not block binding to a healthy triangle', () => {
  const part = target();
  part.geometry.positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 2, 2, 2]);
  part.geometry.normals = new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]);
  part.geometry.indices = new Uint32Array([0, 1, 2, 3, 3, 3]);
  const attachment = createSurfaceAttachment(part, bind);
  assert.equal(attachment.matrix.length, 16);
  assert.throws(() => createSurfaceAttachment(part, { ...bind, triangle: 1 }), /triangle is degenerate/);
});