You can now generate creatures directly within your project. Drop the open-source into your Agent, and start prompting what you want.
JavaScript
// Generic creature mechanical judge (engine layer, L1) — pure numeric measurement, zero LLM, zero browser.
// The engine contains no creature-specific vocabulary; all identity claims live in the spec JSON.
//
// usage: node judge.mjs <model.glb> <outDir> <name> [--spec creature.json] [--stage LOW|MID|HIGH]
// no --spec = measure only, emit metrics JSON (for humans or for scoring)
// with --spec = check every claim in the spec; any failure exits 1 (symptom-first messages)
//
// WHERE THE NUMBERS COME FROM. This used to launch a headless Chromium, load the
// model into three.js, render five views, and read the pixels back. Every number
// it wanted was already in the file: part shares are a z-buffer, the baked colour
// IS the albedo, and the clip list and skin count are in the glTF header. So the
// measuring moved to harness/outline.py — the tool that already owns every other
// geometry measure in this harness — and this file does what is left: check the
// claims. One measure, one definition, in one place.
//
// Two conventions changed with the move, both toward the tool that survived:
// · `side` is the LONG profile (outline.py picks the axis), not a fixed +X.
// Judge's old fixed camera showed a spread-winged creature edge-on and
// called it a side view.
// · `tq` and `reartq` are gone; the three-quarter view is `hero`. The two
// cameras sit within a few degrees of each other and the shares agree to
// ~1 percentage point, so a band calibrated on `tq` still means what it meant.
//
// spec JSON = { "name": "...", "claims": [ {type, ...params, "label": "plain-language description"} ] }
// Supported claim types (add a new one in CHECKS; keep the engine creature-agnostic):
// part_exists {part} — a material/part with this name must exist
// part_visible {part, view?, min_share} — minimum share of body pixels the part holds in a given view
// part_signature {part, view?, min_share, or_min_span} — signature part: share OR span ratio must clear its bar
// style_dark {view?, max_median_lum} — dark styling: the creature's OWN colour must not be brighter
// style_light {view?, min_median_lum} — light styling: must not fall below the floor
// rig_skinned {} — must be skinned (bones move nothing without skin weights)
// anim_named {names:[...]} — these named animations must be present
// tri_budget {min, max} — triangle budget band
// share_hierarchy {primary:[..],secondary:[..],tertiary:[..],view?,tolerance?} — primary/secondary/tertiary shares ≈6:3:1
// focal_contrast {a, b, view?, min_ratio?} — the two focal parts' shares must differ by ≥N× (default 2)
// saturation_area {view?, min?, max?} — share of the view carrying a highly saturated colour
// (HSV S ≥ 0.50 on the UNLIT baked colour). Default floor 0.10.
import path from 'path'; import fs from 'fs';
import { spawnSync } from 'child_process';
import { fileURLToPath } from 'url';
const args = process.argv.slice(2);
const si = args.indexOf('--spec');
const specFile = si >= 0 ? args.splice(si, 2)[1] : null;
const sti = args.indexOf('--stage');
const stageFilter = sti >= 0 ? args.splice(sti, 2)[1].toUpperCase() : null; // LOW/MID/HIGH; none = check all
const [src, outDir, name] = args;
if (!src || !outDir || !name) { console.error('usage: node judge.mjs <model> <outDir> <name> [--spec spec.json]'); process.exit(2); }
const root = path.dirname(fileURLToPath(import.meta.url));
const abs = path.resolve(src);
fs.mkdirSync(outDir, { recursive: true });
// ── measure: one call to the one measuring tool ──
const outline = path.join(root, 'outline.py');
const run = spawnSync('python3', [outline, abs, outDir], { encoding: 'utf8' });
if (run.status !== 0) {
console.error('[judge] outline.py failed — it owns every measurement here, so nothing can be judged:\n'
+ (run.stderr || run.stdout || '').trim());
process.exit(2);
}
const M = JSON.parse(fs.readFileSync(path.join(outDir, 'metrics.json'), 'utf8'));
// `tq`/`reartq` were judge's own camera names; the surviving three-quarter view is `hero`.
const VIEW = v => (v === 'tq' || v === 'reartq') ? 'hero' : v;
const view = v => M.views[VIEW(v)] || {};
const names = M.materials || [];
const parts = M.parts || {};
const share = (v, mat) => (view(v).share || {})[mat] ?? 0;
const stats = M.stats || { triangles: M.triangles, skinnedMeshes: 0, animations: [] };
const m = { name, stats, names,
lum: Object.fromEntries(Object.entries(M.views).map(([vn, d]) => [vn, d.median_lum])),
hi_sat_share: Object.fromEntries(Object.entries(M.views).map(([vn, d]) => [vn, d.saturated_area])),
parts, whole: M.whole };
const metricsPath = path.join(outDir, `${name}_metrics.json`);
fs.writeFileSync(metricsPath, JSON.stringify(m, null, 1));
// A SUMMARY, not the blob. Tool output lands in the conversation permanently and
// the conversation is re-read on every turn afterwards, so a 2KB dump at round 3
// is still being paid for at round 30. `--json` restores the full object.
if (process.argv.includes('--json')) console.log(JSON.stringify(m));
else {
const v = 'hero';
console.log(`[judge] ${name}: ${stats.triangles} tris · ${names.length} materials · `
+ `clips ${stats.animations.join('/') || 'none'} · skinned ${stats.skinnedMeshes}`);
console.log(` ${v} view: luminance ${m.lum[v]} · saturated area `
+ `${((m.hi_sat_share[v] || 0) * 100).toFixed(1)}%`);
const top = Object.entries(parts).sort((a, b) => (share(v, b[0])) - (share(v, a[0]))).slice(0, 3);
console.log(' biggest in view: ' + top.map(([n]) => `${n} ${(share(v, n) * 100).toFixed(0)}%`).join(' · '));
console.log(` full numbers: ${metricsPath}`);
}
// ── Spec mode: check every claim, symptom first ──
if (specFile) {
const S = JSON.parse(fs.readFileSync(specFile, 'utf8'));
const bad = [];
const pct = x => (x * 100).toFixed(2) + '%';
const CHECKS = {
part_exists(c){ if(!names.includes(c.part))
bad.push(`Part "${c.part}" not measurable: no material by that name in the model (part missing, or naming convention not followed)`); },
part_visible(c){ if(!names.includes(c.part)) return CHECKS.part_exists(c);
const v=c.view||'side'; const s=share(v,c.part);
if(s<c.min_share) bad.push(`Part "${c.part}" is nearly invisible in the ${v} view (share ${pct(s)} < ${pct(c.min_share)}) — occluded, too small, or in the wrong place`); },
part_signature(c){ if(!names.includes(c.part)) return CHECKS.part_exists(c);
const v=c.view||'side'; const s=share(v,c.part); const sp=(parts[c.part]||{}).span_ratio ?? 0;
if(!(s>=c.min_share||sp>=c.or_min_span))
bad.push(`Signature part "${c.part}" is not exaggerated enough: ${v}-view share ${pct(s)} (need ≥${pct(c.min_share)}) and span ratio ${sp} (need ≥${c.or_min_span}) — right now it is just another part; it cannot carry this creature's identity`); },
// Dark/light now read the creature's OWN colour, not a studio render of it.
// The old number was the median luminance of a lit beauty pass, which made
// the verdict a property of a lighting rig nobody ships. This is the unlit
// baked albedo: what the designer actually chose. The two correlate at
// r≈0.96 but are not the same scale — the albedo runs darker — so a
// threshold carried over from a pre-1.3.2 spec needs re-picking once.
style_dark(c){ const v=c.view||'side'; const L=view(v).median_lum;
if(L>c.max_median_lum) bad.push(`Declared dark but its own colour is not dark: ${v}-view median albedo luminance ${L.toFixed(0)}/255 (need ≤${c.max_median_lum}) — push the material colour values darker`); },
style_light(c){ const v=c.view||'side'; const L=view(v).median_lum;
if(L<c.min_median_lum) bad.push(`Declared light but its own colour is too dark: ${v}-view median albedo luminance ${L.toFixed(0)}/255 (need ≥${c.min_median_lum})`); },
// High-saturation AREA, computed from the unlit baked colour (HSV S ≥ 0.50).
// Too little and the creature is a grey lump; too much and saturation stops
// being a spotlight and the whole thing screams. Do NOT name which surfaces
// carry it — where the colour goes is the designer's call, only how much.
saturation_area(c){ const v=c.view||'tq';
const s=view(v).saturated_area; if(s==null) return;
// There is NO default ceiling. Dropping `max` from claims.json did not
// remove the old 0.34 one, because it lived here as a fallback — so the
// ceiling went on refusing creatures after it had supposedly been
// retired. A ceiling only applies now if a spec asks for one by name. The
// floor keeps its default: "reads as a grey lump" is a real failure and
// nobody has to opt into catching it.
const p=s*100, lo=(c.min??0.10)*100;
if(p<lo) bad.push(`Too little colour: only ${p.toFixed(1)}% of the ${VIEW(v)} view is highly saturated (need ≥${lo.toFixed(0)}%) — the creature reads as a grey mass. Raise the saturation of a mass that deserves the attention, do not tint everything.`);
if(c.max!=null && p>c.max*100) bad.push(`Too much colour: ${p.toFixed(1)}% of the ${VIEW(v)} view is highly saturated (need ≤${(c.max*100).toFixed(0)}%) — saturation stops reading as a spotlight when it covers this much. Desaturate the supporting masses and keep the loud colour on the signature.`); },
rig_skinned(){ if(stats.skinnedMeshes<1)
bad.push('Model is not skinned: the rig is not bound to the mesh, so animating the bones moves nothing'); },
anim_named(c){ for(const a of c.names) if(!stats.animations.includes(a))
bad.push(`Missing named animation ${a} (present: ${stats.animations.join(',')||'none'})`); },
tri_budget(c){ const t=stats.triangles;
if(t<c.min||t>c.max) bad.push(`Triangle count ${t} is outside the budget band ${c.min}–${c.max}`); },
// 6:3:1 hierarchy: the primary / secondary / tertiary part groups must hold roughly
// 6:3:1 of the frame. An even spread reads as no hierarchy at all — a silhouette needs
// one mass that clearly leads, one that supports, and detail that stays detail.
share_hierarchy(c){ const v=c.view||'side';
const grp=g=>g.reduce((a,p)=>a+(names.includes(p)?share(v,p):0),0);
const [P,Sc,T]=[grp(c.primary||[]),grp(c.secondary||[]),grp(c.tertiary||[])];
const tot=P+Sc+T; if(!tot){ bad.push(`631 hierarchy not measurable: primary/secondary/tertiary parts are all 0 in the ${v} view`); return; }
const tol=c.tolerance??0.15, want=[0.6,0.3,0.1], got=[P/tot,Sc/tot,T/tot];
const off=got.map((g,i)=>Math.abs(g-want[i]));
if(Math.max(...off)>tol) bad.push(`Hierarchy ratio off: primary/secondary/tertiary = ${got.map(x=>(x*100).toFixed(0)).join(':')} (target 60:30:10, tolerance ±${tol*100}%) — no dominance; the frame is split evenly`); },
// No equal-weight focal points: two focal parts of the same size make the eye ping-pong
// between them and neither one wins. The declared pair's shares must differ by ≥ratio×.
focal_contrast(c){ const v=c.view||'side';
for(const p of [c.a,c.b]) if(!names.includes(p)) return CHECKS.part_exists({part:p});
const A=share(v,c.a), B=share(v,c.b); const hi=Math.max(A,B), lo=Math.min(A,B);
const ratio=c.min_ratio??2;
if(lo>0 && hi/lo<ratio) bad.push(`Two focal points of equal weight compete: "${c.a}" ${(A*100).toFixed(1)}% vs "${c.b}" ${(B*100).toFixed(1)}% (need ≥${ratio}× apart) — the eye ping-pongs between them; open up the dominance gap`); },
};
const claims=(S.claims||[]).filter(c=>!stageFilter || !c.stage || c.stage.toUpperCase()===stageFilter);
// enforce: "block" stops the build; "advise" measures and reports and never
// stops it. Taste is advice — a number that says the eye will ping-pong is
// worth reading and is not worth a rebuild. Correctness is a gate: a rig that
// does not deform or a clip that does not exist is broken, not debatable.
// Every claim carries the tag explicitly; see harness/gates.json for the map
// of the whole system, and for `when` (allocate up front vs verify after).
const advice=[];
for(const c of claims){
const fn=CHECKS[c.type];
if(!fn){ bad.push(`Spec contains a claim type the engine does not recognise: "${c.type}"`); continue; }
const before=bad.length; fn(c);
if(bad.length===before) continue;
const mine=bad.splice(before);
if(c.label) mine[mine.length-1] += ` [${c.label}]`;
if((c.enforce||'block')==='advise') advice.push(...mine); else bad.push(...mine);
}
if(advice.length){ console.log('\n'+'-'.repeat(68));
console.log('ADVICE — measured, not blocking. Your judgment, your call:');
for(const a of advice) console.log(' · '+a);
console.log('-'.repeat(68)); }
if(bad.length){ console.log('\n'+'='.repeat(68));
console.log(`BLOCKING — against spec "${S.name||path.basename(specFile)}", the following fail and must be fixed:`);
for(const b of bad) console.log(' ✗ '+b);
console.log('='.repeat(68)+`\n${bad.length} blocking item(s). exit 1 — cannot ship.`);
process.exit(1); }
console.log(advice.length
? `[judge] Spec "${S.name||''}" — nothing blocking. ${advice.length} advisory item(s) above; read them, then decide.`
: `[judge] Spec "${S.name||''}" — all claims pass.`);
}