Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

14.3 KB
Raw Blame
/**
 * Instanceability metrics + grader (Phase 0/1).
 *
 * Covers: post-dedup metric extraction from a baked Document, the empirical
 * dedup-merges-value-identical-materials question, the grade rubric (advisory),
 * and that render.meta carries the report.
 */

import { describe, it, expect } from 'bun:test';
import {
  createRoot,
  createPart,
  createInstance,
  cylinderGeo,
  boxGeo,
  gameMaterial,
  glassMaterial,
} from '../primitives';
import { renderSceneToGLB, renderGLB, gradeGlbBytes } from '../render';
import {
  collectGlbMetrics,
  gradeInstanceability,
  materialMergeCandidates,
  type InstanceabilityMetrics,
} from '../metrics';
import { Document } from '@gltf-transform/core';
import { EXTMeshGPUInstancing } from '@gltf-transform/extensions';
import * as THREE from 'three';
import { countTriangles } from '../primitives';

const baseMetrics = (over: Partial<InstanceabilityMetrics> = {}): InstanceabilityMetrics => ({
  uniqueGeometries: 1,
  uniqueMaterials: 1,
  meshNodes: 1,
  meshInstances: 1,
  drawCalls: 1,
  textureCount: 0,
  skinned: false,
  transparentMaterials: 0,
  triangles: 100,
  ...over,
});

describe('collectGlbMetrics (post-dedup)', () => {
  it('distinguishes mesh nodes, instance copies, materials and estimated primitive draws', () => {
    const doc = new Document();
    const position = doc
      .createAccessor()
      .setType('VEC3')
      .setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]));
    const material = doc.createMaterial();
    const triangle = doc.createPrimitive().setAttribute('POSITION', position).setMaterial(material);
    const mesh = doc.createMesh().addPrimitive(triangle);
    const ordinary = doc.createNode().setMesh(mesh);
    const copies = doc.createAccessor().setType('VEC3').setArray(new Float32Array(9));
    const instances = doc
      .createExtension(EXTMeshGPUInstancing)
      .createInstancedMesh()
      .setAttribute('TRANSLATION', copies);
    const instanced = doc
      .createNode()
      .setMesh(mesh)
      .setExtension('EXT_mesh_gpu_instancing', instances);
    const points = doc
      .createNode()
      .setMesh(
        doc
          .createMesh()
          .addPrimitive(
            doc
              .createPrimitive()
              .setMode(0)
              .setAttribute('POSITION', position)
              .setMaterial(material),
          ),
      );
    doc.createScene().addChild(ordinary).addChild(instanced).addChild(points);
    expect(collectGlbMetrics(doc)).toMatchObject({
      meshNodes: 3,
      meshInstances: 5,
      drawCalls: 3,
      uniqueMaterials: 1,
      uniqueGeometries: 2,
      triangles: 4,
    });
  });

  it('source triangle counts include active InstancedMesh copies and zero-count batches', () => {
    const root = new THREE.Group();
    const mesh = new THREE.InstancedMesh(
      new THREE.BoxGeometry(),
      new THREE.MeshStandardMaterial(),
      5,
    );
    root.add(mesh);
    mesh.count = 3;
    expect(countTriangles(root)).toBe(36);
    mesh.count = 0;
    expect(countTriangles(root)).toBe(0);
  });
  it('an instanced 4-wheel scene reports 1 geometry, 1 material, 4 draw calls', async () => {
    const r = createRoot('Truck');
    const wg = cylinderGeo(0.4, 0.4, 0.2, 16);
    const rubber = gameMaterial(0x1a1a1a);
    const fl = createPart('WheelFL', wg, rubber, { position: [-0.8, 0.3, 1.2], parent: r });
    createInstance('WheelFR', fl, { position: [0.8, 0.3, 1.2], parent: r });
    createInstance('WheelRL', fl, { position: [-0.8, 0.3, -1.2], parent: r });
    createInstance('WheelRR', fl, { position: [0.8, 0.3, -1.2], parent: r });

    const scene = await renderSceneToGLB(r);
    const m = scene.instanceability?.metrics;
    expect(m).toBeDefined();
    expect(m!.uniqueGeometries).toBe(1);
    expect(m!.uniqueMaterials).toBe(1);
    expect(m!.drawCalls).toBe(4);
    expect(scene.instanceability!.grade).toBe('A');
  });

  it('records whether dedup() merges value-identical-but-independent materials', async () => {
    // Two distinct THREE materials with identical values (separate gameMaterial
    // calls) on two distinct geometries. This empirically answers the watch-item.
    const r = createRoot('Pair');
    createPart('A', boxGeo(1, 1, 1), gameMaterial(0x808080), { position: [0, 0, 0], parent: r });
    createPart('B', boxGeo(1, 1, 1), gameMaterial(0x808080), { position: [2, 0, 0], parent: r });

    const scene = await renderSceneToGLB(r);
    const mats = scene.instanceability!.metrics.uniqueMaterials;
    // dedup() compares materials structurally, so value-identical materials
    // collapse to 1. If this ever regresses to 2, Phase-2-bake material
    // unification (palette()) becomes worth wiring.
    expect(mats).toBe(1);
  });

  it('distinct-color materials are NOT merged', async () => {
    const r = createRoot('TwoColor');
    createPart('A', boxGeo(1, 1, 1), gameMaterial(0xff0000), { position: [0, 0, 0], parent: r });
    createPart('B', boxGeo(1, 1, 1), gameMaterial(0x00ff00), { position: [2, 0, 0], parent: r });
    const scene = await renderSceneToGLB(r);
    expect(scene.instanceability!.metrics.uniqueMaterials).toBe(2);
    expect(scene.instanceability!.grade).toBe('B');
  });

  it('a blended (glass) material marks transparentMaterials', async () => {
    const r = createRoot('Glassy');
    createPart('Pane', boxGeo(1, 1, 0.05), glassMaterial(0x88ccff, { opacity: 0.4 }), {
      position: [0, 0, 0],
      parent: r,
    });
    const scene = await renderSceneToGLB(r);
    expect(scene.instanceability!.metrics.transparentMaterials).toBeGreaterThanOrEqual(1);
  });
});

describe('gradeInstanceability (advisory rubric)', () => {
  it('1 material -> A', () => {
    expect(gradeInstanceability(baseMetrics()).grade).toBe('A');
  });
  it('2-3 materials -> B', () => {
    expect(gradeInstanceability(baseMetrics({ uniqueMaterials: 3 })).grade).toBe('B');
  });
  it('many materials -> F', () => {
    expect(gradeInstanceability(baseMetrics({ uniqueMaterials: 20 })).grade).toBe('F');
  });
  it('transparency caps an otherwise-A asset at C', () => {
    const r = gradeInstanceability(baseMetrics({ transparentMaterials: 1 }));
    expect(r.grade).toBe('C');
    expect(r.reasons.join(' ')).toMatch(/transparent/i);
  });
  it('skinned is NOT an automatic F and is noted', () => {
    const r = gradeInstanceability(baseMetrics({ skinned: true, uniqueMaterials: 1 }));
    expect(r.grade).toBe('A');
    expect(r.summary).toMatch(/skinned/);
    expect(r.reasons.join(' ')).toMatch(/clone-rendered/i);
  });
  it('texture sprawl demotes toward C', () => {
    const r = gradeInstanceability(baseMetrics({ uniqueMaterials: 1, textureCount: 6 }));
    expect(['C', 'D', 'F']).toContain(r.grade);
  });
  it('the summary is informational and names what set the grade', () => {
    // Nine materials set D; the glass does not, so it must not read as the cause.
    const r = gradeInstanceability(
      baseMetrics({
        uniqueMaterials: 9,
        transparentMaterials: 1,
        uniqueGeometries: 20,
        drawCalls: 30,
      }),
    );
    expect(r.grade).toBe('D');
    expect(r.summary).toBe(
      'D (informational, not a QA verdict), set by 9 distinct materials (D at 7-12). Also: 1 transparent material (lowers only A/B to C); 20 geometries; 30 draw calls.',
    );
    expect(r.reasons[0]).toBe('grade D set by 9 distinct materials (D at 7-12)');
  });
  it('a grade lowered by transparency or textures names that driver', () => {
    expect(gradeInstanceability(baseMetrics({ transparentMaterials: 1 })).summary).toBe(
      'C (informational, not a QA verdict), set by 1 transparent material (lowers A/B to C). Also: 1 distinct material (A at 0-1); 1 geometry; 1 draw call.',
    );
    const both = gradeInstanceability(
      baseMetrics({ uniqueMaterials: 2, transparentMaterials: 2, textureCount: 6, skinned: true }),
    );
    expect(both.summary).toBe(
      'C (informational, not a QA verdict), set by 2 transparent materials (lowers A/B to C) and 6 textures (over 4 lowers A/B to C). Also: 2 distinct materials (B at 2-3); 1 geometry; 1 draw call; skinned (clone-rendered, not penalized).',
    );
    expect(both.reasons[0]).toBe(
      'grade C set by 2 transparent materials (lowers A/B to C) and 6 textures (over 4 lowers A/B to C)',
    );
    expect(gradeInstanceability(baseMetrics({ uniqueMaterials: 5, textureCount: 6 })).summary).toBe(
      'C (informational, not a QA verdict), set by 5 distinct materials (C at 4-6). Also: 6 textures (over 4 lowers only A/B to C); 1 geometry; 1 draw call.',
    );
    expect(gradeInstanceability(baseMetrics({ uniqueMaterials: 13 })).summary).toStartWith(
      'F (informational, not a QA verdict), set by 13 distinct materials (F at 13+).',
    );
  });
});

describe('material merge advice (optional)', () => {
  /** One triangle per material, each on its own named node. */
  function shadingDoc() {
    const doc = new Document();
    const position = doc
      .createAccessor()
      .setType('VEC3')
      .setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]));
    const scene = doc.createScene();
    const place = (name: string, material: ReturnType<Document['createMaterial']>) =>
      scene.addChild(
        doc
          .createNode(name)
          .setMesh(
            doc
              .createMesh(name)
              .addPrimitive(
                doc.createPrimitive().setAttribute('POSITION', position).setMaterial(material),
              ),
          ),
      );
    const red = [0.8, 0.1, 0.1, 1] as [number, number, number, number];
    place('Frond_0', doc.createMaterial('FrondA').setBaseColorFactor(red));
    place('Frond_1', doc.createMaterial('FrondB').setBaseColorFactor([0.1, 0.6, 0.1, 1]));
    place('Leaf', doc.createMaterial('Cutout').setBaseColorFactor(red).setAlphaMode('MASK'));
    place(
      'Bark',
      doc.createMaterial('Bark').setBaseColorFactor(red).setBaseColorTexture(doc.createTexture()),
    );
    return doc;
  }

  it('groups factor-only differences and projects the material band without changing the grade', () => {
    const doc = shadingDoc();
    const candidates = materialMergeCandidates(doc);
    expect(candidates).toEqual([
      {
        materials: ['FrondA', 'FrondB'],
        parts: [['Frond_0'], ['Frond_1']],
        alphaMode: 'OPAQUE',
        differs: ['baseColorFactor'],
        needs: 'colours in a shared texture, an atlas region or vertex colours',
      },
    ]);
    const metrics = collectGlbMetrics(doc);
    const plain = gradeInstanceability(metrics);
    const advised = gradeInstanceability(metrics, { mergeCandidates: candidates });
    expect(advised.grade).toBe(plain.grade);
    expect(advised.grade).toBe('C');
    expect(advised.reasons[0]).toBe(plain.reasons[0]);
    expect(advised.advice).toEqual({
      optional: true,
      materialMerges: candidates,
      projectedMaterials: 3,
      projectedGrade: 'B',
    });
    expect(advised.summary).toStartWith(plain.summary);
    expect(advised.summary).toEndWith(
      ' Optional advice, not a requirement: merging FrondA + FrondB (differ in baseColorFactor) would leave 3 materials (B at 2-3).',
    );
    expect(advised.reasons).toContain(
      'optional advice: FrondA + FrondB share shading and differ in baseColorFactor; a merge needs colours in a shared texture, an atlas region or vertex colours; parts: Frond_0, Frond_1',
    );
  });

  it('keeps alpha mode, texture bindings and extras apart and is silent without candidates', () => {
    const doc = shadingDoc();
    doc
      .getRoot()
      .listMaterials()
      .find((m) => m.getName() === 'FrondB')!
      .setExtras({ role: 'trim' });
    expect(materialMergeCandidates(doc)).toEqual([]);
    const report = gradeInstanceability(collectGlbMetrics(doc), { mergeCandidates: [] });
    expect(report.advice).toBeUndefined();
    expect(report.summary).not.toContain('Optional advice');
  });

  it('dedup keeps byte-identical materials merged, so they produce no candidate', async () => {
    const root = createRoot('Palm');
    for (let i = 0; i < 3; i++)
      createPart(`Frond_${i}`, boxGeo(1, 0.1, 0.3), gameMaterial(0x2f7a2f), {
        parent: root,
        position: [i, 0, 0],
      });
    const same = await renderSceneToGLB(root, { optimize: 'off' });
    expect(same.instanceability!.metrics.uniqueMaterials).toBe(1);
    expect(same.instanceability!.advice).toBeUndefined();

    createPart('Frond_3', boxGeo(1, 0.1, 0.3), gameMaterial(0x3f8a2f), { parent: root });
    const varied = await renderSceneToGLB(root, { optimize: 'off' });
    expect(varied.instanceability!.grade).toBe('B');
    expect(varied.instanceability!.advice).toMatchObject({
      projectedMaterials: 1,
      projectedGrade: 'A',
    });
    expect(varied.instanceability!.advice!.materialMerges[0]!.materials).toEqual([
      'Mesh_Frond_0 material',
      'Mesh_Frond_3 material',
    ]);
    expect(varied.instanceability!.summary).toContain('Optional advice, not a requirement');
  });
});

describe('render.meta carries the instanceability report', () => {
  it('renderGLB merges instanceability into meta', async () => {
    const code = `
      const meta = { name: 'Box', category: 'prop' };
      function build() {
        const root = createRoot('Box');
        createPart('B', boxGeo(1, 1, 1), gameMaterial(0xff0000), { parent: root });
        return root;
      }
    `;
    const res = await renderGLB(code);
    expect(res.meta.instanceability).toBeDefined();
    expect(res.meta.instanceability!.grade).toBe('A');
    // tier is auto-filled to mirror the grade (M1d).
    expect(res.meta.tier).toBe('A');
    expect(res.meta.metricsError).toBeUndefined();
  });
});

describe('gradeGlbBytes (web-side path)', () => {
  it('grades a finished GLB from its bytes and derives triangles', async () => {
    const r = createRoot('Truck');
    const wg = cylinderGeo(0.4, 0.4, 0.2, 16);
    const rubber = gameMaterial(0x1a1a1a);
    const fl = createPart('WheelFL', wg, rubber, { position: [-0.8, 0.3, 1.2], parent: r });
    createInstance('WheelFR', fl, { position: [0.8, 0.3, 1.2], parent: r });
    const scene = await renderSceneToGLB(r);

    const report = await gradeGlbBytes(scene.bytes, { category: 'vehicle' });
    expect(report).toBeDefined();
    expect(report!.grade).toBe('A');
    expect(report!.metrics.triangles).toBeGreaterThan(0);
    expect(report!.metrics.drawCalls).toBe(2);
  });

  it('returns undefined on unparseable bytes', async () => {
    expect(await gradeGlbBytes(new Uint8Array([1, 2, 3, 4]))).toBeUndefined();
  });
});