Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

17.0 KB
Raw Blame
import './support/load-agent-scene-modules.mjs';
import assert from 'node:assert/strict';
import { createHash } from 'node:crypto';
import test from 'node:test';
import { bakeMaterialPattern, materialPatternTextures, normalizeMaterialPattern } from '../src/material-patterns.js';
import { compileMaterialGraph } from '../src/material-graph.js';
import { AGENT_SCENE_CAPABILITIES, MATERIAL_GRAPH_LIMITS, MATERIAL_GRAPH_OPERATORS } from '../src/agent-scene-capabilities.js';
import { createAgentScene } from '../src/agent-scene.js';
import { exportGlb } from '../src/export.js';

const brickGraph = {
  color: {
    ramp: {
      value: { add: [{ mul: [{ noise: { scale: 8, seed: 3 } }, 0.5] }, { mul: [{ wave: { frequency: 4, direction: 'v', shape: 'saw' } }, 0.5] }] },
      stops: [[0, [0.15, 0.05, 0.03]], [1, [0.6, 0.25, 0.15]]],
    },
  },
  roughness: { mix: [0.6, 0.95, { noise: { scale: 16, seed: 5 } }] },
  height: { noise: { scale: 12, seed: 9 } },
};

const graphPattern = (overrides = {}) => ({ type: 'graph', graph: brickGraph, resolution: 256, ...overrides });

function sha(baked) {
  const hash = createHash('sha256');
  for (const channel of ['map', 'normalMap', 'metallicRoughnessMap', 'emissiveMap']) {
    if (baked[channel]) hash.update(Buffer.from(baked[channel].image.data));
  }
  return hash.digest('hex');
}

function glbJson(bytes) {
  const array = new Uint8Array(bytes);
  const view = new DataView(array.buffer, array.byteOffset, array.byteLength);
  const length = view.getUint32(12, true);
  return JSON.parse(new TextDecoder().decode(array.subarray(20, 20 + length)));
}

function checkerboardSum(image) {
  let total = 0;
  for (const byte of image.data) total += byte;
  return total;
}

test('a graph bakes the outputs it has, and only those', () => {
  const baked = bakeMaterialPattern(normalizeMaterialPattern(graphPattern()));
  assert.equal(baked.map.colorSpace, 'srgb');
  assert.equal(baked.metallicRoughnessMap.colorSpace, 'linear');
  assert.equal(baked.normalMap.colorSpace, 'linear');
  assert.equal(baked.emissiveMap, undefined);
  const colorOnly = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', graph: { color: [1, 0, 0] }, resolution: 256 }));
  assert.equal(colorOnly.normalMap, undefined);
  assert.equal(colorOnly.metallicRoughnessMap, undefined);
  assert.equal(colorOnly.map.image.data[0], 255);
  assert.equal(colorOnly.map.image.data[1], 0);
});

test('a baked graph is identical bytes every time', () => {
  const first = sha(bakeMaterialPattern(normalizeMaterialPattern(graphPattern())));
  const second = sha(bakeMaterialPattern(normalizeMaterialPattern(graphPattern())));
  assert.equal(first, second);
  const reseeded = structuredClone(brickGraph);
  reseeded.height.noise.seed = 10;
  assert.notEqual(sha(bakeMaterialPattern(normalizeMaterialPattern(graphPattern({ graph: reseeded })))), first);
});

test('height becomes a normal map: flat height is a flat normal, relief tilts it', () => {
  const flat = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', graph: { height: 0.5 }, resolution: 256 }));
  assert.deepEqual(Array.from(flat.normalMap.image.data.slice(0, 3)), [128, 128, 255]);
  const ridge = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', graph: { height: { wave: { frequency: 4 } } }, resolution: 256, bump: 2 }));
  const tilted = Array.from({ length: 256 }, (_, column) => ridge.normalMap.image.data[column * 4]);
  assert.ok(Math.max(...tilted) - Math.min(...tilted) > 40);
});

test('a height ramp tilts the normal by bump / 32 per UV unit at any resolution, the sign pointing downhill', () => {
  for (const resolution of [256, 512]) {
    const ramp = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', graph: { height: { uv: 'u' } }, resolution, bump: 4 }));
    const { data } = ramp.normalMap.image;
    const slope = 4 / 32;
    const length = Math.hypot(slope, 1);
    const offset = (Math.floor(resolution / 2) * resolution + Math.floor(resolution / 2)) * 4;
    assert.equal(data[offset], Math.round((-slope / length * 0.5 + 0.5) * 255));
    assert.equal(data[offset + 1], 128);
    assert.equal(data[offset + 2], Math.round((1 / length * 0.5 + 0.5) * 255));
  }
});

test('the slope of a sharp joint edge stays within one texel of the edge instead of spreading over three', () => {
  const resolution = 256;
  const step = { smoothstep: [0.5, 0.5 + 1 / resolution, { uv: 'u' }] };
  const edge = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', graph: { height: step }, resolution, bump: 1 }));
  const tiltedColumns = Array.from({ length: resolution }, (_, column) => column).filter(column => edge.normalMap.image.data[(10 * resolution + column) * 4] !== 128);
  assert.ok(tiltedColumns.length <= 2, `${tiltedColumns.length} texels are tilted`);
});

test('every graph texture node tiles across the seam', () => {
  const nodes = [{ noise: { scale: 6 } }, { voronoi: { scale: 5, output: 'edge' } }, { wave: { frequency: 3, direction: 'diagonal' } }, { checker: { count: 8 } }];
  for (const node of nodes) {
    const { outputs } = compileMaterialGraph({ height: node });
    const evaluate = outputs.height.evaluate;
    const step = 1 / 1024;
    for (const row of [0.13, 0.5, 0.87]) {
      const seam = Math.abs(evaluate(1 - step / 2, row) - evaluate(step / 2, row));
      const interior = Math.abs(evaluate(0.5 + step / 2, row) - evaluate(0.5 - step / 2, row));
      assert.ok(seam < 0.2 + interior, `${Object.keys(node)[0]} seam ${seam}`);
    }
  }
});

test('the noise node returns the values of Blender 5.2 Noise Texture (2D, scale 10, detail 2, roughness 0.5, normalized)', () => {
  // Fac read back from a Cycles bake at these positions (bench/reference/README.md, 2026-11-04).
  const golden = [
    [0.080078125, 0.041015625, 0.439068],
    [0.783203125, 0.236328125, 0.398615],
    [0.501953125, 0.501953125, 0.495776],
    [0.130859375, 0.783203125, 0.461263],
    [0.998046875, 0.998046875, 0.511450],
    [0.978515625, 0.013671875, 0.487824],
  ];
  const { outputs } = compileMaterialGraph({ height: { noise: { scale: 10, octaves: 3, tile: false } } });
  for (const [u, v, expected] of golden) {
    assert.ok(Math.abs(outputs.height.evaluate(u, v) - expected) < 1e-4, `noise at ${u}, ${v}`);
  }
});

test('a noise tiles by default and differs from the endless one (tile false) only near the far edges', () => {
  const endless = compileMaterialGraph({ height: { noise: { scale: 10, octaves: 3, tile: false } } }).outputs.height.evaluate;
  const tiled = compileMaterialGraph({ height: { noise: { scale: 10, octaves: 3 } } }).outputs.height.evaluate;
  assert.ok(Math.abs(tiled(0.4, 0.3) - endless(0.4, 0.3)) < 1e-12);
  assert.ok(Math.abs(tiled(0.4, 0.3) - tiled(1.4, 2.3)) < 1e-9);
  assert.throws(() => compileMaterialGraph({ height: { noise: { tile: 'yes' } } }), /tile/);
});

test('patterns with mapping uv use the geometry UVs from uv_unwrap instead of box projection', () => {
  const recipe = {
    format: '67js.scene', schemaVersion: 1,
    geometries: [{ id: 'crate', type: 'mesh', base: { type: 'box', bevel: 0 }, stack: [{ op: 'uv_unwrap' }] }],
    materials: [{ id: 'wall', pattern: graphPattern({ mapping: 'uv' }) }, { id: 'boxed', pattern: { type: 'wood', resolution: 256 } }],
    nodes: [{ id: 'part', geometry: 'crate', material: 'wall' }],
  };
  const scene = createAgentScene(recipe);
  const [part] = scene.parts;
  assert.equal(part.material.boxMapScale, 0);
  assert.equal(part.geometry.uvs.length, part.geometry.positions.length / 3 * 2);
  assert.equal(scene.exportRecipe().materials[1].pattern.mapping, undefined);
  assert.equal(scene.exportRecipe().materials[0].pattern.mapping, 'uv');
  assert.ok(part.material.map && part.material.normalMap && part.material.metallicRoughnessMap);
  assert.equal(part.material.roughness, 1);
  const gltf = glbJson(exportGlb(scene.parts));
  assert.equal(gltf.textures.length, 3);
  assert.ok(gltf.meshes[0].primitives.every(primitive => primitive.attributes.TEXCOORD_0 !== undefined));
  assert.ok(gltf.materials[0].normalTexture);
});

test('a graph that makes emission, roughness or metallic passes it through by default', () => {
  const recipe = {
    format: '67js.scene', schemaVersion: 1,
    geometries: [{ id: 'block', type: 'box', bevel: 0 }],
    materials: [{ id: 'lamp', pattern: { type: 'graph', graph: { emission: { checker: { count: 4 } }, metallic: 1 }, mapping: 'uv', resolution: 256 } }],
    nodes: [{ id: 'part', geometry: 'block', material: 'lamp' }],
  };
  const { material } = createAgentScene(recipe).parts[0];
  assert.equal(material.emission, 1);
  assert.equal(material.metallic, 1);
  assert.equal(material.emissiveMap.colorSpace, 'srgb');
});

test('graph and preset fields do not mix', () => {
  assert.throws(() => normalizeMaterialPattern({ type: 'graph' }), /graph must be an object/);
  assert.throws(() => normalizeMaterialPattern({ type: 'wood', graph: { height: 1 } }), /unless its type is graph/);
  assert.throws(() => normalizeMaterialPattern({ type: 'graph', graph: { height: 1 }, colors: [[0, 0, 0], [1, 1, 1]] }), /does not take colors/);
  assert.throws(() => normalizeMaterialPattern({ type: 'wood', mapping: 'planar' }), /mapping must be one of/);
  const normalized = normalizeMaterialPattern(graphPattern({ mapping: 'uv' }));
  assert.deepEqual(normalizeMaterialPattern(normalized), normalized);
  assert.equal(Object.hasOwn(normalizeMaterialPattern({ type: 'wood' }), 'mapping'), false);
});

test('every capability operator compiles, and no other operator does', () => {
  const samples = {
    uv: { uv: 'u' }, image: { image: { asset: 'a'.repeat(64) } }, coord: { coord: 'object' }, mapping: { mapping: {} }, whiteNoise: { whiteNoise: {} }, brick: { brick: {} }, vec: { vec: [1, 2, 3] }, ramp: { ramp: { value: 0.5, stops: [[0, 0], [1, 1]] } },
    fresnel: { fresnel: {} }, noise: { noise: {} }, voronoi: { voronoi: {} }, wave: { wave: {} }, checker: { checker: {} }, gradient: { gradient: {} },
    layer: { layer: { base: [0, 0, 0], top: [1, 1, 1], mask: 0.5 } }, hue: { hue: { color: [1, 0, 0], shift: 0.1 } }, curve: { curve: { value: 0.5, points: [[0, 0], [1, 1]] } },
  };
  for (const name of MATERIAL_GRAPH_OPERATORS) {
    const node = samples[name] ?? (['abs', 'floor', 'fract', 'sqrt', 'invert'].includes(name) ? { [name]: 0.5 } : { [name]: [0.2, 0.4, 0.6].slice(0, ['clamp', 'smoothstep', 'mix'].includes(name) ? 3 : 2) });
    // Fresnel is view dependent, so only the emission output accepts it.
    assert.doesNotThrow(() => compileMaterialGraph({ [name === 'fresnel' ? 'emission' : 'color']: node }), name);
  }
  assert.deepEqual(AGENT_SCENE_CAPABILITIES.materialGraph.operators, MATERIAL_GRAPH_OPERATORS);
  assert.equal(AGENT_SCENE_CAPABILITIES.materialGraph.maxNodes, MATERIAL_GRAPH_LIMITS.maxNodes);
});

// ---------------------------------------------------------------------------------------------------------------
// Boundary: a graph is data. Every hostile input is rejected before any pixel is evaluated, or is inert.

function nested(depth) {
  let node = 0.5;
  for (let level = 0; level < depth; level++) node = { abs: node };
  return node;
}

test('hostile graphs are rejected', () => {
  const cycle = { abs: null };
  cycle.abs = cycle;
  const wide = { add: [0, 0] };
  for (let index = 0; index < MATERIAL_GRAPH_LIMITS.maxNodes; index++) wide.add[0] = { add: [wide.add[0], 1] };
  const hostile = {
    'proto key': JSON.parse('{"height":{"__proto__":{"abs":1}}}'),
    'proto output': JSON.parse('{"__proto__":{"height":1}}'),
    'constructor operator': { height: { constructor: [1, 2] } },
    'prototype operator': { height: { toString: [1] } },
    'inherited operator name': { height: { hasOwnProperty: 1 } },
    'cycle': { height: cycle },
    'deep nesting': { height: nested(MATERIAL_GRAPH_LIMITS.maxDepth + 5) },
    'too many nodes': { height: wide },
    'glsl as an operator': { height: { 'void main(){discard;}': 1 } },
    'glsl as a value': { height: 'void main() { gl_FragColor = vec4(1.0); }' },
    'glsl in an enum': { height: { wave: { direction: 'u; discard;' } } },
    'glsl as an output name': { 'gl_Position = vec4(0)': 1 },
    'shader injected in at': { height: { noise: { at: '1.0); evil(' } } },
    'function value': { height: () => 1 },
    'huge noise scale': { height: { noise: { scale: 1e9 } } },
    'fractional scale': { height: { noise: { scale: 2.5 } } },
    'octave bomb': { height: { noise: { octaves: 1000 } } },
    'odd checker': { height: { checker: { count: 7 } } },
    'huge literal': { height: 1e300 },
    'not a number': { height: Number.NaN },
    'infinite': { height: Number.POSITIVE_INFINITY },
    'vector for a scalar output': { height: [1, 2, 3] },
    'extra operator key': { height: { abs: 1, floor: 2 } },
    'ramp out of order': { color: { ramp: { value: 0.5, stops: [[0.8, 0], [0.2, 1]] } } },
    'ramp too long': { color: { ramp: { value: 0.5, stops: Array.from({ length: 40 }, (_, index) => [index / 40, 0]) } } },
    'empty': {},
    'array': [],
    'string graph': 'noise',
  };
  for (const [name, graph] of Object.entries(hostile)) {
    assert.throws(() => normalizeMaterialPattern({ type: 'graph', graph, resolution: 256 }), Error, name);
  }
});

test('hostile sizes and costs are rejected before any work', () => {
  assert.throws(() => normalizeMaterialPattern({ type: 'graph', graph: { height: 1 }, resolution: 100000 }), /resolution must be one of/);
  assert.throws(() => normalizeMaterialPattern({ type: 'graph', graph: { height: 1 }, resolution: '512' }), /resolution must be one of/);
  const costly = { height: { voronoi: { scale: 8, at: { add: [{ uv: 'both' }, { mul: [{ vec: [{ noise: { octaves: 6 } }, { noise: { octaves: 6 } }, 0] }, 0.1] }] } } } };
  let graph = costly.height;
  for (let level = 0; level < 5; level++) graph = { add: [graph, { voronoi: { scale: 4, at: { vec: [graph, 0, 0] } } }] };
  // The limits reject the graph while it is normalized, before any pixel is evaluated, so no clock is involved.
  assert.throws(
    () => normalizeMaterialPattern({ type: 'graph', graph: { height: graph }, resolution: 1024 }),
    error => /^Material graph: nesting deeper than/.test(error.message),
  );
});

test('hostile strings never reach a texture, a recipe or a shader', () => {
  const marker = 'discard;';
  const accepted = normalizeMaterialPattern({ type: 'graph', graph: { height: { noise: { scale: 4 } } }, resolution: 256 });
  assert.equal(JSON.stringify(accepted).includes(marker), false);
  const recipe = {
    format: '67js.scene', schemaVersion: 1, geometries: [{ id: 'block', type: 'box', bevel: 0 }],
    materials: [{ id: 'bad', pattern: { type: 'graph', graph: { color: { wave: { direction: marker } } } } }],
    nodes: [{ id: 'part', geometry: 'block', material: 'bad' }],
  };
  assert.throws(() => createAgentScene(recipe), /wave direction/);
});

test('math nodes compute the numbers they name, on numbers and on vectors', () => {
  const value = node => compileMaterialGraph({ color: node }).outputs.color;
  const scalarAt = node => value(node).evaluate(0.25, 0.75);
  assert.equal(scalarAt({ min: [0.3, 0.2] }), 0.2);
  assert.equal(scalarAt({ max: [0.3, 0.2] }), 0.3);
  assert.equal(scalarAt({ add: [{ uv: 'u' }, { uv: 'v' }] }), 1);
  assert.equal(scalarAt({ invert: 0.25 }), 0.75);
  assert.equal(scalarAt({ fract: 2.75 }), 0.75);
  assert.equal(scalarAt({ clamp: [5, 0, 1] }), 1);
  assert.equal(scalarAt({ mix: [2, 4, 0.25] }), 2.5);
  assert.equal(scalarAt({ div: [1, 0] }), 0);
  const mixed = value({ mix: [[0, 0, 0], [1, 0.5, 0.25], 0.5] });
  assert.deepEqual(mixed.parts.map(part => part(0, 0)), [0.5, 0.25, 0.125]);
});

test('the same graph shares one baked texture set across materials', () => {
  const pattern = normalizeMaterialPattern(graphPattern());
  assert.equal(materialPatternTextures(pattern), materialPatternTextures(pattern));
  assert.ok(checkerboardSum(materialPatternTextures(pattern).map.image) > 0);
});

test('graph errors name the valid options, and scene_capabilities lists the nodes an agent can use', () => {
  assert.throws(() => compileMaterialGraph({ color: { glow: 1 } }), /unknown operator "glow"\. Use one of uv, coord, mapping, vec, ramp/);
  assert.throws(() => compileMaterialGraph({ shine: 1 }), /color, roughness, metallic, emission, height/);
  assert.throws(() => compileMaterialGraph({ color: { noise: { size: 4 } } }), /does not take "size"; fields: /);
  assert.throws(() => compileMaterialGraph({ color: { wave: { frequency: 4, shape: 'square' } } }), /must be one of sine, saw, triangle/);
  const { nodes } = AGENT_SCENE_CAPABILITIES.materialGraph;
  assert.ok(nodes.textures.noise.includes('"noise"'));
  const documented = JSON.stringify(nodes);
  for (const operator of MATERIAL_GRAPH_OPERATORS) {
    assert.ok(documented.includes(operator), `${operator} is documented in scene_capabilities`);
  }
});

test('scene_capabilities says fresnel exists only as an emission factor and lists what is missing', () => {
  const coordinates = AGENT_SCENE_CAPABILITIES.materialGraph.nodes.coordinates;
  assert.match(coordinates, /In graphs: fresnel, only as an emission factor/);
  assert.match(coordinates, /Not in graphs: vertexGroup, AO, bevel, curvature/);
  assert.doesNotMatch(coordinates, /Not in graphs yet: AO, bevel, curvature, fresnel/);
});