Skip to content

3D engine that AI agents drive

13.0 KB
Raw Blame
import test from 'node:test';
import assert from 'node:assert/strict';
import { mat4 } from 'gl-matrix';
import { Bone, Skeleton, SkinnedMesh, BufferGeometry, Float32BufferAttribute, Uint16BufferAttribute, Matrix4, Matrix3, Vector3 } from 'three';
import { createSkinPose, updateSkinPose, validateSkinGeometry, validateSkinPose, skinTextureLayout, packSkinInfluences, skinInfluenceSets, reflectedSkinReport, reflectedSkinDiagnostics } from '../src/skinning.js';

function influences() {
  return { positions: new Float32Array([0.2, 1, 0]), skinIndices: new Uint16Array([0, 1, 0, 0]), skinWeights: new Float32Array([0.3, 0.7, 0, 0]) };
}

test('mesh-local palette produces the same bent position as Three.js with inverse binds and mesh transforms', () => {
  const root = new Bone();
  const child = new Bone();
  root.add(child);
  child.position.y = 1;
  root.updateMatrixWorld(true);
  const skeleton = new Skeleton([root, child]);
  const geometry = new BufferGeometry();
  const input = influences();
  geometry.setAttribute('position', new Float32BufferAttribute(input.positions, 3));
  geometry.setAttribute('skinIndex', new Uint16BufferAttribute(input.skinIndices, 4));
  geometry.setAttribute('skinWeight', new Float32BufferAttribute(input.skinWeights, 4));
  const mesh = new SkinnedMesh(geometry);
  mesh.position.set(2, 3, 0);
  mesh.updateMatrixWorld(true);
  mesh.bind(skeleton, new Matrix4().makeTranslation(0.5, 0, 0));
  child.rotation.z = 0.8;
  child.scale.set(2, 0.7, 1);
  root.updateMatrixWorld(true);
  mesh.updateMatrixWorld(true);
  const world = new Float32Array(32);
  const inverse = new Float32Array(32);
  [root, child].forEach((bone, index) => {
    world.set(bone.matrixWorld.elements, index * 16);
    inverse.set(skeleton.boneInverses[index].elements, index * 16);
  });
  const pose = createSkinPose(2);
  updateSkinPose(pose, world, inverse, mesh.matrixWorld.elements, mesh.bindMatrix.elements);
  validateSkinGeometry(input, pose);
  const expected = mesh.applyBoneTransform(0, new Vector3(...input.positions));
  const actual = new Vector3();
  for (let influence = 0; influence < 4; influence++) {
    const joint = input.skinIndices[influence];
    actual.addScaledVector(new Vector3(...input.positions).applyMatrix4(new Matrix4().fromArray(pose.jointMatrices, joint * 16)), input.skinWeights[influence]);
  }
  assert.ok(actual.distanceTo(expected) < 1e-6);
  const blended = new Matrix4();
  blended.elements.fill(0);
  for (let component = 0; component < 16; component++) blended.elements[component] = pose.jointMatrices[component] * 0.3 + pose.jointMatrices[16 + component] * 0.7;
  const normal = new Vector3(1, 1, 0).normalize();
  const correct = normal.clone().applyMatrix3(new Matrix3().getNormalMatrix(blended)).normalize();
  const threeDirection = normal.clone().transformDirection(blended);
  assert.ok(correct.distanceTo(threeDirection) > 0.1, 'nonuniform scaling requires inverse-transpose, unlike Three skin normal chunk');
  const tangent = new Vector3(1, -1, 0).transformDirection(blended);
  assert.ok(Math.abs(correct.dot(tangent)) < 1e-6);
  geometry.dispose();
  mesh.material.dispose();
  skeleton.dispose();
});

test('pose update retains buffers and rejects invalid input atomically', context => {
  const pose = createSkinPose(2);
  const matrices = pose.jointMatrices;
  const world = new Float32Array(matrices);
  const inverses = new Float32Array(matrices);
  world[28] = 2;
  context.mock.method(mat4, 'create', () => { throw new Error('Per-frame matrix allocation'); });
  updateSkinPose(pose, world, inverses);
  assert.equal(pose.jointMatrices, matrices);
  assert.equal(matrices[28], 2);
  const before = Array.from(matrices);
  world[16] = 0;
  assert.throws(() => updateSkinPose(pose, world, inverses), /singular/);
  assert.deepEqual(Array.from(matrices), before);
  world[16] = Infinity;
  assert.throws(() => updateSkinPose(pose, world, inverses), /finite/);
  assert.deepEqual(Array.from(matrices), before);
  assert.throws(() => createSkinPose(0), /Joint count/);
});

test('influences normalize explicitly without modifying inputs and guard malformed skin data', () => {
  const geometry = influences();
  const pose = createSkinPose(2);
  geometry.skinWeights.set([0.2, 0.2, 0, 0]);
  validateSkinGeometry(geometry, pose);
  const layout = skinTextureLayout(2, 16, 2);
  const data = packSkinInfluences(geometry, layout);
  assert.deepEqual(Array.from(data.subarray(0, 8)), [0, 1, 0, 0, 0.5, 0.5, 0, 0]);
  assert.ok(Math.abs(geometry.skinWeights[0] - 0.2) < 1e-7);
  geometry.skinWeights.fill(0);
  assert.throws(() => validateSkinGeometry(geometry, pose), /positive total/);
  geometry.skinWeights[0] = -1;
  assert.throws(() => validateSkinGeometry(geometry, pose), /weights/);
  geometry.skinWeights[0] = NaN;
  assert.throws(() => validateSkinGeometry(geometry, pose), /weights/);
  geometry.skinWeights[0] = 1;
  geometry.skinIndices[0] = 2;
  assert.throws(() => validateSkinGeometry(geometry, pose), /index/);
  assert.throws(() => validateSkinGeometry(geometry, null), /pose/);
  assert.throws(() => validateSkinGeometry({ ...geometry, skinWeights: new Float32Array(3) }, pose), /four values/);
});

test('singular weighted transforms and texture capacity limits fail explicitly', () => {
  const pose = createSkinPose(2);
  const geometry = influences();
  geometry.skinWeights.set([0.5, 0.5, 0, 0]);
  mat4.fromScaling(pose.jointMatrices.subarray(16), [-1, -1, 1]);
  assert.throws(() => validateSkinPose(pose, geometry), /weighted vertex/);
  assert.throws(() => skinTextureLayout(65, 8, 4), /MAX_TEXTURE_SIZE/);
  assert.equal(skinTextureLayout(64, 8, 4).bytes, 1024);
});

test('Float64 influences that round to a singular GPU blend are rejected', () => {
  const pose = createSkinPose(2);
  mat4.fromScaling(pose.jointMatrices.subarray(16), [-1, 1, 1]);
  const geometry = influences();
  geometry.skinWeights = new Float64Array([0.500000007, 0.499999993, 0, 0]);
  const packed = packSkinInfluences(geometry, skinTextureLayout(2, 16, 2));
  assert.deepEqual(Array.from(packed.subarray(4, 8)), [0.5, 0.5, 0, 0]);
  assert.throws(() => validateSkinGeometry(geometry, pose), /singular weighted vertex/);
  assert.throws(() => validateSkinPose(pose, geometry), /singular weighted vertex/);
});

test('near-affine singular mesh input cannot reuse a stale inverse or mutate the palette', () => {
  const pose = createSkinPose(1);
  const world = new Float64Array(pose.jointMatrices);
  const inverseBind = new Float64Array(pose.jointMatrices);
  const initialMesh = new Float64Array(pose.jointMatrices);
  initialMesh[12] = 3;
  updateSkinPose(pose, world, inverseBind, initialMesh);
  const before = Array.from(pose.jointMatrices);
  const invalidMesh = new Float64Array(mat4.create());
  invalidMesh[3] = 1e-6;
  invalidMesh[12] = 1e6;
  assert.equal(mat4.determinant(invalidMesh), 0);
  assert.throws(() => updateSkinPose(pose, world, inverseBind, invalidMesh), /affine/);
  assert.deepEqual(Array.from(pose.jointMatrices), before);
});

test('matrix preflight rejects singular Float32 rounding for every pose input atomically', context => {
  const pose = createSkinPose(1);
  const identity = new Float64Array(pose.jointMatrices);
  const roundedSingular = new Float64Array(identity);
  roundedSingular[0] = 1;
  roundedSingular[1] = 1;
  roundedSingular[4] = 1;
  roundedSingular[5] = 1.00000001;
  assert.ok(mat4.determinant(roundedSingular) > 1e-10);
  assert.equal(mat4.determinant(new Float32Array(roundedSingular)), 0);
  const before = Array.from(pose.jointMatrices);
  context.mock.method(mat4, 'multiply', () => { throw new Error('Math ran before Float32 input validation'); });
  for (let input = 0; input < 4; input++) {
    const inputs = [identity, identity, identity, identity];
    inputs[input] = roundedSingular;
    assert.throws(() => updateSkinPose(pose, ...inputs), /singular/);
    assert.deepEqual(Array.from(pose.jointMatrices), before);
  }
});

test('failed matrix inversion leaves the retained palette unchanged', context => {
  const pose = createSkinPose(1);
  const identity = new Float32Array(pose.jointMatrices);
  const before = Array.from(pose.jointMatrices);
  context.mock.method(mat4, 'invert', () => null);
  assert.throws(() => updateSkinPose(pose, identity, identity), /invert/);
  assert.deepEqual(Array.from(pose.jointMatrices), before);
});

test('pose calculations use Float32 mesh and bind matrices before inversion and multiplication', () => {
  const pose = createSkinPose(1);
  const identity = new Float64Array(pose.jointMatrices);
  const mesh = new Float64Array(identity);
  mesh[0] = 1.00000007;
  const bind = new Float64Array(identity);
  bind[0] = 1.00000007;
  const expectedInverse = mat4.invert(mat4.create(), new Float32Array(mesh));
  const expected = mat4.multiply(mat4.create(), expectedInverse, new Float32Array(bind));
  updateSkinPose(pose, identity, identity, mesh, bind);
  assert.deepEqual(Array.from(pose.jointMatrices), Array.from(expected));
  updateSkinPose(pose, identity, identity, mesh);
  assert.deepEqual(Array.from(pose.jointMatrices), Array.from(expectedInverse));
});

test('validateSkinPose checks each distinct influence set once and still finds a singular one', () => {
  const pose = createSkinPose(2);
  // Joint 1 mirrors x. Each joint is healthy, but a 50/50 blend with the identity flattens x to zero.
  pose.jointMatrices.set([-1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], 16);
  const repeatedHealthy = Array.from({ length: 50 }, () => [0, 0, 0, 0]).flat();
  const geometry = {
    skinIndices: new Uint16Array([...repeatedHealthy, 0, 1, 0, 0]),
    skinWeights: new Float32Array([...Array.from({ length: 50 }, () => [1, 0, 0, 0]).flat(), 0.5, 0.5, 0, 0]),
  };
  assert.equal(skinInfluenceSets(geometry).joints.length / 4, 2);
  assert.throws(() => validateSkinPose(pose, geometry), /singular weighted vertex transform/);
});

test('skinInfluenceSets rebuilds when the index array is replaced', () => {
  const skinWeights = new Float32Array([1, 0, 0, 0, 0.5, 0.5, 0, 0]);
  const first = skinInfluenceSets({ skinIndices: new Uint16Array([0, 0, 0, 0, 0, 1, 0, 0]), skinWeights });
  const replaced = skinInfluenceSets({ skinIndices: new Uint16Array([1, 0, 0, 0, 1, 1, 0, 0]), skinWeights });
  assert.notEqual(first, replaced);
  assert.deepEqual([...replaced.joints.subarray(0, 4)], [1, 0, 0, 0]);
});

test('a mirrored weighted vertex draws pinched and is reported instead of failing the pose (issue #581)', () => {
  const pose = createSkinPose(2);
  // Joint 1 mirrors x. A 25/75 blend with the identity scales x by -0.5: a mirrored but healthy transform.
  pose.jointMatrices.set([-1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], 16);
  const geometry = {
    skinIndices: new Uint16Array([0, 0, 0, 0, 0, 1, 0, 0]),
    skinWeights: new Float32Array([1, 0, 0, 0, 0.25, 0.75, 0, 0]),
  };
  const world = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
  assert.doesNotThrow(() => validateSkinPose(pose, geometry, world));
  assert.deepEqual(reflectedSkinReport(pose), { sets: 1, joints: [0, 1], weights: [0.25, 0.75] });
  const [problem] = reflectedSkinDiagnostics(new Map([[{ name: "knight" }, { skin: pose }]]));
  assert.equal(problem.kind, 'skin-reflected-vertices');
  assert.match(problem.message, /1 vertex weight set\(s\) of knight mirror .*joint 0 at 0\.25, joint 1 at 0\.75/);
  // Once the joint stops mirroring, the report clears.
  pose.jointMatrices.set([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], 16);
  validateSkinPose(pose, geometry, world);
  assert.equal(reflectedSkinReport(pose), null);
  assert.deepEqual(reflectedSkinDiagnostics(new Map([[{ name: "knight" }, { skin: pose }]])), []);
});

test('a palette of many joints equals the four-matrix Float32 product with and without identity bind and mesh matrices (issue #572)', () => {
  const jointCount = 5;
  const jointWorld = new Float32Array(jointCount * 16);
  const inverseBind = new Float32Array(jointCount * 16);
  for (let joint = 0; joint < jointCount; joint++) {
    const rotation = mat4.fromRotationTranslationScale(mat4.create(), [0.1 * joint, 0.3, 0.2, 1], [joint * 0.37, 1.1, -0.6 * joint], [1 + joint * 0.1, 1, 0.9]);
    jointWorld.set(rotation, joint * 16);
    inverseBind.set(mat4.invert(mat4.create(), rotation), joint * 16);
  }
  const transformedMesh = mat4.fromTranslation(mat4.create(), [0.4, -2.3, 1.7]);
  const transformedBind = mat4.fromScaling(mat4.create(), [1.25, 0.8, 1.1]);
  for (const [mesh, bind] of [[transformedMesh, transformedBind], [transformedMesh, mat4.create()], [mat4.create(), transformedBind], [mat4.create(), mat4.create()]]) {
    const pose = createSkinPose(jointCount);
    updateSkinPose(pose, jointWorld, inverseBind, mesh, bind, false);
    const meshInverse = mat4.invert(mat4.create(), new Float32Array(mesh));
    for (let joint = 0; joint < jointCount; joint++) {
      const product = mat4.multiply(mat4.create(), jointWorld.subarray(joint * 16, joint * 16 + 16), inverseBind.subarray(joint * 16, joint * 16 + 16));
      mat4.multiply(product, product, new Float32Array(bind));
      mat4.multiply(product, meshInverse, product);
      assert.deepEqual(Array.from(pose.jointMatrices.subarray(joint * 16, joint * 16 + 16)), Array.from(product));
    }
  }
});