Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

refactor(engine-qa): extract thresholds and verdict math into an isomorphic core module

nirholas0d434d038c6d
diff --git a/api/_lib/engine-qa-core.js b/api/_lib/engine-qa-core.js
new file mode 100644
index 000000000..b85fe03c7
--- /dev/null
+++ b/api/_lib/engine-qa-core.js
@@ -0,0 +1,81 @@
+// Isomorphic core of the engine-qa grade: the thresholds and pure math that
+// both the server grader (api/_lib/engine-qa.js, full report: draw calls,
+// materials, texel density, triangle budget, collider) and the browser-only
+// partial grader (src/engine-qa-client.js, used by Rig Doctor so a file never
+// has to leave the tab for the cheap checks) must agree on. Zero imports: no
+// Node builtin, no gltf-transform, nothing a bundler has to special-case for
+// the browser.
+//
+// Every number a report cites traces back to ENGINE_QA_THRESHOLDS, never a
+// literal buried in a check, so the server and the browser can never grade
+// the same mesh to two different verdicts.
+
+export const ENGINE_QA_VERSION = 'threews.engine.qa.v1';
+
+export const ENGINE_QA_THRESHOLDS = Object.freeze({
+ // One real-time frame budget on mid-tier mobile hardware. Above `warn`,
+ // batching/atlasing stops being optional.
+ drawCalls: Object.freeze({ good: 20, warn: 60 }),
+ // Distinct materials: each one is a potential draw-call split and a texture
+ // set a mobile GPU has to keep resident.
+ materialCount: Object.freeze({ good: 8, warn: 20 }),
+ // Triangle ceiling per LOD level. A level whose own `name` isn't one of
+ // these keys falls back to LOD0's ceiling (the most permissive) rather
+ // than failing on an unrecognized label.
+ triangleBudget: Object.freeze({ LOD0: 100_000, LOD1: 40_000, LOD2: 12_000 }),
+ // Game-ready texel density window (texels per meter of surface). Below the
+ // floor, textures visibly smear up close; above the ceiling, the asset is
+ // paying for resolution the eye can't resolve at normal viewing distance.
+ texelDensity: Object.freeze({ minPxPerMeter: 128, maxPxPerMeter: 2048 }),
+ // A mesh collider heavier than this belongs on a convex-hull or primitive
+ // proxy instead: not because physics engines refuse it, but because the
+ // broad-phase cost stops being worth the precision.
+ colliderTriangleBudget: 5_000,
+});
+
+export function worstVerdict(verdicts) {
+ const real = verdicts.filter((v) => v !== 'skip');
+ if (real.includes('fail')) return 'fail';
+ if (real.includes('warn')) return 'warn';
+ if (real.length === 0) return 'skip';
+ return 'pass';
+}
+
+export function verdictFromBand(value, { good, warn }) {
+ if (value <= good) return 'pass';
+ if (value <= warn) return 'warn';
+ return 'fail';
+}
+
+/**
+ * Grade each LOD level's triangle count against ENGINE_QA_THRESHOLDS.triangleBudget
+ * and confirm the chain is monotonically decreasing (highest to lowest detail).
+ *
+ * @param {Array<{ name: string, triangleCount: number }>|null} lods
+ */
+export function gradeTriangleBudget(lods) {
+ if (!Array.isArray(lods) || lods.length === 0) {
+ return { value: null, verdict: 'skip', reason: 'no LOD chain supplied' };
+ }
+
+ const perLevel = lods.map((level) => {
+ const budget = ENGINE_QA_THRESHOLDS.triangleBudget[level.name] ?? ENGINE_QA_THRESHOLDS.triangleBudget.LOD0;
+ return {
+ name: level.name,
+ triangleCount: level.triangleCount,
+ budget,
+ verdict: level.triangleCount <= budget ? 'pass' : 'fail',
+ };
+ });
+
+ let monotonicDecrease = true;
+ for (let i = 1; i < lods.length; i++) {
+ if (lods[i].triangleCount > lods[i - 1].triangleCount) monotonicDecrease = false;
+ }
+
+ return {
+ value: perLevel,
+ monotonicDecrease,
+ verdict: worstVerdict([...perLevel.map((l) => l.verdict), monotonicDecrease ? 'pass' : 'fail']),
+ };
+}
diff --git a/api/_lib/engine-qa.js b/api/_lib/engine-qa.js
index ef9990d1a..7b8008913 100644
--- a/api/_lib/engine-qa.js
+++ b/api/_lib/engine-qa.js
@@ -31,33 +31,17 @@ import { NodeIO } from '@gltf-transform/core';
import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
import { loadMesh } from './print/mesh-io.js';
import { analyzeMesh } from './print/analyze.js';
+import {
+ ENGINE_QA_VERSION,
+ ENGINE_QA_THRESHOLDS,
+ worstVerdict,
+ verdictFromBand,
+ gradeTriangleBudget,
+} from './engine-qa-core.js';
-const MODE_TRIANGLES = 4;
-
-export const ENGINE_QA_VERSION = 'threews.engine.qa.v1';
+export { ENGINE_QA_VERSION, ENGINE_QA_THRESHOLDS };
-// Pass/fail thresholds in one place, per the work order: every number a
-// report cites traces back to this object, never a literal buried in a check.
-export const ENGINE_QA_THRESHOLDS = Object.freeze({
- // One real-time frame budget on mid-tier mobile hardware. Above `warn`,
- // batching/atlasing stops being optional.
- drawCalls: Object.freeze({ good: 20, warn: 60 }),
- // Distinct materials: each one is a potential draw-call split and a texture
- // set a mobile GPU has to keep resident.
- materialCount: Object.freeze({ good: 8, warn: 20 }),
- // Triangle ceiling per LOD level. A level whose own `name` isn't one of
- // these keys falls back to LOD0's ceiling (the most permissive) rather
- // than failing on an unrecognized label.
- triangleBudget: Object.freeze({ LOD0: 100_000, LOD1: 40_000, LOD2: 12_000 }),
- // Game-ready texel density window (texels per meter of surface). Below the
- // floor, textures visibly smear up close; above the ceiling, the asset is
- // paying for resolution the eye can't resolve at normal viewing distance.
- texelDensity: Object.freeze({ minPxPerMeter: 128, maxPxPerMeter: 2048 }),
- // A mesh collider heavier than this belongs on a convex-hull or primitive
- // proxy instead: not because physics engines refuse it, but because the
- // broad-phase cost stops being worth the precision.
- colliderTriangleBudget: 5_000,
-});
+const MODE_TRIANGLES = 4;
let ioPromise = null;
@@ -191,53 +175,6 @@ function firstTexture(material) {
);
}
-function worstVerdict(verdicts) {
- const real = verdicts.filter((v) => v !== 'skip');
- if (real.includes('fail')) return 'fail';
- if (real.includes('warn')) return 'warn';
- if (real.length === 0) return 'skip';
- return 'pass';
-}
-
-function verdictFromBand(value, { good, warn }) {
- if (value <= good) return 'pass';
- if (value <= warn) return 'warn';
- return 'fail';
-}
-
-/**
- * Grade each LOD level's triangle count against ENGINE_QA_THRESHOLDS.triangleBudget
- * and confirm the chain is monotonically decreasing (highest to lowest detail).
- *
- * @param {Array<{ name: string, triangleCount: number }>|null} lods
- */
-function gradeTriangleBudget(lods) {
- if (!Array.isArray(lods) || lods.length === 0) {
- return { value: null, verdict: 'skip', reason: 'no LOD chain supplied' };
- }
-
- const perLevel = lods.map((level) => {
- const budget = ENGINE_QA_THRESHOLDS.triangleBudget[level.name] ?? ENGINE_QA_THRESHOLDS.triangleBudget.LOD0;
- return {
- name: level.name,
- triangleCount: level.triangleCount,
- budget,
- verdict: level.triangleCount <= budget ? 'pass' : 'fail',
- };
- });
-
- let monotonicDecrease = true;
- for (let i = 1; i < lods.length; i++) {
- if (lods[i].triangleCount > lods[i - 1].triangleCount) monotonicDecrease = false;
- }
-
- return {
- value: perLevel,
- monotonicDecrease,
- verdict: worstVerdict([...perLevel.map((l) => l.verdict), monotonicDecrease ? 'pass' : 'fail']),
- };
-}
-
/**
* Reuse the print pipeline's manifold/watertight check: a closed mesh under
* the collider triangle budget is cheap to collide against as-is; anything
diff --git a/tests/engine-qa-core.test.js b/tests/engine-qa-core.test.js
new file mode 100644
index 000000000..0c77cb3ec
--- /dev/null
+++ b/tests/engine-qa-core.test.js
@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest';
+import { worstVerdict, verdictFromBand, gradeTriangleBudget, ENGINE_QA_THRESHOLDS, ENGINE_QA_VERSION } from '../api/_lib/engine-qa-core.js';
+
+describe('engine-qa-core: the isomorphic thresholds and pure math shared by the server grader and the browser-only client grader', () => {
+ it('exposes a stable version string and frozen thresholds', () => {
+ expect(ENGINE_QA_VERSION).toBe('threews.engine.qa.v1');
+ expect(Object.isFrozen(ENGINE_QA_THRESHOLDS)).toBe(true);
+ expect(Object.isFrozen(ENGINE_QA_THRESHOLDS.drawCalls)).toBe(true);
+ expect(ENGINE_QA_THRESHOLDS.drawCalls.good).toBe(20);
+ });
+
+ it('worstVerdict ignores skip and escalates fail over warn over pass', () => {
+ expect(worstVerdict(['skip', 'skip'])).toBe('skip');
+ expect(worstVerdict(['pass', 'skip'])).toBe('pass');
+ expect(worstVerdict(['pass', 'warn'])).toBe('warn');
+ expect(worstVerdict(['pass', 'warn', 'fail'])).toBe('fail');
+ });
+
+ it('verdictFromBand bands a value against good/warn ceilings', () => {
+ const band = { good: 10, warn: 20 };
+ expect(verdictFromBand(5, band)).toBe('pass');
+ expect(verdictFromBand(15, band)).toBe('warn');
+ expect(verdictFromBand(25, band)).toBe('fail');
+ });
+
+ it('gradeTriangleBudget skips a missing chain and grades a real one against the shared budget', () => {
+ expect(gradeTriangleBudget(null).verdict).toBe('skip');
+ expect(gradeTriangleBudget([]).verdict).toBe('skip');
+
+ const report = gradeTriangleBudget([
+ { name: 'LOD0', triangleCount: 50_000 },
+ { name: 'LOD1', triangleCount: 45_000 },
+ ]);
+ expect(report.value[1].budget).toBe(ENGINE_QA_THRESHOLDS.triangleBudget.LOD1);
+ expect(report.value[1].verdict).toBe('fail');
+ expect(report.verdict).toBe('fail');
+ });
+});