You can now generate creatures directly within your project. Drop the open-source into your Agent, and start prompting what you want.
JavaScript
// ACS engine — mechanical checks (compile-time gate). Author: Ariescar.
// Warnings here are ERRORS: a failing check blocks the build (exit 1 in cli).
// 1. anim_integrity — CPU-skin the mesh at sampled anim times; folded tris = 0,
// edge stretch ≤ 3×. (kills twist/breakage like the wolf case)
// 2. proportion — adjacent axis segments must not be 50:50 (dead rhythm),
// unless spec.style === 'heavy'.
// 3. balance — mass centroid must project inside the support polygon.
'use strict';
const G = require('./geometry.js');
const { sampleKeys, eulerToQuat, mirrorTrack } = require('./anim.js');
const { signedDistance } = require('./inside.js');
// ── mat helpers (column-major mat4) ──
function quatMat(q) {
const [x, y, z, w] = q;
return [
1-2*(y*y+z*z), 2*(x*y+z*w), 2*(x*z-y*w), 0,
2*(x*y-z*w), 1-2*(x*x+z*z), 2*(y*z+x*w), 0,
2*(x*z+y*w), 2*(y*z-x*w), 1-2*(x*x+y*y), 0,
0, 0, 0, 1];
}
function matMul(a, b) {
const o = new Array(16).fill(0);
for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++)
for (let k = 0; k < 4; k++) o[c*4+r] += a[k*4+r] * b[c*4+k];
return o;
}
function matVec(m, v) {
return [
m[0]*v[0]+m[4]*v[1]+m[8]*v[2]+m[12],
m[1]*v[0]+m[5]*v[1]+m[9]*v[2]+m[13],
m[2]*v[0]+m[6]*v[1]+m[10]*v[2]+m[14]];
}
function transMat(t) { return [1,0,0,0, 0,1,0,0, 0,0,1,0, t[0],t[1],t[2],1]; }
// world matrices for all joints at time-fraction t of an anim (or bind pose if anim null)
function jointWorlds(sk, locals, anim, t) {
const rot = {}, trn = {};
if (anim) for (const ch of anim._tracks || []) { /* unused */ }
// build per-joint local TRS from compiled tracks
const trackOf = {};
if (anim) for (const [jn, tr] of Object.entries(anim.tracksResolved)) trackOf[jn] = tr;
const world = new Array(sk.joints.length);
sk.joints.forEach((j, i) => {
let local = transMat(locals[i]);
const tr = trackOf[j.name];
if (tr) {
const T = [
locals[i][0] + (tr.tx ? sampleKeys(tr.tx, t) : 0),
locals[i][1] + (tr.ty ? sampleKeys(tr.ty, t) : 0),
locals[i][2] + (tr.tz ? sampleKeys(tr.tz, t) : 0)];
const q = eulerToQuat(
tr.rx ? sampleKeys(tr.rx, t) : 0,
tr.ry ? sampleKeys(tr.ry, t) : 0,
tr.rz ? sampleKeys(tr.rz, t) : 0);
local = matMul(transMat(T), quatMat(q));
}
world[i] = j.parent < 0 ? local : matMul(world[j.parent], local);
});
return world;
}
function skinVerts(mesh, sk, world) {
// v' = Σ w * world[j] * (v - bind[j]) (IBM is translate(-bind))
return mesh.V.map((v, vi) => {
const out = [0, 0, 0];
for (const [jn, w] of mesh.skin[vi]) {
const ji = sk.index[jn];
const bind = sk.joints[ji].pos;
const p = matVec(world[ji], G.sub(v, bind));
out[0] += w * p[0]; out[1] += w * p[1]; out[2] += w * p[2];
}
return out;
});
}
function foldCount(V, F, minArea2 = 0) {
const tris = [];
for (const f of F) { if (f.length === 3) tris.push(f); else tris.push([f[0],f[1],f[2]],[f[0],f[2],f[3]]); }
const VN = V.map(() => [0, 0, 0]);
const FN = tris.map(([a, b, c]) => {
const n = G.cross(G.sub(V[b], V[a]), G.sub(V[c], V[a]));
for (const i of [a, b, c]) { VN[i][0]+=n[0]; VN[i][1]+=n[1]; VN[i][2]+=n[2]; }
return n;
});
let folds = 0;
tris.forEach(([a, b, c], i) => {
if (G.dot(FN[i], FN[i]) < minArea2) return; // degenerate slivers don't vote
const s = G.add(G.add(VN[a], VN[b]), VN[c]);
if (G.dot(FN[i], s) < 0) folds++;
});
return folds;
}
// How much of one mesh's skin can show an edge: the share of interior edges
// whose dihedral angle reaches the smoothing angle, i.e. exactly the edges
// smoothSplit() will crease. Computed here rather than after the fact because
// checks run before the GLB is assembled.
// A correct walk still drifts forward a little across the contact frames as the
// foot rolls through heel-strike and toe-off, so the bar is a share of stride,
// not zero.
const GAIT_FWD_MAX = 0.15;
const SOFT_FLOOR = 10; // percent of volume edges that must be able to crease
function creaseShare(V, F, deg) {
const tri = [];
for (const f of F) {
if (f.length === 3) tri.push(f);
else if (f.length === 4) { tri.push([f[0], f[1], f[2]]); tri.push([f[0], f[2], f[3]]); }
}
const fn = [];
for (const [a, b, c] of tri) {
const A = V[a], B = V[b], C = V[c];
const u = [B[0]-A[0], B[1]-A[1], B[2]-A[2]], w = [C[0]-A[0], C[1]-A[1], C[2]-A[2]];
const n = [u[1]*w[2]-u[2]*w[1], u[2]*w[0]-u[0]*w[2], u[0]*w[1]-u[1]*w[0]];
const l = Math.hypot(n[0], n[1], n[2]);
fn.push(l > 1e-12 ? [n[0]/l, n[1]/l, n[2]/l] : null);
}
const key = new Map();
const at = i => V[i].map(x => Math.round(x * 1e4)).join(',');
tri.forEach((f, i) => {
for (const [u, v] of [[f[0], f[1]], [f[1], f[2]], [f[2], f[0]]]) {
const a = at(u), b = at(v), k = a < b ? a + '|' + b : b + '|' + a;
(key.get(k) || key.set(k, []).get(k)).push(i);
}
});
const cos = Math.cos(deg * Math.PI / 180);
let hard = 0, tot = 0;
for (const fs of key.values()) {
if (fs.length !== 2) continue;
const p = fn[fs[0]], q = fn[fs[1]];
if (!p || !q) continue;
tot++;
if (p[0]*q[0] + p[1]*q[1] + p[2]*q[2] < cos) hard++;
}
return { hard, tot };
}
function runChecks(spec, sk, meshes, animsCompiled) {
const fails = [];
const warns = []; // hoisted: checks above the part_overlap block also report measures
const locals = require('./skeleton.js').localTranslations(sk);
// ── faceted bodies are banned ─────────────────────────────────────────────
// `faceted: true` on a VOLUME shatters the mass into one independent facet per
// triangle — an 800-triangle torso becomes 800 shards — and because AO bakes
// from those normals the mess ships inside COLOR_0, where no relighting can
// reach it — a faceted body comes back ~90% hard-edged. Bodies are smooth-shaded. Parts — plates, spikes, claws, crystal,
// armour — may still face freely; only volumes are covered.
if (spec.build !== 'rigid') {
const bad = (spec.volumes || []).filter(v => v.faceted).map(v => `"${v.chain}"`);
if (bad.length)
fails.push('faceted_body: volume(s) ' + bad.join(', ') + ' set "faceted": true — bodies are '
+ 'smooth-shaded. Put "sharp": true on the profile rows where the silhouette should break, '
+ 'or lower "smooth_angle" on that volume. If the creature really is a machine, declare '
+ '"build": "rigid" at spec level.');
}
// soft_mass — THE ROUNDED SAUSAGE. The opposite failure to `faceted`, and far
// more common, because it is what you get by DEFAULT.
//
// A volume is a tube of `sides` walls, so the angle between neighbouring walls
// is 360/sides, and `smooth_angle` (default 50) welds every edge under it: 9
// sides is 40 degrees, 16 is 22. Nothing on that mass can then break — not the
// shading, not the outline — and it renders as a smooth bean. The ruler is the
// share of VOLUME edges that reach their own smoothing angle.
if (spec.build !== 'rigid' && !spec.qa_isolate) {
const per = [];
let hard = 0, tot = 0;
for (const m of meshes) {
if (m.part) continue; // parts may be any shape they like
const vol = (spec.volumes || []).find(v => v.chain === m.chain);
if (vol && vol.soft) continue; // declared a soft organic lump
const deg = m.faceted ? 0 : (m.smoothAngle ?? 50);
const r = creaseShare(m.V, m.F, deg);
if (!r.tot) continue;
hard += r.hard; tot += r.tot;
per.push({ chain: m.chain, pct: 100 * r.hard / r.tot, edges: r.tot, deg });
}
if (tot) {
const pct = 100 * hard / tot;
if (pct < SOFT_FLOOR) {
per.sort((a, b) => (a.pct - b.pct) || (b.edges - a.edges));
const worst = per.slice(0, 3).map(p =>
`"${p.chain}" ${p.pct.toFixed(0)}% (smooth_angle ${p.deg})`).join(', ');
fails.push(`soft_mass: only ${pct.toFixed(0)}% of this creature's skin can show an edge `
+ `at all (the floor is ${SOFT_FLOOR}%). Nothing breaks, so every mass renders as a smooth `
+ `bean. Softest first: ${worst}. The lever that works is smooth_angle ON THE VOLUME: a volume's wall `
+ `angle is 360/sides, so 9 sides is 40° and 16 sides is 22°, and the default 50° welds `
+ `both perfectly smooth. Drop it under the wall angle on the masses named above — `
+ `applying exactly this number to every volume of the creature that was `
+ `rejected took it from 29% to 69% and left the side silhouette at IoU 1.000 — the FORM `
+ `is untouched, only the shading hardens. Fewer "sides" works too and thins the outline a little. A "sharp" row `
+ `is the SILHOUETTE lever, not this one, and it does nothing unless the radius steps `
+ `across it. A mass that is genuinely meant to be a smooth lump — a slug, a bladder, a `
+ `droplet — declares "soft": true and drops out of this count.`);
}
}
}
// QA isolation builds ("qa_isolate": true): a lone part rendered for the MID
// blind-read is not a creature — whole-body laws (balance, containment,
// proportion…) don't apply. Geometry must still be sound.
if (spec.qa_isolate) {
let qaFolds = 0;
for (const m of meshes) if (!m.doubleSided) qaFolds += foldCount(m.V, m.F);
return { fails: qaFolds > 0 ? [`mesh_integrity: bind pose has ${qaFolds} flipped tris`] : [], warns: [] };
}
// resolve raw tracks (with mirrored twins) once per anim for CPU skinning
const { mirrorName } = require('./skeleton.js');
const animsResolved = Object.entries(spec.animations || {}).map(([name, a]) => {
const tracks = { ...a.tracks };
const phase = a.mirror_phase ?? 0;
for (const cn of spec.mirror || []) {
for (const jn of spec.chains[cn] || []) {
if (!tracks[jn] || tracks[mirrorName(jn)]) continue;
const dst = {};
for (const [axis, keys] of Object.entries(tracks[jn])) {
const flip = (axis === 'ry' || axis === 'rz' || axis === 'tx') ? -1 : 1;
dst[axis] = mirrorTrack(keys, phase, flip, a.loop !== false); // 同一支:重新取樣,不是搬鍵
}
tracks[mirrorName(jn)] = dst;
}
}
return { name, tracksResolved: tracks };
});
// scale floors: ignore sub-centimetre noise relative to model size
const allV0 = meshes.flatMap(m => m.V);
const ys0 = allV0.map(v => v[1]);
const modelH = Math.max(...ys0) - Math.min(...ys0) || 1;
const edgeFloor = 0.015 * modelH; // edges shorter than 1.5% of height don't vote
// 0. declared size — "height" (metres, ground to crown). Size is identity:
// a 1.7 m "giant" is just a man. The build must land within ±15%.
if (spec.height) {
const err = Math.abs(modelH - spec.height) / spec.height;
if (err > 0.15)
fails.push(`size: spec declares height ${spec.height} m but the build stands `
+ `${modelH.toFixed(2)} m (${Math.round(err * 100)}% off) — multiply every joint coordinate `
+ `by ${(spec.height / modelH).toFixed(4)} to land on the declaration, or change the `
+ `declaration to ${modelH.toFixed(2)}.`);
}
const areaFloor2 = Math.pow(0.0004 * modelH * modelH, 2); // ~sliver faces don't vote
// 1. anim_integrity
const bindEdges = [];
for (const m of meshes) {
const edges = [];
for (const f of m.F) for (let k = 0; k < f.length; k++) {
const a = f[k], b = f[(k + 1) % f.length];
const L = G.len(G.sub(m.V[a], m.V[b]));
if (L >= edgeFloor) edges.push([a, b, L]);
}
bindEdges.push(edges);
}
for (const anim of animsResolved) {
for (const t of [0, 0.2, 0.4, 0.6, 0.8]) {
const world = jointWorlds(sk, locals, anim, t);
// WHERE, not just how many. This check is ~83% of all blocks in practice,
// and "10 flipped tris" with no location forces a binary search through
// the spec. Name the mesh, and for a stretch name the joint driving it.
let folds = 0, maxStretch = 0, worstFoldMesh = '', worstFolds = 0;
let stretchMesh = '', stretchJoint = '';
const nameOf = (m) => m.chain || m.part || m.material;
const heaviestJoint = (m, vi) => {
const infl = (m.skin && m.skin[vi]) || [];
let best = '', bw = -1;
for (const [jn, w] of infl) if (w > bw) { bw = w; best = jn; }
return best;
};
meshes.forEach((m, mi) => {
const V2 = skinVerts(m, sk, world);
if (!m.doubleSided) { // open membranes have saddle regions; fold test assumes a closed surface
const f = foldCount(V2, m.F, areaFloor2);
folds += f;
if (f > worstFolds) { worstFolds = f; worstFoldMesh = nameOf(m); }
}
for (const [a, b, L] of bindEdges[mi]) {
const s = G.len(G.sub(V2[a], V2[b])) / L;
if (s > maxStretch) {
maxStretch = s; stretchMesh = nameOf(m);
stretchJoint = heaviestJoint(m, a) || heaviestJoint(m, b);
}
}
});
if (folds > 0) fails.push(`anim_integrity: "${anim.name}" @${t.toFixed(1)} folds mesh — `
+ `${folds} flipped tris, worst in "${worstFoldMesh}" (${worstFolds}). A bend there is sharper `
+ `than the volume can absorb: reduce the rotation on the joint driving "${worstFoldMesh}", `
+ `raise "ring_step" on that volume so rings are not crowded through the bend, or add a joint `
+ `to split the bend across two segments.`);
if (maxStretch > 3) fails.push(`anim_integrity: "${anim.name}" @${t.toFixed(1)} stretches an edge `
+ `${maxStretch.toFixed(1)}× in "${stretchMesh}", pulled by joint "${stretchJoint}" — that joint `
+ `is tearing the skin. Reduce its travel, or spread the same motion over more joints in the chain.`);
}
}
// 2. proportion — axis chain, 50:50 ban on significant adjacent segments
const mset = new Set(spec.mirror || []);
const mirroredChains = new Set([...mset, ...[...mset].map(c => 'R' + c.slice(1))]);
if (spec.style !== 'heavy') {
for (const [cn, names] of Object.entries(spec.chains)) {
// limbs are exempt (legs are naturally even) — but membership is decided by
// spec.mirror, NOT by the chain's first letter. Testing the letter meant a
// dead-rhythm chain slipped through by renaming "axis" to "Laxis".
if (mirroredChains.has(cn)) continue;
const segs = [];
for (let i = 1; i < names.length; i++)
segs.push(G.len(G.sub(spec.joints[names[i]] ?? [0,0,0], spec.joints[names[i-1]] ?? [0,0,0])));
const total = segs.reduce((a, b) => a + b, 0);
const mean = total / (segs.length || 1);
for (let i = 0; i < segs.length - 1; i++) {
// minor-segment filter is RELATIVE TO MEAN segment length (a fixed %-of-total
// filter silently exempted almost every pair on long chains)
if (segs[i] < 0.5 * mean || segs[i+1] < 0.5 * mean) continue;
const r = Math.min(segs[i], segs[i+1]) / (Math.max(segs[i], segs[i+1]) || 1);
// 0.923 aligns with the styling rule ("no 50:50 rhythm"); the old 0.96 left
// a 0.92–0.96 blind band that let a 0.946 split through
if (r > 0.923) fails.push(`proportion: chain "${cn}" segments ${names[i]}→${names[i+1]}→${names[i+2]} are 50:50 (${r.toFixed(2)}) — dead rhythm; aim for ~0.62–0.85 (declare "style":"heavy" to allow)`);
}
}
}
// 3. balance — centroid over support polygon (XZ convex hull of lowest verts)
const allV = meshes.flatMap(m => m.V);
const cen = allV.reduce((a, v) => G.add(a, v), [0,0,0]).map(x => x / allV.length);
const ys = allV.map(v => v[1]); const ymin = Math.min(...ys), ymax = Math.max(...ys);
const feet = allV.filter(v => v[1] < ymin + 0.08 * (ymax - ymin));
if (feet.length >= 3) {
const xs = feet.map(v => v[0]), zs = feet.map(v => v[2]);
const inX = cen[0] >= Math.min(...xs) - 1e-6 && cen[0] <= Math.max(...xs) + 1e-6;
const inZ = cen[2] >= Math.min(...zs) && cen[2] <= Math.max(...zs);
if (!inX || !inZ) fails.push(`balance: mass centre (${cen[0].toFixed(2)},${cen[2].toFixed(2)}) falls outside the support footprint x[${Math.min(...xs).toFixed(2)},${Math.max(...xs).toFixed(2)}] z[${Math.min(...zs).toFixed(2)},${Math.max(...zs).toFixed(2)}] — it would tip over`);
}
// 4. root containment — attached volumes (legs/tail) must bury their root
// ring inside the host tube, or the open ring shows on the surface.
const volsByChain = {};
for (const m of meshes) if (m._rings && m.chain) volsByChain[m.chain] = m;
for (const [cn, hostJoint] of Object.entries(spec.attach || {})) {
const v = volsByChain[cn]; if (!v) continue;
// host volume = the one whose chain contains the host joint
const hostChain = Object.keys(spec.chains).find(c => volsByChain[c] && spec.chains[c].includes(hostJoint) && c !== cn);
if (!hostChain) continue;
const host = volsByChain[hostChain];
const rootRing = v._rings[0];
let inside = 0;
// Keep how far past the surface each ring point sits, and which host centre
// it is nearest. The check already computes both; throwing them away and
// saying only "deeper" makes the reader re-derive the geometry the engine
// just did — the same work, done twice, once in code and once by hand.
const over = []; let nearC = null, nearD = Infinity;
for (const p of rootRing) {
// Distance to the host's actual SURFACE, signed: negative is inside. This
// used to compare against a sphere of the nearest ring's widest radius,
// which hands out a whole half-width of phantom "inside" straight off the
// end cap — exactly where the next chain attaches. See engine/core/inside.js.
const sd = signedDistance(p, host);
over.push(sd);
if (sd < nearD) { nearD = sd; nearC = p; }
if (sd < 0) inside++;
}
// THE STATISTIC IS THE MEDIAN, not a count of points. A root ring meets a
// CURVED host, so a few of its points always poke out; counting them punishes
// every honest quadruped. What separates a seated ring from a floating one is
// whether its MIDDLE is buried. Across a reference set of 102 joints the median
// point sits inside on 95 of them, and the 7 it does not are the ones you can
// see. That is a style number, not a law, and it is a tag away from being a
// profile.
const sortedSD = over.slice().sort((a, b) => a - b);
const medianSD = sortedSD[Math.floor(sortedSD.length / 2)];
if (medianSD >= 0) {
// 80% of the ring has to end up inside, so the move that fixes it is the
// 80th-percentile overshoot — not the worst point, which would bury it
// further than the rule asks for.
const sorted = sortedSD;
const need = sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.8))];
// Name the CHAIN'S OWN first joint, not the host joint it hangs from.
// Moving the host drags this chain along with it, so that correction can
// never converge — applying it repeatedly just walks the pair across the
// model. The thing sitting outside the host is this chain's root ring.
const ownRoot = (spec.chains[cn] || [])[0] || hostJoint;
const jp = sk.joints[sk.index[ownRoot]] && sk.joints[sk.index[ownRoot]].pos;
let dirTxt = '';
if (nearC && jp) {
const d = G.sub(nearC, jp), L = G.len(d) || 1;
dirTxt = ` toward [${d.map(x => (x / L).toFixed(2)).join(', ')}]`;
}
fails.push(`root_containment: chain "${cn}" root ring is `
+ `${Math.round(100 * (1 - inside / rootRing.length))}% outside its host "${hostChain}" `
+ `— the open ring will show on the surface. Move joint "${ownRoot}" about `
+ `${Math.max(0, need).toFixed(3)}m${dirTxt} (into the host), or widen "${hostChain}" `
+ `there by the same amount.`);
}
}
// 5. limb clearance — mirrored volumes must not touch across the centreline
// (Verified:ly on exposed verts below the torso)
{
const hostOf = cn => {
const hj = (spec.attach || {})[cn]; if (!hj) return null;
const hc = Object.keys(spec.chains).find(c => volsByChain[c] && spec.chains[c].includes(hj) && c !== cn);
return hc ? volsByChain[hc] : null;
};
const containedInHost = (p, host) => {
if (!host) return false;
// Surface distance, not a sphere (engine/core/inside.js). The band is the
// same idea it always was: a vert sitting just OUTSIDE the host is seam
// geometry, covered by the host's own silhouette, not a limb showing at the
// centreline — a zero-margin test flags every quadruped groin seam.
return signedDistance(p, host) < 0.02 * modelH;
};
for (const cn of spec.mirror || []) {
const v = volsByChain[cn]; if (!v) continue;
const host = hostOf(cn);
const exposed = v.V.filter(p => !containedInHost(p, host));
if (!exposed.length) continue;
const minX = Math.min(...exposed.map(p => Math.abs(p[0])));
const clearance = 2 * minX;
if (clearance < 0.03 * modelH)
fails.push(`limb_clearance: "${cn}" and its mirror are ${clearance.toFixed(3)} apart at the `
+ `centreline (need ≥ ${(0.03 * modelH).toFixed(3)}) — legs will interpenetrate in motion. `
+ `Move "${cn}" ${(((0.03 * modelH) - clearance) / 2).toFixed(3)} further out in x `
+ `(the mirror follows), or narrow the limb by the same amount.`);
}
}
// 4b. part_attachment — root_containment above only walks `spec.attach`, whose
// candidates are meshes carrying BOTH `_rings` and `chain`. Parts (curve /
// fin / eye / paw / spike / membrane) have neither, so until now no part was
// ever checked for being attached to anything: tusks whose entire root ring
// floated 0.031 clear of the skull, a trunk 6/15 outside, a forehead plate
// 0.050 above the surface at its nearest point — all shipped "all green"
// and were caught by eye, in the most expensive repair round of the run.
// The test is deliberately generous: a part only has to TOUCH its host.
// Eyes and conformed plates sit ON the surface (nearest ≈ 0) and pass; a
// part hanging in the air does not.
{
const gap = 0.015 * modelH; // a part nearer than this counts as meeting the host
for (const m of meshes) {
if (!m.part || !m.hostChain) continue;
// A mirrored twin is the source reflected across X, and its host volume is
// the source's host reflected the same way — testing it against the LEFT
// host would measure the width of the creature. The source carries the
// verdict for both; any twin-only deformation is mirror_distortion's job.
if (m._mirrorSrc) continue;
// "join":"place" is the designer DECLARING deliberate detachment (a
// floating rune, an orbiting shard) — the strict law yields to it;
// part_seat still reports the measured burial for the record.
if (m.join === 'place') continue;
const host = volsByChain[m.hostChain];
if (!host || !host._rings) continue;
let nearest = Infinity;
for (const p of m.V) {
// <0 inside the host, >0 clear of it — measured against the surface, not
// a sphere through the widest ring (engine/core/inside.js).
const outside = signedDistance(p, host);
if (outside < nearest) nearest = outside;
}
if (nearest > gap)
// Say the MOVE, not just the gap. The engine measured the distance; a
// message that reports it and stops makes the reader work the
// subtraction back out of the prose. The first third of a root is meant
// to be embedded, so the useful number is the one that buries it, not
// the one that merely touches: gap + a third of the part's own reach.
fails.push(`part_attachment: "${m.part}" never meets its host "${m.hostChain}" — its closest `
+ `point still stands ${nearest.toFixed(3)} clear of the surface (tolerance ${gap.toFixed(3)}). `
+ `Move it ${(nearest + gap).toFixed(3)} INTO the host along its own axis — touching is the `
+ `floor, and the first third of a root is meant to be embedded, which is what hides the seam. `
+ `Or move its anchor onto the surface. `
+ `Floating, it reads as a detached sticker and drifts the moment the host animates.`);
}
}
// 5b. mirror_distortion — `joints_R` staggers a mirrored twin by TRANSLATING
// its vertices with skin weights: the mesh was grown along the LEFT bone
// path and is then linearly dragged onto the right joints. Small offsets
// read as a pose; large ones shear the volume — a thigh that measures
// 0.38 deep on the left comes out 0.15 deep on the right while its width
// stays correct, which looks like the limb lost its volume. Nothing else
// catches this: the build is green, the silhouette from the left is fine,
// and only a look from the other side shows it.
// Without joints_R every axis ratio is exactly 1.00, so any deviation is
// distortion the skinning introduced, in either direction.
{
const extents = (V) => {
const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
for (const v of V) for (let k = 0; k < 3; k++) {
if (v[k] < lo[k]) lo[k] = v[k];
if (v[k] > hi[k]) hi[k] = v[k];
}
return [hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]];
};
const AXIS = ['width', 'height', 'depth'];
for (const m of meshes) {
if (!m._mirrorSrc) continue;
const a = extents(m._mirrorSrc.V), b = extents(m.V);
for (let k = 0; k < 3; k++) {
if (a[k] < 1e-6) continue;
const r = b[k] / a[k];
const who = m._mirrorSrc.chain || m._mirrorSrc.part || m._mirrorSrc.material;
const how = r < 1 ? 'collapsed' : 'stretched';
if (r < 0.70 || r > 1.30)
fails.push(`mirror_distortion: the mirrored twin of "${who}" has ${how} — ${AXIS[k]} `
+ `${b[k].toFixed(3)} against ${a[k].toFixed(3)} on the source (${(r * 100).toFixed(0)}%). `
+ `"joints_R" drags a mesh grown on the LEFT bone path onto the right joints by translation, `
+ `so a large offset shears the volume instead of posing it. Keep "joints_R" to a few `
+ `centimetres of stagger; for a genuinely different pose take the limb OUT of "mirror" `
+ `and author it as its own chain.`);
else if (r < 0.88 || r > 1.12)
warns.push(`mirror_distortion: mirrored twin of "${who}" is ${(r * 100).toFixed(0)}% of the `
+ `source's ${AXIS[k]} — "joints_R" is starting to shear the volume rather than pose it.`);
}
}
}
// 6. bind-pose integrity
let bindFolds = 0;
for (const m of meshes) if (!m.doubleSided) bindFolds += foldCount(m.V, m.F, areaFloor2);
if (bindFolds > 0) fails.push(`mesh_integrity: bind pose has ${bindFolds} flipped tris — geometry folds into itself`);
// 7. attack_reach — an attack must COMMIT FORWARD. Two ways to satisfy it,
// because a strike does not have to be a whole-body lunge:
// REACH — something ends up in the space in front of the body, i.e. past
// the bind-pose front. Enough to touch a target standing there.
// SWING — something travels forward far enough relative to ITS OWN bind
// position. A creature planted on the spot swinging an arm, a
// weapon or a tail is a legitimate attack; the root never moves
// and the hand still crosses a lot of ground.
// Either route passes. The old rule demanded half a body span PAST the
// nose, which forced every creature to fly forward and rejected every
// stand-and-swing design.
{
const atk = animsResolved.find(a => a.name === 'attack');
if (atk) {
const zs0 = allV0.map(v => v[2]);
const maxZ0 = Math.max(...zs0);
const span = Math.max(maxZ0 - Math.min(...zs0), modelH);
const REACH_MIN = 0.15 * span;
// A limb's travel is bounded by the LIMB, not by the body. Measuring the
// swing against the body span is a dimensional error: it asks a wolf's
// foreleg to cover most of the wolf. Each mesh is judged against its own
// longest bind axis instead, so the same rule fits a claw, a tail and a
// greatsword. Meshes too small to carry a strike (eyes, nostrils) do not
// vote. Calibration: a foreleg swung ±20° travels 0.32 of its own length,
// ±35° travels 0.51, ±55° travels 0.70 — 0.45 keeps the real swings.
const SWING_FRAC = 0.45, MIN_PART = 0.10 * span;
let reach = 0, swing = 0, swingName = '', swingRatio = 0;
const extentOf = (m) => {
let lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
for (const v of m.V) for (let k = 0; k < 3; k++) {
if (v[k] < lo[k]) lo[k] = v[k];
if (v[k] > hi[k]) hi[k] = v[k];
}
return Math.max(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]);
};
for (let s = 0; s <= 20; s++) {
const world = jointWorlds(sk, locals, atk, s / 20);
for (const m of meshes) {
const ext = extentOf(m);
const V2 = skinVerts(m, sk, world);
for (let i = 0; i < V2.length; i++) {
const dz = V2[i][2] - maxZ0; if (dz > reach) reach = dz;
if (ext < MIN_PART) continue;
const tr = V2[i][2] - m.V[i][2];
if (tr > swing) swing = tr;
const ratio = tr / ext;
if (ratio > swingRatio) { swingRatio = ratio; swingName = m.chain || m.part || m.material; }
}
}
}
if (reach < REACH_MIN && swingRatio < SWING_FRAC)
fails.push(`attack_reach: "attack" neither reaches nor swings. Forward of the bind front: `
+ `${reach.toFixed(2)} (a reach needs ≥ ${REACH_MIN.toFixed(2)}). Best swing: "${swingName || 'none'}" `
+ `travels ${swing.toFixed(2)} forward = ${(swingRatio * 100).toFixed(0)}% of its own length `
+ `(a swing needs ≥ ${(SWING_FRAC * 100).toFixed(0)}%). Nothing commits at a target. `
+ `You do NOT have to lunge — standing on the spot and sweeping a limb, tail or weapon `
+ `counts, as long as it winds BACK and crosses FORWARD. Otherwise drive the root with tz keys.`);
}
}
// 7b. gait_direction — A PLANTED FOOT MUST TRAVEL BACKWARD.
//
// The clips loop in place, so the ground does the moving: while a foot is on
// the ground it must sweep BACKWARD under the body, and that is what pushes
// the creature forward. Swing it backward and sweep it forward instead and you
// have a perfectly smooth walk cycle that plays in reverse — invisible in every
// still frame, obvious the moment it moves.
{
const mv = animsResolved.find(a => a.name === 'move');
if (mv) {
const feet = [];
for (const [cn, js] of Object.entries(spec.chains || {})) {
if (!/leg|foot|paw/i.test(cn)) continue;
const last = js[js.length - 1];
if (last && sk.index[last] != null) feet.push(last);
}
for (const jn of feet) {
const N = 24, path = [];
for (let s = 0; s <= N; s++) {
const w = jointWorlds(sk, locals, mv, s / N);
path.push(matVec(w[sk.index[jn]], [0, 0, 0]));
}
const ys = path.map(p => p[1]), zs = path.map(p => p[2]);
const ymin = Math.min(...ys), ymax = Math.max(...ys);
const stride = Math.max(...zs) - Math.min(...zs);
if (stride < 1e-3 || ymax - ymin < 1e-4) continue; // not a stepping leg
// Sum the per-step forward travel over contact frames, rather than
// (last - first): a contact phase that straddles the loop point would
// otherwise subtract two frames that are the same frame and read 0.
// Contact window: expand CONTIGUOUSLY from the foot's lowest frame.
// Thresholding the whole cycle breaks as soon as the pelvis bobs: the bob puts
// a second harmonic on the foot's Y, the window splits in two, and touchdown /
// liftoff land on the wrong frames. (Measured: a correct 24%-reach walk read as
// -17% after adding pelvis translation.) Contiguous expansion is immune to that.
const L = path.length, lim = ymin + (ymax - ymin) * 0.30;
let c0 = ys.indexOf(ymin), aI = c0, bI = c0;
while (ys[(aI - 1 + L) % L] < lim && (bI - aI) < L - 1) aI--;
while (ys[(bI + 1) % L] < lim && (bI - aI) < L - 1) bI++;
const ix = i => ((i % L) + L) % L;
const low = path.map(() => false);
for (let i = aI; i <= bI; i++) low[ix(i)] = true;
// 7c. gait_footfall — THE FOOT MUST LAND IN FRONT OF WHERE IT LEAVES.
// gait_direction only asks that the planted foot sweeps backward. A leg that
// lifts and puts itself down in the same place passes that and still is not
// walking; so does a leg that reaches backward and plants behind the body.
// The reference is the foot's own liftoff point, NOT the hip: a bird's hip sits
// far forward inside the body, so its foot is always ahead of the hip and a
// hip-relative test calls a good walk bad.
{
const reach = path[ix(aI)][2] - path[ix(bI)][2];
if (reach < 0.15 * stride)
fails.push(`gait_footfall: "${jn}" touches down ${reach >= 0 ? '' : '-'}`
+ `${Math.abs(reach).toFixed(3)} m ${reach >= 0 ? 'in front of' : 'BEHIND'} where it lifts off `
+ `(${(100 * reach / stride).toFixed(0)}% of its ${stride.toFixed(2)} m stride; needs >= 15% in FRONT). `
+ `A step reaches FORWARD and DOWN, then sweeps back under the body. Lifting the foot and `
+ `setting it down level or behind is walking backwards, or marching on the spot. `
+ `THE FIX: shift the hip track so the leg is FORWARD when the foot comes down and BACK when it lifts `
+ `— the phase, not the amplitude.`);
}
let net = 0, contact = 0;
for (let s = 0; s < path.length - 1; s++) {
if (!(low[s] && low[s + 1])) continue;
net += path[s + 1][2] - path[s][2];
contact++;
}
if (contact < 2) continue;
if (net > stride * GAIT_FWD_MAX) {
fails.push(`gait_direction: "${jn}" travels ${net.toFixed(3)} m FORWARD while it is on `
+ `the ground — ${(100 * net / stride).toFixed(0)}% of its own ${stride.toFixed(2)} m `
+ `stride, in the wrong direction. A planted foot must sweep BACKWARD under the body; `
+ `that is what makes the creature look like it is going somewhere. This clip swings `
+ `the leg back through the air and pushes it forward on the ground, which is a walk `
+ `cycle playing in reverse — smooth, correct-looking in every still, and visibly `
+ `backwards the moment it moves. THE FIX: write ONE leg correctly (negate its hip/knee/hock rx `
+ `tracks so it reaches forward through the air and sweeps back on the ground), `
+ `DELETE the hand-written opposite leg, and set "mirror_phase": 0.5 on the clip so `
+ `the engine generates it half a cycle out. Hand-writing the second leg is where the `
+ `phase error comes from and it is twice the authoring for a worse result.`);
}
}
}
}
// 7c. root_drive — DO NOT NAIL THE CREATURE DOWN BY ITS ROOT.
//
// A lunge written on a joint that is not the skeleton root moves everything
// BELOW that joint and leaves the root exactly where it was. On a creature
// whose root is the rump, the body lunges and the backside stays pinned to the
// floor, which reads as being nailed down.
{
const root = sk.joints.find(j => j.parent < 0);
for (const anim of animsResolved) {
const moved = Object.entries(anim.tracksResolved || {})
.filter(([, tr]) => tr.tz).map(([jn]) => jn);
if (!moved.length || !root) continue;
const bind = jointWorlds(sk, locals, null, 0);
let peak = 0, pu = 0;
for (let s = 0; s <= 20; s++) {
const w = jointWorlds(sk, locals, anim, s / 20);
for (const jn of moved) {
const d = matVec(w[sk.index[jn]], [0, 0, 0])[2] - matVec(bind[sk.index[jn]], [0, 0, 0])[2];
if (Math.abs(d) > Math.abs(peak)) { peak = d; pu = s / 20; }
}
}
if (Math.abs(peak) < 0.05) continue; // not really a lunge
const w = jointWorlds(sk, locals, anim, pu);
const rd = matVec(w[sk.index[root.name]], [0, 0, 0])[2]
- matVec(bind[sk.index[root.name]], [0, 0, 0])[2];
if (Math.abs(rd) < Math.abs(peak) * 0.6) {
fails.push(`root_drive: "${anim.name}" drives ${moved.map(m => `"${m}"`).join(', ')} `
+ `${peak.toFixed(2)} m forward, but the skeleton ROOT "${root.name}" moves `
+ `${rd.toFixed(3)} m. Everything below the driven joint lunges and the root stays where `
+ `it was, so the creature reads as nailed to the floor by that end of itself. Put the `
+ `"tz" track on "${root.name}" instead — it is the root, so the whole body follows it. `
+ `Card 03's own example does exactly that.`);
}
}
}
// 7d. THE COLOUR QUESTIONS A READER WAS BEING PAID TO ANSWER.
//
// Both are arithmetic on the palette — microseconds, no render, no subagent.
//
// These are ADVICE. A number saying the eye will not separate two masses is
// worth reading and is not worth refusing a build over — camouflage and
// deliberately subtle detail are real design choices. What is NOT acceptable
// is spending a reader to learn them.
{
let hex2lab = null;
try { hex2lab = require('./shade.js').hex2lab; } catch { /* no stack, skip */ }
const pal = spec.palette || {};
const lab = {};
if (hex2lab) for (const [k, v] of Object.entries(pal)) {
const c = (v && v.color) || (typeof v === 'string' ? v : null);
if (typeof c === 'string' && /^#[0-9a-f]{6}$/i.test(c)) lab[k] = hex2lab(c.slice(1));
}
const dist = (a, b) => Math.hypot(lab[a][0]-lab[b][0], lab[a][1]-lab[b][1], lab[a][2]-lab[b][2]);
// value_order — the whole value plan, sorted, so nobody squints at a render.
const byL = Object.keys(lab).sort((a, b) => lab[b][0] - lab[a][0]);
if (byL.length > 1) {
warns.push('value_order: materials by lightness, brightest first — '
+ byL.map(k => `${k} ${lab[k][0].toFixed(2)}`).join(' · '));
// whatever is brightest OWNS the eye. If something else is within 0.05 of
// it, they compete and neither wins.
const top = byL[0];
const tied = byL.slice(1).filter(k => lab[top][0] - lab[k][0] < 0.05);
if (tied.length)
warns.push(`value_order: "${top}" (L ${lab[top][0].toFixed(2)}) is tied for brightest with `
+ tied.map(k => `"${k}" (${lab[k][0].toFixed(2)})`).join(', ')
+ ' — nothing owns the eye when two masses sit at the same value. Drop the one that is '
+ 'NOT the brief\'s dominant focal by at least 0.08 L, or accept that the eye will '
+ 'ping-pong.');
}
// contrast_adjacent — a part must separate from what it SITS ON. Materials
// inside one visual mass are deliberately close (three shades of black
// quill are one mass), so this only compares a part to its host.
const volMat = {};
for (const m of meshes) if (!m.part && m.chain) volMat[m.chain] = m.material;
const seen = new Set();
for (const m of meshes) {
if (!m.part || !m.hostChain) continue;
const a = m.material, b = volMat[m.hostChain];
if (!a || !b || a === b) {
if (a && a === b) {
const k = `${m.part}|${a}`;
if (!seen.has(k)) {
seen.add(k);
warns.push(`contrast_adjacent: part "${m.part}" wears the SAME material "${a}" as the `
+ `"${m.hostChain}" it sits on — at reading size it is not a part, it is a bump. `
+ `Give it its own entry in the palette.`);
}
}
continue;
}
if (!lab[a] || !lab[b]) continue;
const d = dist(a, b);
if (d < 0.10) {
const k = `${a}|${b}`;
if (seen.has(k)) continue;
seen.add(k);
warns.push(`contrast_adjacent: part "${m.part}" (${a}, L ${lab[a][0].toFixed(2)}) against its `
+ `host "${m.hostChain}" (${b}, L ${lab[b][0].toFixed(2)}) — OKLab distance ${d.toFixed(3)}, `
+ `under 0.10. They will read as one mass at thumbnail size. Move one of them in `
+ `LIGHTNESS, which is what survives shrinking; hue alone does not.`);
}
}
}
// 8. declared adjacency — "touch": [["chainA","chainB"], ...]. Declared-
// connected chains must actually meet; a gap reads as floating bodyparts.
{
const insideVol = (p, vol) => {
let best = Infinity, bs = 0;
vol._pts.forEach((c2, si) => { const d = G.len(G.sub(p, c2)); if (d < best) { best = d; bs = si; } });
const c2 = vol._pts[bs];
const rad = Math.max(...vol._rings[bs].map(q => G.len(G.sub(q, c2))));
return best < rad * 0.98;
};
for (const [ca, cb] of spec.touch || []) {
const A = volsByChain[ca], B = volsByChain[cb];
if (!A || !B) { fails.push(`touch: pair ["${ca}","${cb}"] names a chain with no volume`); continue; }
const eps = 0.01 * modelH;
let met = false, best = Infinity;
for (const p of A.V) { if (insideVol(p, B)) { met = true; break; } }
if (!met) for (const p of B.V) { if (insideVol(p, A)) { met = true; break; } }
if (!met) outer: for (const p of A.V) for (const q of B.V) {
const d = G.len(G.sub(p, q)); if (d < best) best = d;
if (d < eps) { met = true; break outer; }
}
if (!met)
fails.push(`touch: "${ca}" and "${cb}" are declared connected but their surfaces stay `
+ `${best.toFixed(3)} apart. Close the gap by at least ${best.toFixed(3)} and then keep `
+ `going — move one chain's end joint ${(best * 1.5).toFixed(3)} toward the other, so the `
+ `join is BURIED rather than merely touching; a seam that only kisses still shows.`);
}
}
// 9. part_overlap — how much of one part is actually inside another.
//
// THIS USED TO COMPARE BOUNDING BOXES, and that is not a shape. A 2.8 m spear's
// box contains any hand gripping it, so the check reported "the hand is 100%
// inside the spear" — and acting on that number removes parts that are placed
// correctly. The signal was not noisy, it was wrong: a box says nothing about
// whether two surfaces share space. Same error class as the sphere that let a
// head float.
//
// Measured against the real surfaces now (engine/core/inside.js), which makes
// most of the old false positives disappear on their own — a hand around a
// haft is not inside the haft. Two severities, because they are different
// problems: a part BURIED whole is geometry nobody will ever see that still
// costs triangles, and a part partly in is a seam, which is usually the point.
{
const { signedDistance } = require('./inside.js');
const parts = meshes.filter(m => m.part && m.V && m.V.length && m.F && m.F.length);
const box = m => {
const lo = [1e9, 1e9, 1e9], hi = [-1e9, -1e9, -1e9];
for (const v of m.V) for (let a = 0; a < 3; a++) {
if (v[a] < lo[a]) lo[a] = v[a];
if (v[a] > hi[a]) hi[a] = v[a];
}
return { lo, hi };
};
const boxes = parts.map(box);
const stem = s => s.replace(/\.R$/, '').replace(/[_-]?\d+$/, '');
for (let i = 0; i < parts.length; i++) for (let k = 0; k < parts.length; k++) {
if (i === k) continue;
const A = parts[i], B = parts[k];
if (stem(A.part) === stem(B.part)) continue; // own mirror twin, or the same ring repeat
if (B.doubleSided) continue; // a membrane encloses nothing
let sep = false;
for (let a = 0; a < 3; a++) if (boxes[i].lo[a] > boxes[k].hi[a] || boxes[k].lo[a] > boxes[i].hi[a]) sep = true;
if (sep) continue; // boxes do not even touch — cheap reject only
const step = Math.max(1, Math.ceil(A.V.length / 160));
let inside = 0, tested = 0;
for (let v = 0; v < A.V.length; v += step) { tested++; if (signedDistance(A.V[v], B) < 0) inside++; }
if (!tested) continue;
const frac = inside / tested;
if (frac >= 0.995)
warns.push(`part_overlap: '${A.part}' is COMPLETELY buried inside '${B.part}' — invisible geometry `
+ `that still costs triangles. Either it is meant to nest (an eye in a socket) and is fine, or it `
+ `should be pushed out until it shows, or deleted.`);
else if (frac > 0.45)
warns.push(`part_overlap: '${A.part}' sits ${Math.round(frac * 100)}% inside '${B.part}' `
+ `— measured surface to surface, so this is real interpenetration, not a bounding box.`);
}
}
// 10. part_seat — is the part's base ring actually buried in a body?
// The exposed-root class: tusks starting in mid-air, beaks hovering off
// the face, a trunk that reads as a bolted-on object. Every hosted
// curve/spike carries its base ring (`_seatIdx`); how it is ALLOWED to
// meet the body is the declared "join":
// "insert" → base ring ≥60% inside a volume, or BLOCK
// "extrude" → base ring CENTRE inside a volume (grows out of the skin), or BLOCK
// "snap" → the part must ride an anchor (surface conform), or BLOCK
// "place" → deliberately free-floating — no test (rare; justify it)
// Undeclared parts are measured anyway: a base ring under 50% buried is
// a warn — look at the junction and either sink it or declare the join.
{
const vols = Object.values(volsByChain);
const insideAnyVol = (q) => {
for (const vol of vols) {
let best = Infinity, bs = 0;
vol._pts.forEach((c2, si) => { const d = G.len(G.sub(q, c2)); if (d < best) { best = d; bs = si; } });
const c2 = vol._pts[bs];
const rad = Math.max(...vol._rings[bs].map(r2 => G.len(G.sub(r2, c2))));
if (best < rad * 0.98) return true;
}
return false;
};
const JOINS = new Set(['insert', 'extrude', 'snap', 'place', undefined]);
for (const pt of spec.parts || []) {
if (!JOINS.has(pt.join))
fails.push(`part_seat: unknown join "${pt.join}" on '${pt.name || pt.type}' — use insert / extrude / snap / place`);
if (pt.join === 'snap' && !pt.anchor)
fails.push(`part_seat: '${pt.name || pt.type}' declares join "snap" but has no "anchor" — snap means riding the surface`);
}
if (vols.length) for (const m of meshes) {
if (!m._seatIdx) continue;
let seat = m._seatIdx.map(i => m.V[i]).filter(Boolean);
if (!seat.length) continue;
// mirrored twins: the vols list holds the LEFT/axis volumes, so test the
// twin's seat in mirror space (x-flipped) — symmetric by construction
if (m.part && m.part.endsWith('.R')) seat = seat.map(q => [-q[0], q[1], q[2]]);
const buried = seat.filter(insideAnyVol).length / seat.length;
const centre = seat.reduce((a, q) => G.add(a, q), [0, 0, 0]).map(x => x / seat.length);
const label = m.part || 'part';
if (m.join === 'insert' && buried < 0.6)
fails.push(`part_seat: '${label}' declares join "insert" but its base ring is only ${Math.round(buried * 100)}% inside a body (need ≥60%) — sink the root deeper or thicken the host`);
else if (m.join === 'extrude' && !insideAnyVol(centre))
fails.push(`part_seat: '${label}' declares join "extrude" but its base centre sits outside every body — the part does not grow out of a surface`);
else if (!m.join && buried < 0.5)
warns.push(`part_seat: '${label}' base ring is ${Math.round(buried * 100)}% buried — the root may show; sink it, or declare the join (insert/extrude/snap/place)`);
}
}
// ── 7i. eye_pupil — an eye is a VALUE STEP, not a coloured dot.
//
// The engine's `eye` part is one monochrome sphere. On its own it ships a flat
// disc of colour, and at reading size a flat disc is a sticker, not an eye. What
// makes an eye read is the step between a bright iris and a near-black pupil —
// not the saturation of either. Faces built from a lone sphere measure as "no
// eyes" for exactly this, and the fix is always the same: a second, smaller,
// much darker sphere on the same host. `harness/pupils.py` places it by measuring where the eyeball actually
// landed, because guessed numbers bury it inside the iris or float it in front.
{
const eyes = (spec.parts || []).filter(p => p.type === 'eye');
const byHost = {};
for (const p of eyes) (byHost[p.host] = byHost[p.host] || []).push(p);
const bare = [];
for (const [host, ps] of Object.entries(byHost)) {
if (ps.length > 1) continue; // a pair on one host IS iris + pupil
const L = m => {
const pal = (spec.palette || {})[m];
if (!pal || !pal.color) return null;
const h = pal.color.replace('#', '');
const [r, g, b] = [0, 2, 4].map(i => parseInt(h.substr(i, 2), 16) / 255);
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
};
const l = L(ps[0].material || 'eye');
if (l !== null && l < 0.18) continue; // a single very dark sphere is a pupil-only eye
bare.push(`${ps[0].name || 'eye'}@${host}`);
}
if (bare.length)
warns.push(`eye_pupil: ${bare.join(', ')} — one sphere on its own is a flat coloured disc, `
+ `and at reading size a disc is a sticker. An eye reads because of the VALUE STEP `
+ `between a bright iris and a near-black pupil. Add the pupil with `
+ `\`python3 harness/pupils.py <spec.json>\` — it measures where the eyeball actually `
+ `landed before placing it, which hand-picked numbers cannot do.`);
}
// ── 7g. part_names — every part carries its own name, and no two share one.
//
// A material is a CLASS: "this is horn". Many parts share one on purpose, and the
// GLB merges by material precisely so a body with forty plates does not ship forty
// draw calls. That makes a material name structurally incapable of answering "which
// part is this" — the same `paw` material sits on a foot pad AND on a nose-leaf, and
// anything that aggregates by material silently adds the two together.
//
// So identity gets its own channel and the author fills it, because the generator
// already knows what it is emitting at the moment it emits it. `nose_leaf` is a name;
// `spike@Skull` is a description of where a thing was put, and two spikes on one skull
// share it. glb.js then records [first, count] per name, so a name reaches all the way
// into the file without costing a single extra material.
{
const chainNames = new Set(Object.keys(spec.chains || {}));
const seen = new Map();
const unnamed = [], dupes = [], clashes = [];
(spec.parts || []).forEach((p, i) => {
const n = (p.name || '').trim();
if (!n) { unnamed.push(`parts[${i}] (${p.type} on ${p.host || 'ribs'})`); return; }
if (seen.has(n)) dupes.push(n); else seen.set(n, i);
if (chainNames.has(n)) clashes.push(n);
});
if (unnamed.length)
fails.push(`part_names: ${unnamed.length} part(s) have no "name" — ${unnamed.slice(0, 6).join(', ')}`
+ (unnamed.length > 6 ? `, +${unnamed.length - 6} more` : '')
+ `. THE FIX: give every part the name of the THING it is ("nose_leaf", "left_tusk"), not its type `
+ `and host. The material is a class shared by many parts and cannot identify one; this name is what `
+ `checks, the Arena importer and graft.py use to point at a single piece of geometry.`);
if (dupes.length)
fails.push(`part_names: duplicated — ${[...new Set(dupes)].join(', ')}. Two parts with one name is two `
+ `things nothing downstream can tell apart. THE FIX: name them for what they are (left_tusk / `
+ `right_tusk), not what they are made of.`);
if (clashes.length)
fails.push(`part_names: ${[...new Set(clashes)].join(', ')} is already a chain name, and volumes are `
+ `identified by their chain. THE FIX: pick a different name for the part.`);
}
// ── 7h. body_islands — a creature is ONE thing, and one thing is connected.
//
// This exists because a head shipped as a free-floating object: 0.24 m clear of
// the torso surface, every one of its 311 vertices outside the body mesh, held
// to the creature only by two stray vertices of a foreleg that happened to poke
// into it. Nothing caught it. root_containment, limb_clearance and
// part_attachment were all reading a SPHERE through the widest ring instead of
// the surface (fixed — see engine/core/inside.js), and even corrected, all three
// ask a LOCAL question: is this piece seated in ITS host. The failure was global.
// A silhouette cannot see it either: a head floating inside the outline is not a
// hole in the mask. So the global question gets asked directly.
//
// THE WELD TOLERANCE IS 3% OF MODEL HEIGHT, and it is a floor rather than a
// target. Well-built parts sit anywhere from fully embedded to ~3% of height
// off their host, because part_attachment's own bar allows a part to
// TOUCH rather than sink in. There is no gap in that distribution to put a
// threshold in, so this takes the loosest value that is still correct and calls
// anything looser detached. The failure it exists for is 9.3% — three times the
// bar — so a loose floor still catches it by a wide margin. Tightening attachment
// is a separate decision, and it belongs to part_attachment, not here.
if (!spec.qa_isolate) {
const groups = require('./inside.js').islands(meshes, 0.03 * modelH, 3);
if (groups.length > 1) {
const loose = groups.slice(1);
const shown = loose.slice(0, 6).map(g => `[${g.join(', ')}]`).join(' ');
fails.push(`body_islands: this is ${groups.length} separate objects, not one creature. `
+ `Floating free of the main body: ${shown}${loose.length > 6 ? ` +${loose.length - 6} more` : ''}. `
+ `A piece counts as attached when it shares material with something else — `
+ `${(0.03 * modelH).toFixed(3)} m of weld, at three points. Two stray vertices `
+ `poking in is not an attachment, it is a coincidence. THE FIX: move the floating `
+ `piece INTO whatever it is supposed to grow out of, along its own axis; a root is `
+ `meant to be buried, and burying it is what hides the seam as well.`);
}
}
// ── 7f. joint_range — a joint that turns declares how far it turns, the
// declaration is honest about THIS body, and the clips stay inside it.
//
// The numbers are authored, because whoever writes the spec already knows a knee
// bends one way and an elbow does not twist, and that knowledge is impossible to
// compute from vertices. The numbers are then CHECKED, because the author does not
// know how thick this creature's thigh is — a declared limit is a claim about the
// body, and an unverified claim is the thing this release exists to stop.
//
// Three failures, three different fixes, so three different messages:
// undeclared a clip turns a joint that has no entry -> write the entry
// overrun a track leaves its own declared interval -> fix the track or the number
// unreachable the body collides before the limit -> tighten the number
//
// The sweep costs one pass at the declared extreme per axis, which is the same
// order as self_clip's own broad phase. The 8-step ladder that finds the angle it
// ACTUALLY reaches only runs on bounds that already failed, so a clean body pays
// nothing for it.
if (!spec.qa_isolate) {
const SK = require('./skeleton.js');
const mirrorName2L = n => (n.startsWith('R') ? 'L' + n.slice(1) : n);
let ranges = null;
try { ranges = SK.jointRanges(spec, sk); }
catch (e) { fails.push(`joint_range: ${e.message}`); }
if (ranges) {
const AX = SK.RANGE_AXES;
// a limit on a joint that does not exist is a typo doing nothing quietly
const ghosts = Object.keys(spec.joint_range || {}).filter(jn => sk.index[jn] === undefined);
if (ghosts.length)
fails.push(`joint_range: no such joint — ${ghosts.join(', ')}. THE FIX: use the joint names from `
+ `"chains"; a limit on a name nothing owns is silently doing nothing.`);
const turned = new Map(); // joint -> Set(axis) actually animated
for (const a of animsResolved)
for (const [jn, tr] of Object.entries(a.tracksResolved))
for (const ax of AX) if (tr[ax]) {
if (!turned.has(jn)) turned.set(jn, new Set());
turned.get(jn).add(ax);
}
// (a) undeclared
const allUndec = [...turned.keys()].filter(jn => !ranges[jn]);
// a generated R joint disappears the moment its L twin is declared, so asking for it
// by name would send the author to a file that must not contain it
const undec = allUndec.filter(jn => !(jn.startsWith('R') && sk.index[mirrorName2L(jn)] !== undefined
&& allUndec.includes(mirrorName2L(jn)))).sort();
if (undec.length) {
const ex = undec[0], exAx = [...turned.get(ex)][0];
fails.push(`joint_range: ${undec.length} joint(s) are turned by an animation with no declared limit — `
+ undec.slice(0, 8).join(', ') + (undec.length > 8 ? `, +${undec.length - 8} more` : '')
+ `. THE FIX: add a "joint_range" block — { "${ex}": { "${exAx}": [min, max] } } — in DEGREES, in the `
+ `joint's own frame, using the same axis names the tracks use. Write what the ANIMAL can do; an axis `
+ `you leave out is LOCKED at 0, and "free" opts one out. Declare the L side only: R is generated.`);
}
// (b) overrun — keys interpolate linearly, so the key values ARE the extremes
for (const a of animsResolved) {
for (const [jn, tr] of Object.entries(a.tracksResolved)) {
const lim = ranges[jn]; if (!lim) continue;
for (const ax of AX) {
if (!tr[ax] || !lim[ax]) continue;
const [lo, hi] = lim[ax];
const bad = tr[ax].find(([, v]) => v < lo - 1e-6 || v > hi + 1e-6);
if (!bad) continue;
fails.push(`joint_range: "${a.name}" turns ${jn}.${ax} to ${bad[1].toFixed(1)}° at t=${(+bad[0]).toFixed(2)}, `
+ `outside its declared limit [${lo}, ${hi}]. THE FIX: one of the two is wrong, not both — either the `
+ `clip overreaches and the key comes back inside, or the joint really does turn that far and the limit `
+ `was written too tight.`
+ (mirrorName(jn) !== jn && jn.startsWith('R')
? ` (${jn} and its limit are BOTH generated from the L side; edit the L side.)` : ''));
}
}
}
// (c) unreachable — sweep to the declared extreme and see whether the body arrives first
const bodyHJ = Math.max(...allV0.map(v => v[1])) - Math.min(...allV0.map(v => v[1])) || 1;
const hit = g => g != null && g < 0.006 * bodyHJ;
const poseAnim = (jn, ax, deg, tag) =>
({ name: tag, tracksResolved: { [jn]: { [ax]: [[0, 0], [1, deg]] } } });
const bounds = [];
for (const [jn, lim] of Object.entries(ranges)) {
if (!turned.has(jn)) continue; // only limits the clips actually lean on
for (const ax of AX) {
const r = lim[ax]; if (!r) continue;
for (const deg of r) {
if (Math.abs(deg) < 1e-6) continue;
bounds.push({ jn, ax, deg, tag: `${jn}.${ax}@${deg}` });
}
}
}
const sweepAt = list => {
try {
return require('./selfclip.js').selfClip(
spec, sk, locals, meshes, list.map(b => poseAnim(b.jn, b.ax, b.deg, b.tag)),
1, 4, 0.15 * bodyHJ);
} catch (e) { return []; }
};
if (bounds.length) {
const first = new Map();
for (const r of sweepAt(bounds)) if (hit(r.gap)) first.set(r.clip, r);
for (const b of bounds) {
const r = first.get(b.tag); if (!r) continue;
// ladder, only for the bounds that already failed: the largest fraction of the
// declared angle this body can actually hold.
let safe = 0;
for (let k = 7; k >= 1; k--) {
const frac = k / 8;
const res = sweepAt([{ jn: b.jn, ax: b.ax, deg: b.deg * frac, tag: 'L' }]);
if (!hit((res[0] || {}).gap)) { safe = b.deg * frac; break; }
}
fails.push(`joint_range: ${b.jn}.${b.ax} is declared to ${b.deg}°, but this body stops first — `
+ `"${r.a}" reaches "${r.b}" (${r.gap.toFixed(3)} m apart, from ${r.rest.toFixed(2)} m at rest). `
+ `A limit is a claim about THIS creature, not about the species. THE FIX: set the limit to `
+ `${safe.toFixed(0)}°, which is the last angle that clears, or move the geometry that is in the way. `
+ `Leaving the number means every clip authored against it interpenetrates.`);
}
}
}
}
// ── 7e. self_clip — the swept volume must not go through the creature itself.
// Joint limits say what one joint MAY do; they say nothing about where the chain ends up.
// A windup can stay inside legal angles the whole time and still swing a carried part
// through the creature's own leg — which is easy to miss by eye.
if (!spec.qa_isolate) {
let res = null;
const bodyH0 = Math.max(...allV0.map(v => v[1])) - Math.min(...allV0.map(v => v[1])) || 1;
try { res = require('./selfclip.js').selfClip(spec, sk, locals, meshes, animsResolved, 32, 4, 0.15 * bodyH0); }
catch (e) { res = null; }
for (const r of (res || [])) {
if (r.gap == null) continue;
const bodyH2 = Math.max(...allV0.map(v => v[1])) - Math.min(...allV0.map(v => v[1])) || 1;
if (r.gap < 0.006 * bodyH2)
fails.push(`self_clip: in "${r.clip}" at t=${r.t.toFixed(2)}, "${r.a}" comes within `
+ `${r.gap.toFixed(3)} m of "${r.b}" — they are ${r.rest.toFixed(2)} m apart at rest, and they are `
+ `not neighbours on the skeleton, so this is the animation driving one through the other. `
+ `THE FIX: change the PLANE the part travels in, not the amount. A weapon that cannot wind `
+ `straight back goes out to the side; a limb that sweeps through the body gets lifted over it `
+ `(hoist the load above the shoulder before slewing, the way a crane actually works).`);
}
}
// ── 7d. clip_closes / ground_clip / attack_windup / effector_leads ──────────
//
// Four checks that all need the same thing: the mesh, skinned, at sampled times.
// They are grouped so the skinning is paid for once.
{
const groundY = Math.min(...allV0.map(v => v[1]));
const bodyH = Math.max(...allV0.map(v => v[1])) - groundY || 1;
const N = 32;
const declared = spec.function || {};
const effChains = new Set(Object.entries(declared).filter(([, v]) => v === 'effector').map(([k]) => k));
const labOf = m => `${m.material}@${m.chain || m.part || '?'}`;
// A part (a claw, a blade, a spike) carries no chain of its own — it hangs off a joint.
// Find that joint from the skin weights and ask which chain the joint belongs to, so
// "function": {"neck": "effector"} covers the blade bolted to the neck without the
// designer having to name every part. Declaring the part's own name works too.
const jointChain = {};
for (const [cn, js] of Object.entries(spec.chains || {})) for (const j of js) jointChain[j] = cn;
const chainOfMesh = m => {
if (m.chain) return m.chain;
const tally = {};
for (const w of (m.skin || [])) if (w && w[0]) tally[w[0][0]] = (tally[w[0][0]] || 0) + 1;
const bone = Object.keys(tally).sort((a, b) => tally[b] - tally[a])[0];
return bone ? jointChain[bone] : null;
};
const isEff = m => effChains.has(chainOfMesh(m))
|| (m.part && effChains.has(String(m.part).split('@').pop()))
|| effChains.has(m.material);
for (const a of animsResolved) {
const frames = [];
for (let f = 0; f <= N; f++) frames.push(jointWorlds(sk, locals, a, f / N));
// clip_closes — a clip that does not loop still SNAPS back when it ends.
// If the last frame is not the first frame, that snap is a visible pop.
{
let worst = 0, who = '';
for (const j of sk.joints) {
const i = sk.index[j.name]; if (i == null) continue;
const p0 = matVec(frames[0][i], [0, 0, 0]), p1 = matVec(frames[N][i], [0, 0, 0]);
const d = Math.hypot(p0[0] - p1[0], p0[1] - p1[1], p0[2] - p1[2]);
if (d > worst) { worst = d; who = j.name; }
}
if (worst > 0.05 * bodyH)
fails.push(`clip_closes: "${a.name}" ends ${worst.toFixed(2)} m away from where it starts `
+ `(joint "${who}"; the ceiling is ${(0.05 * bodyH).toFixed(2)} m = 5% of the body). The clip does not `
+ `loop, so when it finishes the creature TELEPORTS back to the rest pose. `
+ `THE FIX: give every track a final key equal to its first key — the action must recover, `
+ `not freeze mid-lunge.`);
}
// ground_clip — nothing may go below the plane the creature stands on.
// The collision proxy is built from the mesh, so a hand or a claw that spends the
// clip under the floor is a hand the physics engine will push the whole body up off.
{
let deep = 0, who = '';
for (const m of meshes) for (let f = 0; f <= N; f += 2) {
const V = skinVerts(m, sk, frames[f]);
for (const v of V) if (v[1] - groundY < deep) { deep = v[1] - groundY; who = labOf(m); }
}
if (deep < -0.02 * bodyH)
fails.push(`ground_clip: "${a.name}" drives "${who}" ${(-deep).toFixed(3)} m BELOW the ground plane `
+ `(the ceiling is ${(0.02 * bodyH).toFixed(3)} m). The ground is the lowest point of the bind pose; `
+ `anything under it is inside the floor. THE FIX: this is arithmetic, not posing — measure the `
+ `penetration per frame and add it to the ROOT's "ty" track. Chasing it with joint angles does not `
+ `converge, because a contact point rotating about a joint above it always dips below the tangent plane.`);
}
if (a.name !== 'attack') continue;
// The frame the attack reaches furthest forward. That is the frame that lands the
// hit, and the only frame whose silhouette anyone judges.
let peakF = 0, peakZ = -Infinity;
const frontOf = f => {
let z = -Infinity, who = '';
for (const m of meshes) { const V = skinVerts(m, sk, frames[f]); for (const v of V) if (v[2] > z) { z = v[2]; who = labOf(m); } }
return [z, who];
};
for (let f = 0; f <= N; f++) { const [z] = frontOf(f); if (z > peakZ) { peakZ = z; peakF = f; } }
// attack_windup — a strike winds BACK (or out to the side) before it commits.
// Straight-line push reads as a shove, and gives the physics nothing to load against.
{
let bestM = null, bestI = 0, best = -Infinity;
for (const m of meshes) {
if (effChains.size && !isEff(m)) continue;
for (let f = 0; f <= N; f++) { const V = skinVerts(m, sk, frames[f]);
for (let i = 0; i < V.length; i++) { const d = V[i][2] - m.V[i][2]; if (d > best) { best = d; bestM = m; bestI = i; } } }
}
if (bestM) {
const zs = [], xs = [];
for (let f = 0; f <= N; f++) { const V = skinVerts(bestM, sk, frames[f]); zs.push(V[bestI][2]); xs.push(V[bestI][0]); }
const zi = zs.indexOf(Math.max(...zs));
const back = zs[0] - Math.min(...zs.slice(0, zi + 1));
const lat = Math.max(...xs.slice(0, zi + 1)) - Math.min(...xs.slice(0, zi + 1));
const tot = Math.max(...zs) - Math.min(...zs) || 1e-6;
if (back < 0.05 * tot && lat < 0.15 * tot)
fails.push(`attack_windup: "${labOf(bestM)}" travels ${tot.toFixed(2)} m but never winds up — `
+ `it pulls back ${(100 * back / tot).toFixed(0)}% (needs 5%) and swings sideways `
+ `${(100 * lat / tot).toFixed(0)}% (needs 15%). A strike loads before it commits. `
+ `If the structure cannot pull straight back — the weapon would sweep through the body — `
+ `take it out to the SIDE and bring it round instead. Either route satisfies this.`);
}
}
// effector_leads — at the moment of furthest reach, the declared effector must be
// the frontmost thing on the creature. Otherwise the strike reads as whatever IS in
// front: a head-butt when it was meant to be a kick.
if (effChains.size) {
let effZ = -Infinity, othZ = -Infinity, othWho = '';
for (const m of meshes) { const V = skinVerts(m, sk, frames[peakF]);
let z = -Infinity; for (const v of V) if (v[2] > z) z = v[2];
if (isEff(m)) { if (z > effZ) effZ = z; } else if (z > othZ) { othZ = z; othWho = labOf(m); } }
if (effZ === -Infinity)
warns.push(`effector_leads: "function" declares effector chain(s) `
+ `${[...effChains].map(c => `"${c}"`).join(', ')} but no mesh belongs to them.`);
else if (effZ <= othZ)
fails.push(`effector_leads: at the frame the attack reaches furthest (t=${(peakF / N).toFixed(2)}), `
+ `the frontmost part is "${othWho}" at z=${othZ.toFixed(2)}, ahead of the declared effector at `
+ `z=${effZ.toFixed(2)}. Whatever is in front is what the strike reads as. `
+ `THE FIX: either the effector has to reach further — rotate the BASE the effector hangs off `
+ `(pitching the whole torso back sends the legs forward far better than extending the legs does) `
+ `— or "${othWho}" has to get out of the way. A part that keeps its own world aim while the body `
+ `turns will stick out; aim it only as far as leaves the effector in front.`);
}
}
}
return { fails, warns };
}
module.exports = { runChecks, foldCount, skinVerts, jointWorlds };