Skip to content

3D engine that AI agents drive

14.8 KB
Raw Blame
import test from 'node:test';
import assert from 'node:assert/strict';
import { readFile } from 'node:fs/promises';
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { exportGlb } from '../src/export.js';
import { fromThreeObject, toThreeObject } from '../packages/three-bridge/index.mjs';

const TOLERANCE = 1e-6;

function checkerTexture() {
  const data = new Uint8Array(4 * 4 * 4).fill(200);
  const texture = new THREE.Texture({ data, width: 4, height: 4 });
  texture.colorSpace = THREE.SRGBColorSpace;
  texture.flipY = false;
  texture.wrapS = THREE.ClampToEdgeWrapping;
  return texture;
}

function buildSourceGroup() {
  const group = new THREE.Group();
  group.name = 'source';
  group.position.set(1, 2, 3);
  group.rotation.set(0.1, 0.2, 0.3);

  const box = new THREE.Mesh(new THREE.BoxGeometry(1, 2, 3), new THREE.MeshStandardMaterial({ color: 0x2f9e6b, roughness: 0.4, metalness: 0.6 }));
  box.name = 'box';
  box.position.set(-2, 0, 0);

  const sphere = new THREE.Mesh(new THREE.SphereGeometry(1, 12, 8), new THREE.MeshPhysicalMaterial({
    color: 0xffaa33, roughness: 0.2, transmission: 0.7, ior: 1.3, thickness: 0.5, clearcoat: 0.4,
    emissive: 0x112233, emissiveIntensity: 2, transparent: true, opacity: 0.8, side: THREE.DoubleSide,
  }));
  sphere.name = 'sphere';
  sphere.scale.set(1, 2, 0.5);
  sphere.position.set(2, 0, 1);

  const textured = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), new THREE.MeshStandardMaterial({ map: checkerTexture(), normalMap: checkerTexture(), normalScale: new THREE.Vector2(0.5, 0.5) }));
  textured.name = 'textured';
  textured.rotation.x = -Math.PI / 2;

  const vertexColored = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial({ vertexColors: true }));
  vertexColored.geometry.setAttribute('color', new THREE.BufferAttribute(new Float32Array(24 * 3).fill(0.25), 3));
  vertexColored.name = 'colored';
  vertexColored.position.y = 3;

  group.add(box, sphere, textured, vertexColored);
  return group;
}

function maxDifference(left, right) {
  assert.equal(left.length, right.length);
  let largest = 0;
  for (let index = 0; index < left.length; index += 1) largest = Math.max(largest, Math.abs(left[index] - right[index]));
  return largest;
}

test('the addon has no import statement and keeps three.js as a peer dependency only', async () => {
  const source = await readFile(new URL('../packages/three-bridge/index.mjs', import.meta.url), 'utf8');
  assert.doesNotMatch(source, /^\s*import\s/m);
  const pack = JSON.parse(await readFile(new URL('../packages/three-bridge/package.json', import.meta.url), 'utf8'));
  assert.equal(pack.dependencies, undefined);
  assert.ok(pack.peerDependencies.three);
  assert.ok(pack.peerDependencies['@codepawlhq/crucible']);
  const core = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
  assert.equal(core.dependencies?.three, undefined, 'the core takes no three.js runtime dependency');
});

test('a group is imported with vertex counts, index counts and world matrices', () => {
  const group = buildSourceGroup();
  const { parts, warnings } = fromThreeObject(group);
  assert.deepEqual(parts.map(part => part.name), ['box', 'sphere', 'textured', 'colored']);
  const expectedGeometries = [group.children[0], group.children[1], group.children[2], group.children[3]].map(mesh => mesh.geometry);
  parts.forEach((part, index) => {
    const geometry = expectedGeometries[index];
    assert.equal(part.geometry.positions.length / 3, geometry.attributes.position.count, `${part.name} vertices`);
    assert.equal(part.geometry.indices.length, geometry.index.count, `${part.name} indices`);
    assert.ok(maxDifference(part.matrix, group.children[index].matrixWorld.elements) < TOLERANCE, `${part.name} matrix`);
  });
  assert.equal(parts[2].geometry.uvs.length, 4 * 2);
  assert.equal(parts[3].geometry.colors.length, 24 * 3);
  assert.equal(parts[0].geometry.colors, undefined, 'colours import only when material.vertexColors is on');
  assert.deepEqual(warnings, [], 'a supported tree gives no warnings');
});

test('material fields map to the Crucible material', () => {
  const { parts } = fromThreeObject(buildSourceGroup());
  const [box, sphere, textured] = parts.map(part => part.material);
  assert.ok(maxDifference(box.color, new THREE.Color(0x2f9e6b).toArray()) < TOLERANCE);
  assert.equal(box.roughness, 0.4);
  assert.equal(box.metallic, 0.6);
  assert.equal(sphere.transmission, 0.7);
  assert.equal(sphere.ior, 1.3);
  assert.equal(sphere.thickness, 0.5);
  assert.equal(sphere.clearcoat, 0.4);
  assert.equal(sphere.emission, 2);
  assert.equal(sphere.alphaMode, 'blend');
  assert.equal(sphere.opacity, 0.8);
  assert.equal(sphere.doubleSided, true);
  assert.equal(textured.map.colorSpace, 'srgb');
  assert.equal(textured.map.wrapS, 33071);
  assert.equal(textured.normalMap.colorSpace, 'linear');
  assert.equal(textured.normalScale, 0.5);
  assert.equal(box.map, undefined);
});

test('import is deterministic', () => {
  assert.deepEqual(fromThreeObject(buildSourceGroup()), fromThreeObject(buildSourceGroup()));
});

test('a round trip keeps positions, normals, indices, matrices and material fields', () => {
  const group = buildSourceGroup();
  const { parts } = fromThreeObject(group);
  const { object, warnings } = toThreeObject(parts, THREE);
  assert.deepEqual(warnings, []);
  assert.equal(object.children.length, parts.length);
  object.children.forEach((mesh, index) => {
    const source = group.children[index];
    assert.equal(mesh.name, source.name);
    assert.equal(maxDifference(mesh.geometry.attributes.position.array, source.geometry.attributes.position.array), 0);
    assert.equal(maxDifference(mesh.geometry.attributes.normal.array, source.geometry.attributes.normal.array), 0);
    assert.deepEqual(Array.from(mesh.geometry.index.array), Array.from(source.geometry.index.array));
    assert.ok(maxDifference(mesh.matrixWorld.elements, source.matrixWorld.elements) < TOLERANCE, `${mesh.name} world matrix`);
    assert.ok(mesh.material.isMeshStandardMaterial);
    for (const field of ['roughness', 'metalness', 'opacity', 'transparent', 'side', 'emissiveIntensity']) {
      assert.equal(mesh.material[field], source.material[field], `${mesh.name} ${field}`);
    }
    assert.ok(maxDifference(mesh.material.color.toArray(), source.material.color.toArray()) < TOLERANCE);
    assert.ok(maxDifference(mesh.material.emissive.toArray(), source.material.emissive.toArray()) < TOLERANCE);
  });
  const sphere = object.children[1].material;
  assert.ok(sphere.isMeshPhysicalMaterial);
  assert.deepEqual([sphere.transmission, sphere.ior, sphere.thickness, sphere.clearcoat], [0.7, 1.3, 0.5, 0.4]);
  const textured = object.children[2].material;
  assert.equal(textured.map.image, group.children[2].material.map.image);
  assert.equal(textured.map.wrapS, THREE.ClampToEdgeWrapping);
  assert.equal(textured.map.colorSpace, THREE.SRGBColorSpace);
  assert.equal(textured.normalScale.x, 0.5);
  const again = fromThreeObject(object).parts;
  assert.deepEqual(again.map(part => Array.from(part.geometry.indices)), parts.map(part => Array.from(part.geometry.indices)));
  again.forEach((part, index) => assert.equal(maxDifference(part.geometry.positions, parts[index].geometry.positions), 0));
});

test('exportGlb of the bridged parts loads in GLTFLoader with matching transforms and counts', async () => {
  const group = buildSourceGroup();
  group.remove(group.children[2]);
  const { parts } = fromThreeObject(group);
  const gltf = await new GLTFLoader().parseAsync(exportGlb(parts), '');
  gltf.scene.updateMatrixWorld(true);
  const loaded = [];
  gltf.scene.traverse(node => { if (node.isMesh) loaded.push(node); });
  assert.equal(loaded.length, parts.length);
  loaded.forEach((mesh, index) => {
    const source = group.children[index];
    assert.equal(mesh.name, source.name);
    assert.equal(mesh.geometry.attributes.position.count, source.geometry.attributes.position.count);
    assert.equal(mesh.geometry.index.count, source.geometry.index.count);
    assert.ok(maxDifference(mesh.matrixWorld.elements, source.matrixWorld.elements) < TOLERANCE, `${mesh.name} node transform`);
  });
});

test('an InstancedMesh becomes one part per instance that all share one geometry', () => {
  const instanced = new THREE.InstancedMesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial(), 3);
  instanced.name = 'crate';
  for (let index = 0; index < 3; index += 1) {
    instanced.setMatrixAt(index, new THREE.Matrix4().makeTranslation(index * 2, 0, 0));
  }
  instanced.position.y = 1;
  const { parts } = fromThreeObject(instanced);
  assert.deepEqual(parts.map(part => part.name), ['crate', 'crate-1', 'crate-2']);
  assert.equal(new Set(parts.map(part => part.geometry)).size, 1);
  assert.deepEqual(parts.map(part => part.matrix[12]), [0, 2, 4]);
  assert.equal(parts[0].matrix[13], 1);
});

test('a non-indexed mesh without normals gets indices and computed normals, with a warning', () => {
  const geometry = new THREE.BufferGeometry();
  geometry.setAttribute('position', new THREE.BufferAttribute(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]), 3));
  const { parts, warnings } = fromThreeObject(new THREE.Mesh(geometry, new THREE.MeshStandardMaterial()));
  assert.deepEqual(Array.from(parts[0].geometry.indices), [0, 1, 2]);
  assert.deepEqual(Array.from(parts[0].geometry.normals.slice(0, 3)), [0, 0, 1]);
  assert.match(warnings.join('\n'), /no normal attribute/);
  assert.doesNotThrow(() => exportGlb(parts));
});

test('a material array is split by geometry group', () => {
  const geometry = new THREE.BoxGeometry(1, 1, 1);
  const materials = [new THREE.MeshStandardMaterial({ color: 0xff0000 }), new THREE.MeshStandardMaterial({ color: 0x0000ff })];
  geometry.clearGroups();
  geometry.addGroup(0, 18, 0);
  geometry.addGroup(18, 18, 1);
  const { parts } = fromThreeObject(new THREE.Mesh(geometry, materials));
  assert.equal(parts.length, 2);
  assert.deepEqual(parts.map(part => part.geometry.indices.length), [18, 18]);
  assert.notDeepEqual(parts[0].material.color, parts[1].material.color);
});

test('unsupported features are listed in warnings, never dropped silently', () => {
  const group = new THREE.Group();
  const mesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial({ envMap: new THREE.Texture(), wireframe: true, side: THREE.BackSide }));
  mesh.name = 'shiny';
  const basic = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshBasicMaterial());
  const hidden = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial());
  hidden.visible = false;
  const light = new THREE.PointLight();
  const points = new THREE.Points(new THREE.BufferGeometry(), new THREE.PointsMaterial());
  group.add(mesh, basic, hidden, light, points);
  const { parts, warnings } = fromThreeObject(group);
  assert.equal(parts.length, 2);
  const text = warnings.join('\n');
  for (const expected of ['envMap is not imported', 'wireframe is not imported', 'BackSide', 'MeshBasicMaterial has no roughness', 'invisible', 'PointLight', 'Points']) {
    assert.match(text, new RegExp(expected), expected);
  }
});

test('a shader material and a skinned mesh without bones throw errors that name the object and the fix', () => {
  const shader = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.ShaderMaterial());
  shader.name = 'glow';
  assert.throws(() => fromThreeObject(shader), /Mesh "glow" material "ShaderMaterial" is a ShaderMaterial.*MeshStandardMaterial/);
  const skinned = new THREE.SkinnedMesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial());
  skinned.name = 'hero';
  assert.throws(() => fromThreeObject(skinned), /SkinnedMesh "hero" is a SkinnedMesh without skeleton\.bones/);
  const skipped = fromThreeObject(new THREE.Group().add(shader, skinned), { skipUnsupported: true });
  assert.equal(skipped.parts.length, 0);
  assert.equal(skipped.warnings.length, 2);
});

test('limits are bounded and errors say what to pass', () => {
  const instanced = new THREE.InstancedMesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial(), 20);
  assert.throws(() => fromThreeObject(instanced, { maxParts: 10 }), /Raise maxParts/);
  assert.throws(() => fromThreeObject(new THREE.Mesh(new THREE.SphereGeometry(1, 16, 16)), { maxVertices: 50 }), /above the limit of 50/);
  assert.throws(() => fromThreeObject(instanced, { maxParts: 1e9 }), /whole number from 1 to 100000/);
  assert.throws(() => fromThreeObject(instanced, { maxPart: 5 }), /Unknown option "maxPart"/);
  assert.throws(() => fromThreeObject({}), /needs a three\.js Object3D/);
  assert.throws(() => toThreeObject([], THREE), /nonempty array of Crucible parts/);
  assert.throws(() => toThreeObject([{ name: 'a' }], THREE), /parts\[0\] "a" needs geometry\.positions/);
  assert.throws(() => toThreeObject(fromThreeObject(buildSourceGroup()).parts, {}), /needs the three\.js namespace.*Group/);
  const { parts } = fromThreeObject(buildSourceGroup());
  assert.throws(() => toThreeObject(parts, THREE, { maxParts: 2 }), /4 parts is above the limit of 2/);
  assert.throws(() => toThreeObject([{ ...parts[0], matrix: [1] }], THREE), /matrix of 16 finite numbers/);
});

function trianglePart(geometryChanges) {
  const 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]),
    ...geometryChanges,
  };
  const matrix = new THREE.Matrix4().toArray();
  return { name: 'triangle', geometry, matrix, material: { color: [1, 1, 1], metallic: 0, roughness: 1 } };
}

test('toThreeObject refuses attribute arrays that do not match the vertex count and indices past the last vertex', () => {
  assert.ok(toThreeObject([trianglePart({})], THREE).object);
  assert.throws(() => toThreeObject([trianglePart({ normals: new Float32Array(6) })], THREE), /6 values in geometry\.normals.*3 vertices need 9/);
  assert.throws(() => toThreeObject([trianglePart({ uvs: new Float32Array(4) })], THREE), /4 values in geometry\.uvs.*3 vertices need 6/);
  assert.throws(() => toThreeObject([trianglePart({ colors: new Float32Array(12) })], THREE), /12 values in geometry\.colors.*3 vertices need 9/);
  assert.throws(() => toThreeObject([trianglePart({ indices: new Uint32Array([0, 1, 3]) })], THREE), /indices entry 3.*0 to 2/);
});

test('an InstancedMesh count above its matrix array is clamped with a warning, not NaN', () => {
  const instanced = new THREE.InstancedMesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial(), 3);
  instanced.count = 5;
  const { parts, warnings } = fromThreeObject(instanced);
  assert.equal(parts.length, 3, 'one part per matrix in the array');
  for (const part of parts) assert.ok(part.matrix.every(Number.isFinite), 'every matrix is finite');
  assert.ok(warnings.some(warning => /count 5 is above the 3 matrices instanceMatrix holds/.test(warning)), 'the clamp is reported');
});