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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsnew file mode 100644index 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.jsindex 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; anythingdiff --git a/tests/engine-qa-core.test.js b/tests/engine-qa-core.test.jsnew file mode 100644index 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');+ });+});