Skip to content

3D engine that AI agents drive

11.3 KB
Raw Blame
import test from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import {
  SNIPPET_LIMITS, ShaderSnippetError, validateShaderSnippet, validateSnippetUniforms, snippetUniformDeclarations, mapShaderInfoLog, measureCodeBytes,
} from '../src/shader-snippet-validator.js';
import { normalizeUserPasses, buildPassFragment, describeUserPasses, USER_PASS_INPUTS, USER_PASS_CAPABILITIES } from '../src/user-pass.js';
import { AGENT_SCENE_CAPABILITIES } from '../src/agent-scene-capabilities.js';
import { createAgentScene, loadAgentSceneModules } from '../src/agent-scene.js';

const ENTRY = 'vec4 userPass(vec2 uv) { return texture(sceneColor, uv); }';
const wrap = body => `vec4 userPass(vec2 uv) {\n${body}\n  return texture(sceneColor, uv);\n}`;

function rejects(source, pattern, position) {
  assert.throws(() => validateShaderSnippet(source, { label: 'Test' }), error => {
    assert.ok(error instanceof ShaderSnippetError, String(error));
    assert.match(error.message, pattern);
    assert.match(error.message, /Fix: /);
    assert.ok(error.hint.length > 0);
    if (position) assert.deepEqual([error.line, error.column], position);
    return true;
  });
}

test('the validator refuses each forbidden pattern and says where', () => {
  rejects(wrap('  #define X 1'), /Preprocessor lines \(#\)/, [2, 3]);
  rejects(wrap('  while (true) {}'), /"while" loops are not allowed/, [2, 3]);
  rejects(wrap('  do {} while (false);'), /"do" loops are not allowed/, [2, 3]);
  rejects(wrap('  for (int i = 0; i < 65; i++) {}'), /more than 64 iterations/, [2, 3]);
  rejects(wrap('  for (int i = 0; i < 8; i += 0) {}'), /more than 64 iterations/);
  rejects(wrap('  for (int i = 0; i < 8; i++) { i = 0; }'), /loop counter "i" is changed/);
  rejects(wrap('  for (int i = 0; i < n; i++) {}'), /integer literal/);
  rejects(wrap('  for (float f = 0.0; f < 8.0; f += 1.0) {}'), /declare one counter/);
  rejects(wrap('  for (int i = 0; i < 8; i++) x += 1.0;'), /inside \{ \}/);
  rejects(wrap('  float a = gl_FragDepth;'), /"gl_FragDepth" is not allowed/, [2, 13]);
  rejects(wrap('  vec4 p = gl_Position;'), /"gl_Position" is not allowed/);
  rejects(wrap('  float u67_x = 1.0;'), /starts with u67_/);
  rejects(wrap('  float y = u67_output.x;'), /starts with u67_/);
  rejects(`uniform float strength;\n${ENTRY}`, /"uniform" declarations are not allowed/, [1, 1]);
  rejects(`layout(location = 0) out vec4 c;\n${ENTRY}`, /"layout" declarations/);
  rejects(`${ENTRY}\n/* never closes`, /block comment never closes/, [2, 1]);
  rejects(`${ENTRY}\n// note \\\n`, /backslash/);
  rejects(`${ENTRY} é`, /not allowed/);
  rejects('x'.repeat(SNIPPET_LIMITS.maxBytes + 1), /limit is 4096/);
  rejects('   ', /empty/);
});

test('the byte limit counts code, not comments or indentation', () => {
  const commentLine = `  // ${'a note that explains the next line '.repeat(3)}\n`;
  const commented = `${commentLine.repeat(60)}/* ${'block '.repeat(200)} */\n${wrap('    float a = 1.0;')}`;
  assert.ok(commented.length > 6000);
  const checked = validateShaderSnippet(commented);
  assert.equal(checked.source.length, commented.length);
  assert.equal(checked.source.split('\n').length, commented.split('\n').length);
  assert.ok(!checked.source.includes('note'));

  const indented = wrap(`${' '.repeat(5000)}float a = 1.0;`);
  assert.doesNotThrow(() => validateShaderSnippet(indented));

  const realCode = wrap('  float a = 1.0;\n'.repeat(300));
  assert.ok(realCode.length > 5000);
  rejects(realCode, /The fragment is \d+ bytes \(\d+ after comments and spaces are removed\); the limit is 4096\./);
  assert.throws(() => validateShaderSnippet(realCode), error => {
    const [, raw, code] = error.message.match(/is (\d+) bytes \((\d+) after/);
    assert.equal(Number(raw), realCode.length);
    assert.equal(Number(code), measureCodeBytes(realCode));
    assert.ok(Number(code) < Number(raw));
    return true;
  });

  rejects(`${commentLine.repeat(2000)}${ENTRY}`, /most accepted, comments included, is 65536/);
});

test('preprocessor lines stay refused when comments pad the snippet', () => {
  rejects(`${'// padding\n'.repeat(500)}#define X 1\n${ENTRY}`, /Preprocessor lines \(#\)/, [501, 1]);
});

test('loops nest and call helpers within the work limit', () => {
  const nested = 'void f() {\n  for (int a = 0; a < 64; a++) {\n    for (int b = 0; b < 64; b++) {\n      for (int c = 0; c < 2; c++) {}\n    }\n  }\n}';
  rejects(nested, /can run 8192 loop iterations/);
  const viaHelper = 'float blur() { float s = 0.0; for (int a = 0; a < 64; a++) { s += 1.0; } return s; }\nvoid g() { for (int b = 0; b < 64; b++) { blur(); } }\nvoid h() { for (int c = 0; c < 2; c++) { g(); } }';
  rejects(viaHelper, /Function h can run 8192/);
  const fine = validateShaderSnippet('void f() { for (int a = 0; a < 64; a++) { for (int b = 8; b > 0; b -= 2) {} } }');
  assert.equal(fine.loopWork, 256);
});

test('comments are blanked and never hide a rule', () => {
  const checked = validateShaderSnippet(`// # while\n/* uniform */ ${ENTRY}`);
  assert.ok(!checked.source.includes('while'));
  assert.equal(checked.source.split('\n').length, 2);
  rejects(`/* ok */ ${wrap('  while (a) {}')}`, /"while"/);
});

test('an entry function can be required', () => {
  const requiredFunction = { pattern: /\bvec4\s+userPass\s*\(/, example: 'vec4 userPass(vec2 uv)' };
  assert.throws(() => validateShaderSnippet('float x = 1.0;', { requiredFunction }), /entry function is missing.*Define vec4 userPass/);
});

test('uniforms: names, types, values and counts', () => {
  const options = { label: 'Pass', reservedNames: USER_PASS_INPUTS };
  const checked = validateSnippetUniforms({ amount: 0.5, tint: [1, 0, 0.5], level: { type: 'int', value: 3 }, offset: { type: 'vec2', value: [1, 2] } }, options);
  assert.deepEqual(checked.tint, { type: 'vec3', value: [1, 0, 0.5] });
  assert.equal(checked.level.type, 'int');
  assert.equal(snippetUniformDeclarations(checked), 'uniform float amount;\nuniform int level;\nuniform vec2 offset;\nuniform vec3 tint;');
  for (const [uniforms, pattern] of [
    [{ Bad: 1 }, /must match/], [{ '1a': 1 }, /must match/], [{ a_b: 1 }, /must match/], [{ ['x'.repeat(33)]: 1 }, /must match/],
    [{ float: 1 }, /keyword/], [{ time: 1 }, /keyword or an input/], [{ sceneColor: 1 }, /keyword or an input/],
    [{ a: Infinity }, /finite number/], [{ a: NaN }, /finite number/], [{ a: '1' }, /type must be one of/], [{ a: [1] }, /type must be one of/],
    [{ a: [1, 2, 3, 4, 5] }, /type must be one of/], [{ a: [1, NaN] }, /finite number/], [{ a: { type: 'int', value: 1.5 } }, /whole number/],
    [{ a: { type: 'mat4', value: [] } }, /type must be one of/], [{ a: { type: 'vec3', value: [1, 2] } }, /array of 3/],
    [{ a: { type: 'float', value: 1, extra: 1 } }, /Unknown/], [{ a: 1e39 }, /finite number/],
    [Object.fromEntries(Array.from({ length: 17 }, (_, index) => [`u${index}`, 1])), /limit is 16/],
  ]) {
    assert.throws(() => validateSnippetUniforms(uniforms, options), pattern, JSON.stringify(uniforms).slice(0, 60));
  }
  assert.deepEqual(validateSnippetUniforms(undefined), {});
});

test('info log lines map to the snippet', () => {
  const pass = normalizeUserPasses([{ name: 'broken', fragment: wrap('  vec3 v = 1.0;'), uniforms: { amount: 1 } }])[0];
  const built = buildPassFragment(pass);
  const absolute = built.headerLines + 2;
  const mapped = mapShaderInfoLog(`ERROR: 0:${absolute}: '=' : cannot convert from 'const float' to 'vec3'\nERROR: 0:3: 'x' : engine\n`, built);
  assert.match(mapped, /ERROR: snippet line 2: '=' : cannot convert/);
  assert.match(mapped, /\| vec3 v = 1\.0;/);
  assert.match(mapped, /ERROR: engine wrapper line 3: 'x' : engine/);
  assert.equal(built.source.split('\n')[built.headerLines].startsWith('vec4 userPass'), true);
  assert.ok(built.source.includes('uniform float amount;'));
});

test('the documented limits match the validator', () => {
  const { limits } = USER_PASS_CAPABILITIES;
  assert.deepEqual({ ...limits }, { maxPasses: 4, maxBytes: 4096, maxUniforms: 16, maxLoopIterations: 64, maxLoopWork: 4096 });
  assert.match(USER_PASS_CAPABILITIES.rules, /64 iterations at most, loop work under 4096/);
  assert.equal(limits.maxBytes, SNIPPET_LIMITS.maxBytes);
  assert.equal(limits.maxUniforms, SNIPPET_LIMITS.maxUniforms);
  assert.equal(limits.maxLoopIterations, SNIPPET_LIMITS.maxLoopIterations);
  assert.equal(limits.maxLoopWork, SNIPPET_LIMITS.maxLoopWork);
  assert.ok(AGENT_SCENE_CAPABILITIES.operations.includes('set-post-passes'));
});

test('passes: count, names, fields, scale and the entry function', () => {
  const pass = (overrides = {}) => ({ name: 'one', fragment: ENTRY, ...overrides });
  assert.equal(normalizeUserPasses([pass()])[0].scale, 1);
  assert.throws(() => normalizeUserPasses(Array.from({ length: 5 }, (_, index) => pass({ name: `p${index}` }))), /limit is 4/);
  assert.throws(() => normalizeUserPasses([pass(), pass()]), /used twice/);
  assert.throws(() => normalizeUserPasses([pass({ name: 'Bad Name' })]), /name must match/);
  assert.throws(() => normalizeUserPasses([pass({ scale: 0 })]), /scale must be between/);
  assert.throws(() => normalizeUserPasses([pass({ scale: 2 })]), /scale must be between/);
  assert.throws(() => normalizeUserPasses([pass({ shader: 'x' })]), /Unknown postPasses\[0\] field: shader/);
  assert.throws(() => normalizeUserPasses([pass({ fragment: 'float x = 1.0;' })]), /Define vec4 userPass/);
  assert.throws(() => normalizeUserPasses('x'), /must be an array/);
  assert.deepEqual(describeUserPasses(normalizeUserPasses([pass({ uniforms: { amount: 1 } })])), [{ name: 'one', scale: 1, uniforms: ['amount:float'], fragmentBytes: ENTRY.length }]);
});

test('the documented example passes the validator and builds a scene', async () => {
  // A Windows checkout may turn the doc's line endings into CRLF.
  const documentation = readFileSync(new URL('../docs/user-passes.md', import.meta.url), 'utf8').replaceAll('\r\n', '\n');
  const recipeText = documentation.match(/```json\n(\{"postPasses".*)\n```/)[1];
  const { postPasses } = JSON.parse(recipeText);
  const [pass] = normalizeUserPasses(postPasses);
  assert.equal(pass.scale, 0.25);
  const glsl = documentation.match(/```glsl\n([\s\S]*?)\n```/)[1];
  assert.equal(glsl, postPasses[0].fragment);
  const recipe = { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [], postPasses };
  await loadAgentSceneModules(recipe);
  const scene = createAgentScene(recipe);
  assert.equal(scene.postPasses[0].name, 'pixel-dither');
  assert.equal(scene.inspect().postPasses[0].uniforms.join(), 'levels:float,spread:float');
  scene.apply([{ type: 'set-post-passes', postPasses: null }], { expectedRevision: scene.revision });
  assert.deepEqual(scene.postPasses, []);
  assert.equal(scene.inspect().postPasses, undefined);
  scene.apply([{ type: 'set-post-passes', postPasses }], { expectedRevision: scene.revision });
  assert.equal(scene.postPasses.length, 1);
  assert.throws(() => scene.apply([{ type: 'set-post-passes', postPasses: [{ ...postPasses[0], fragment: '#define A 1\n' + postPasses[0].fragment }] }], { expectedRevision: scene.revision }), /Preprocessor lines/);
  assert.equal(scene.postPasses.length, 1);
  assert.throws(() => scene.apply([{ type: 'set-post-passes' }], { expectedRevision: scene.revision }), /postPasses: got undefined; expected a postPasses value, or null to clear it/);
  assert.deepEqual(scene.exportRecipe().postPasses, scene.postPasses);
});