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
// Rig report — read a GLB's glTF JSON chunk and answer the one question every
// creator asks before they upload: "will this thing actually move on three.ws?"
//
// The answer has always existed, but only after an upload, a conversion, and a
// look at the result. That is a slow, discouraging loop, and the failure mode is
// silent: a rig whose bones are named `Bip001 L UpperArm` loads fine, renders
// fine, and then stands in a frozen T-pose forever because the clip library's
// tracks address `LeftArm`. This module moves that verdict to the front of the
// funnel and makes it local.
//
// Everything here is a pure function of the GLB bytes. No network, no WebGL, no
// DOM. That is what lets the browser run it on a file the user never uploads,
// and what lets the test suite run it on fixtures without a headless GPU.
//
// The verdict deliberately mirrors AnimationManager's runtime gate
// (`_modelSupportsCanonicalClips`: a SkinnedMesh plus >= MIN_CANONICAL_BONES
// name-mapped joints) rather than approximating it. If this file and that gate
// ever disagree, this file is wrong: the runtime is the product.
import { canonicalizeBoneName, CANONICAL_BONES } from './glb-canonicalize.js';
const GLB_MAGIC = 0x46546c67; // 'glTF' little-endian
const CHUNK_TYPE_JSON = 0x4e4f534a; // 'JSON'
/** Mirrors MIN_CANONICAL_BONES in src/animation-manager.js. */
export const MIN_CANONICAL_BONES = 8;
/** Total joints in the canonical set, so coverage reads as a real fraction. */
export const CANONICAL_TOTAL = CANONICAL_BONES.length;
// Limb groups, in the order a person reads a body. Each group is scored on its
// own because "62% covered" tells a creator nothing actionable, while "arms and
// torso yes, legs no" tells them their character will glide instead of walk.
// The `key` bones are the ones whose absence is visible in motion; finger joints
// are counted but never gate a group, since a walk cycle survives without them.
export const LIMB_GROUPS = Object.freeze([
{
id: 'torso',
label: 'Torso',
blurb: 'Root motion, sway, and the anchor every other track hangs off.',
bones: ['Hips', 'Spine', 'Spine1', 'Spine2', 'Neck', 'Head'],
key: ['Hips'],
},
{
id: 'arms',
label: 'Arms',
blurb: 'Waves, claps, gestures. Unmapped arms freeze at the bind pose.',
bones: ['LeftShoulder', 'LeftArm', 'LeftForeArm', 'LeftHand', 'RightShoulder', 'RightArm', 'RightForeArm', 'RightHand'],
key: ['LeftArm', 'LeftForeArm', 'RightArm', 'RightForeArm'],
},
{
id: 'hands',
label: 'Hands',
blurb: 'Finger joints. Required for sign language and detailed emotes.',
bones: CANONICAL_BONES.filter((b) => /Hand(Index|Middle|Pinky|Ring|Thumb)/.test(b)),
key: ['LeftHandIndex1', 'RightHandIndex1'],
},
{
id: 'legs',
label: 'Legs',
blurb: 'Walk and run cycles. Without these the avatar slides across the floor.',
bones: ['LeftUpLeg', 'LeftLeg', 'LeftFoot', 'LeftToeBase', 'RightUpLeg', 'RightLeg', 'RightFoot', 'RightToeBase'],
key: ['LeftUpLeg', 'LeftLeg', 'RightUpLeg', 'RightLeg'],
},
]);
// Skeleton-convention fingerprints, most specific first. `test` sees the raw
// joint-name list plus the node/mesh names, because some conventions are only
// identifiable from what surrounds the skeleton (Ready Player Me ships Mixamo
// bone names and is distinguishable solely by its `Wolf3D_*` mesh nodes).
//
// `schema` maps onto the avatar-manifest `skeleton` enum
// (packages/avatar-schema/schema/avatar.v1.json), so the generated manifest
// declares the right value instead of defaulting everything to `custom`.
export const CONVENTIONS = [
{
id: 'rpm', label: 'Ready Player Me', schema: 'rpm',
test: (ctx) => ctx.meshNames.some((n) => /^Wolf3D_/i.test(n)) && ctx.joints.some((n) => /Hips$/i.test(n)),
evidence: 'Wolf3D_* mesh nodes alongside a Mixamo-named skeleton',
},
{
id: 'mixamo', label: 'Mixamo', schema: 'mixamo',
test: (ctx) => ctx.joints.some((n) => /^mixamorig\d*[_:]/i.test(n)),
evidence: 'mixamorig: joint prefix',
},
{
id: 'vrm', label: 'VRM / VRoid', schema: 'vrm-humanoid',
test: (ctx) => ctx.joints.some((n) => /^J_(Bip|Sec|Adj)_/i.test(n)),
evidence: 'J_Bip_* humanoid joint names',
},
{
id: 'mmd', label: 'MikuMikuDance (PMX/PMD)', schema: 'custom',
test: (ctx) => ctx.joints.some((n) => /^(センター|上半身2?|下半身|[左右](腕|ひじ|ひざ|手首|足首))$/.test(n)),
evidence: 'Japanese PMX bone names (センター / 上半身 / 左腕)',
},
{
id: 'apple-joint', label: 'Apple / ARKit joint suffix', schema: 'custom',
test: (ctx) => ctx.joints.filter((n) => /_joint$/i.test(n)).length >= 4,
evidence: 'four or more skeleton joints with the _joint suffix',
},
{
id: 'kinect', label: 'Kinect / Azure Kinect', schema: 'custom',
test: (ctx) => ctx.joints.some((n) => /^Spine(Base|Mid|Shoulder)$/i.test(n)) && ctx.joints.some((n) => /^(Shoulder|Elbow|Knee)(Left|Right)$/i.test(n)),
evidence: 'SpineBase/SpineMid plus full trailing-side limb names',
},
{
id: 'mediapipe', label: 'MediaPipe Pose', schema: 'custom',
test: (ctx) => ctx.joints.some((n) => /^(left|right)_foot_index$/i.test(n)) && ctx.joints.some((n) => /^(left|right)_heel$/i.test(n)),
evidence: 'foot_index and heel landmark joints',
},
{
id: 'reallusion', label: 'Reallusion Character Creator', schema: 'custom',
test: (ctx) => ctx.joints.some((n) => /^CC_Base_/i.test(n)),
evidence: 'CC_Base_* joint prefix',
},
{
id: 'unreal', label: 'Unreal Engine mannequin', schema: 'custom',
test: (ctx) => ctx.joints.some((n) => /^pelvis$/i.test(n)) && ctx.joints.some((n) => /^(thigh|calf|clavicle|upperarm)_[lr]$/i.test(n)),
evidence: 'pelvis / thigh_l / clavicle_l mannequin naming',
},
{
id: 'source', label: 'Source engine (ValveBiped)', schema: 'custom',
test: (ctx) => ctx.joints.some((n) => /^ValveBiped\.?Bip\d+/i.test(n)),
evidence: 'ValveBiped.Bip01_* joint prefix',
},
{
id: 'biped', label: '3ds Max Biped', schema: 'custom',
test: (ctx) => ctx.joints.some((n) => /^Bip\d+[\s_]/i.test(n)),
evidence: 'Bip01/Bip001 joint prefix',
},
{
id: 'rigify', label: 'Blender Rigify', schema: 'custom',
test: (ctx) => ctx.joints.some((n) => /^(DEF|ORG|MCH)[-_]/i.test(n)),
evidence: 'DEF-/ORG-/MCH- Rigify bone layers',
},
{
id: 'humanik', label: 'Autodesk HumanIK / MotionBuilder', schema: 'custom',
test: (ctx) => ctx.joints.filter((n) => /^[A-Za-z]\w*:/.test(n) && !/^mixamorig/i.test(n)).length >= 4,
evidence: 'character-namespaced joints (Character1:Hips)',
},
{
id: 'daz', label: 'Daz Genesis', schema: 'custom',
test: (ctx) => ctx.joints.some((n) => /^(lShldr|rShldr|abdomen|lThigh|rThigh)/i.test(n)),
evidence: 'Daz lShldr / abdomen / lThigh naming',
},
{
id: 'makehuman', label: 'MakeHuman / Blender side-suffix', schema: 'custom',
test: (ctx) => ctx.joints.filter((n) => /\.[LR]$/.test(n)).length >= 4,
evidence: 'Blender .L/.R side suffixes',
},
{
id: 'avaturn', label: 'Avaturn / three.ws canonical', schema: 'avaturn',
test: (ctx) => {
const set = new Set(ctx.joints);
return ['Hips', 'Spine2', 'LeftUpLeg', 'RightForeArm'].every((b) => set.has(b));
},
evidence: 'joint names already match the canonical set exactly',
},
];
/**
* How many authoring conventions the fingerprinter knows. The Rig Doctor page
* advertises this number in its hero, and a hand-typed copy of it went stale
* the first time a convention was added, so the page reads it from here.
*/
export const CONVENTION_COUNT = CONVENTIONS.length;
// Oculus/OVR viseme set — what the lip-sync pipeline drives. An avatar missing
// these can still animate; it just cannot speak with its mouth.
const OVR_VISEMES = ['viseme_sil', 'viseme_PP', 'viseme_FF', 'viseme_TH', 'viseme_DD', 'viseme_kk', 'viseme_CH', 'viseme_SS', 'viseme_nn', 'viseme_RR', 'viseme_aa', 'viseme_E', 'viseme_I', 'viseme_O', 'viseme_U'];
// A representative ARKit blendshape slice. Presence of these means the face can
// be driven expressively (brows, jaw, smile) rather than just phonetically.
const ARKIT_SAMPLE = ['jawOpen', 'mouthSmileLeft', 'mouthSmileRight', 'browInnerUp', 'eyeBlinkLeft', 'eyeBlinkRight'];
/**
* Read the glTF JSON chunk out of a GLB ArrayBuffer.
* Kept separate from analysis so a caller can inspect the raw document.
*
* @param {ArrayBuffer} buffer
* @returns {{ json: object, jsonBytes: number, binBytes: number }}
* @throws {Error} with a message written for a human, not a stack trace
*/
export function readGlbJson(buffer) {
if (!(buffer instanceof ArrayBuffer)) throw new TypeError('readGlbJson: ArrayBuffer required');
if (buffer.byteLength < 20) throw new Error('This file is too small to be a GLB.');
const view = new DataView(buffer);
if (view.getUint32(0, true) !== GLB_MAGIC) {
throw new Error('Not a binary glTF. Export as .glb (binary), not .gltf (JSON) or .fbx.');
}
if (view.getUint32(4, true) !== 2) throw new Error('Only glTF 2.0 binaries are supported.');
const c0Len = view.getUint32(12, true);
if (view.getUint32(16, true) !== CHUNK_TYPE_JSON) throw new Error('Malformed GLB: the first chunk is not JSON.');
if (20 + c0Len > buffer.byteLength) throw new Error('Malformed GLB: the JSON chunk runs past the end of the file.');
let json;
try {
json = JSON.parse(new TextDecoder().decode(new Uint8Array(buffer, 20, c0Len)));
} catch (err) {
throw new Error(`Malformed GLB: the JSON chunk did not parse (${err.message}).`);
}
const binOffset = 20 + c0Len;
const binBytes = binOffset + 8 <= buffer.byteLength ? view.getUint32(binOffset, true) : 0;
return { json, jsonBytes: c0Len, binBytes };
}
// Every node index reachable from skins[].joints[]. This is the authoritative
// definition of "is a bone" — a node named `Head` that no skin references is a
// prop, and counting it would inflate coverage on a rig that cannot deform.
function jointNodeIndices(json) {
const set = new Set();
for (const skin of json.skins || []) {
for (const j of skin.joints || []) set.add(j);
}
return set;
}
// Slice the BIN chunk out of a GLB ArrayBuffer, the same chunk-1 offset math
// glb-canonicalize.js's canonicalizeGLBBones uses: 20 bytes of header + the
// (already 4-byte-padded) JSON chunk length lands exactly on chunk 1's own
// 8-byte length/type header. Returns null for a file with no BIN chunk at all
// (a skinless, texture-free, or data-URI-only GLB).
function readGlbBin(buffer, jsonBytes) {
const c1Offset = 20 + jsonBytes;
if (c1Offset + 8 > buffer.byteLength) return null;
const view = new DataView(buffer);
const c1Len = view.getUint32(c1Offset, true);
return new Uint8Array(buffer, c1Offset + 8, c1Len);
}
const ACCESSOR_COMPONENT_BYTES = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 };
// Divisors for KHR-normalized integer accessors (glTF 2.0 §3.6.2.3): an
// UNSIGNED_BYTE weight of 255 means 1.0, an UNSIGNED_SHORT weight of 65535
// means 1.0. JOINTS_0 is never normalized (its ints are bone indices).
const ACCESSOR_NORMALIZE_MAX = { 5120: 127, 5121: 255, 5122: 32767, 5123: 65535 };
// Read one VEC4 accessor (JOINTS_0/WEIGHTS_0 and any JOINTS_n/WEIGHTS_n set
// above 0) into `count` rows of 4 numbers. Returns null for anything this
// reader cannot safely walk (no bufferView, an unsupported componentType, or
// a sparse accessor). Skin-weight attributes are not sparse in practice, and
// a report that skipped the rare case is safer than one that misreads it.
function readVec4Accessor(json, bin, accessorIndex) {
const accessor = json.accessors?.[accessorIndex];
if (!accessor || accessor.sparse || typeof accessor.bufferView !== 'number') return null;
const view = json.bufferViews?.[accessor.bufferView];
const compBytes = ACCESSOR_COMPONENT_BYTES[accessor.componentType];
if (!view || !bin || !compBytes) return null;
const stride = view.byteStride || compBytes * 4;
const base = (view.byteOffset || 0) + (accessor.byteOffset || 0);
if (base + stride * Math.max(0, accessor.count - 1) + compBytes * 4 > bin.byteLength) return null;
const dv = new DataView(bin.buffer, bin.byteOffset + base);
const normMax = accessor.normalized ? ACCESSOR_NORMALIZE_MAX[accessor.componentType] : null;
const rows = [];
for (let i = 0; i < accessor.count; i++) {
const row = [];
for (let c = 0; c < 4; c++) {
const o = i * stride + c * compBytes;
let v;
switch (accessor.componentType) {
case 5120: v = dv.getInt8(o); break;
case 5121: v = dv.getUint8(o); break;
case 5122: v = dv.getInt16(o, true); break;
case 5123: v = dv.getUint16(o, true); break;
case 5125: v = dv.getUint32(o, true); break;
default: v = dv.getFloat32(o, true); break;
}
row.push(normMax ? v / normMax : v);
}
rows.push(row);
}
return rows;
}
// Per-vertex skin-weight health, the question canonical joint coverage can't
// answer: a non-humanoid rig (UniRig/SkinTokens, AniGen) has no canonical
// names to map at all, so its drivability hinges entirely on whether every
// vertex actually got a weight. Walks every JOINTS_n/WEIGHTS_n set a skinned
// primitive declares (glTF allows more than one set for >4 influences per
// vertex) and reports the heaviest influence count seen and how many
// vertices came back with no weight on any joint, a sign the predictor's
// skinning step missed geometry the mesh step produced.
function analyzeSkinWeights(json, bin) {
const skinnedMeshIdx = new Set();
for (const node of json.nodes || []) {
if (node.skin != null && node.mesh != null) skinnedMeshIdx.add(node.mesh);
}
let maxInfluences = 0;
let unweightedVertices = 0;
let totalVertices = 0;
for (const meshIdx of skinnedMeshIdx) {
for (const prim of json.meshes?.[meshIdx]?.primitives || []) {
const sets = Object.keys(prim.attributes || {})
.map((k) => /^JOINTS_(\d+)$/.exec(k)?.[1])
.filter((n) => n != null)
.map(Number)
.sort((a, b) => a - b);
if (!sets.length) continue;
const weightRows = sets.map((n) => readVec4Accessor(json, bin, prim.attributes[`WEIGHTS_${n}`]));
if (weightRows.some((rows) => !rows)) continue;
const vertexCount = weightRows[0].length;
for (let v = 0; v < vertexCount; v++) {
let influences = 0;
for (const rows of weightRows) {
for (const w of rows[v]) if (w > 1e-6) influences++;
}
totalVertices++;
if (influences === 0) unweightedVertices++;
if (influences > maxInfluences) maxInfluences = influences;
}
}
}
return { maxInfluences, unweightedVertices, totalVertices };
}
export function detectConvention(ctx) {
for (const c of CONVENTIONS) {
let hit = false;
try {
hit = c.test(ctx);
} catch {
hit = false;
}
if (hit) return { id: c.id, label: c.label, schema: c.schema, evidence: c.evidence };
}
return { id: 'unknown', label: 'Unrecognised', schema: 'custom', evidence: 'no known vendor fingerprint in the joint names' };
}
// Triangles across every primitive, honouring the glTF `mode` enum: only modes
// 4/5/6 (TRIANGLES, STRIP, FAN) produce triangles, and strips/fans yield
// count-2 rather than count/3. Getting this wrong would misreport a stylised
// low-poly avatar as three times heavier than it is.
function countGeometry(json) {
const accessors = json.accessors || [];
let triangles = 0;
let vertices = 0;
let primitives = 0;
for (const mesh of json.meshes || []) {
for (const prim of mesh.primitives || []) {
primitives++;
const posIdx = prim.attributes?.POSITION;
const vcount = posIdx != null ? accessors[posIdx]?.count || 0 : 0;
vertices += vcount;
const mode = prim.mode == null ? 4 : prim.mode;
const elements = prim.indices != null ? accessors[prim.indices]?.count || 0 : vcount;
if (mode === 4) triangles += Math.floor(elements / 3);
else if (mode === 5 || mode === 6) triangles += Math.max(0, elements - 2);
}
}
return { triangles, vertices, primitives, meshes: (json.meshes || []).length };
}
function collectTextures(json) {
const views = json.bufferViews || [];
return (json.images || []).map((img, i) => {
const bytes = img.bufferView != null ? views[img.bufferView]?.byteLength || 0 : 0;
return {
index: i,
name: img.name || `image_${i}`,
mimeType: img.mimeType || (img.uri ? guessMime(img.uri) : 'unknown'),
bytes,
external: !!img.uri && !/^data:/i.test(img.uri),
};
});
}
function guessMime(uri) {
if (/^data:([^;,]+)/i.test(uri)) return uri.match(/^data:([^;,]+)/i)[1];
if (/\.png$/i.test(uri)) return 'image/png';
if (/\.jpe?g$/i.test(uri)) return 'image/jpeg';
if (/\.webp$/i.test(uri)) return 'image/webp';
if (/\.ktx2$/i.test(uri)) return 'image/ktx2';
return 'unknown';
}
// Morph-target names live on mesh.extras.targetNames (the glTF convention every
// major exporter follows) rather than on the targets themselves. Union them
// across meshes so a head-and-body split avatar reports one coherent set.
function collectMorphs(json) {
const names = new Set();
for (const mesh of json.meshes || []) {
const fromMesh = mesh.extras?.targetNames;
if (Array.isArray(fromMesh)) fromMesh.forEach((n) => typeof n === 'string' && names.add(n));
for (const prim of mesh.primitives || []) {
const fromPrim = prim.extras?.targetNames;
if (Array.isArray(fromPrim)) fromPrim.forEach((n) => typeof n === 'string' && names.add(n));
}
}
const list = [...names];
const lower = new Set(list.map((n) => n.toLowerCase()));
const visemes = OVR_VISEMES.filter((v) => lower.has(v.toLowerCase()));
const arkit = ARKIT_SAMPLE.filter((v) => lower.has(v.toLowerCase()));
return {
total: list.length,
names: list,
visemes,
visemeCount: visemes.length,
visemeComplete: visemes.length === OVR_VISEMES.length,
arkit,
arkitCount: arkit.length,
lipSync: visemes.length >= 8,
};
}
/**
* Full diagnostic for a GLB, ready to render.
*
* @param {ArrayBuffer} buffer raw .glb bytes
* @param {{ fileName?: string }} [opts]
* @returns {object} report; never throws for a readable GLB
* @throws {Error} only when the bytes are not a readable glTF 2.0 binary
*/
export function analyzeGlb(buffer, opts = {}) {
const { json, jsonBytes, binBytes } = readGlbJson(buffer);
const nodes = json.nodes || [];
const jointIdx = jointNodeIndices(json);
const skinWeights = analyzeSkinWeights(json, readGlbBin(buffer, jsonBytes));
// Skinned = at least one mesh primitive is bound to a skin. This is the
// glTF-level equivalent of three.js's `node.isSkinnedMesh` check, which the
// runtime gate uses; a skinless mesh cannot be deformed by any clip.
const skinned = nodes.some((n) => n.skin != null && n.mesh != null);
const joints = [...jointIdx].map((i) => nodes[i]?.name || '').filter(Boolean);
const meshNames = nodes.filter((n) => n.mesh != null).map((n) => n.name || '');
// canonical → the first source joint that claimed it. Later duplicates are
// recorded as collisions rather than silently overwriting, because a rig
// with two nodes both mapping to `Hips` is a real authoring bug worth naming.
const mapped = new Map();
const collisions = [];
const unmapped = [];
const renames = [];
for (const name of joints) {
const canonical = canonicalizeBoneName(name);
if (!canonical) {
unmapped.push(name);
continue;
}
if (mapped.has(canonical)) collisions.push({ canonical, names: [mapped.get(canonical), name] });
else mapped.set(canonical, name);
if (name !== canonical) renames.push({ from: name, to: canonical });
}
const convention = detectConvention({ joints, meshNames, json });
const groups = LIMB_GROUPS.map((g) => {
const have = g.bones.filter((b) => mapped.has(b));
const keyHave = g.key.filter((b) => mapped.has(b));
return {
id: g.id,
label: g.label,
blurb: g.blurb,
have: have.length,
total: g.bones.length,
pct: g.bones.length ? Math.round((have.length / g.bones.length) * 100) : 0,
driven: keyHave.length === g.key.length,
missingKey: g.key.filter((b) => !mapped.has(b)),
};
});
const geometry = countGeometry(json);
const textures = collectTextures(json);
const morphs = collectMorphs(json);
const animations = (json.animations || []).map((a, i) => ({
name: a.name || `animation_${i}`,
channels: (a.channels || []).length,
}));
const drivable = skinned && mapped.size >= MIN_CANONICAL_BONES;
const report = {
fileName: opts.fileName || 'model.glb',
bytes: buffer.byteLength,
jsonBytes,
binBytes,
generator: json.asset?.generator || 'unknown',
gltfVersion: json.asset?.version || '2.0',
extensions: [...new Set([...(json.extensionsUsed || []), ...(json.extensionsRequired || [])])].sort(),
extensionsRequired: json.extensionsRequired || [],
counts: {
nodes: nodes.length,
meshes: geometry.meshes,
materials: (json.materials || []).length,
textures: (json.textures || []).length,
images: textures.length,
skins: (json.skins || []).length,
animations: animations.length,
},
geometry,
textures,
textureBytes: textures.reduce((sum, t) => sum + t.bytes, 0),
morphs,
animations,
skeleton: {
skinned,
jointCount: joints.length,
joints,
convention,
mapped: mapped.size,
total: CANONICAL_TOTAL,
pct: Math.round((mapped.size / CANONICAL_TOTAL) * 100),
mappedNames: Object.fromEntries(mapped),
unmapped,
collisions,
renames,
groups,
maxInfluences: skinWeights.maxInfluences,
unweightedVertices: skinWeights.unweightedVertices,
skinnedVertices: skinWeights.totalVertices,
},
};
report.verdict = buildVerdict(report, drivable);
return report;
}
// The verdict is the whole product: one sentence a creator can act on, plus the
// specific reasons behind it. Ordering matters — the first blocker a creator can
// actually fix should be the first thing they read.
function buildVerdict(report, drivable) {
const s = report.skeleton;
const notes = [];
const fixes = [];
if (!s.skinned) {
return {
level: 'fail',
headline: 'This model has no skinned mesh, so no clip can deform it.',
detail: 'three.ws will still display it, but it will render as a static prop and every animation control is hidden.',
notes: [s.jointCount ? `${s.jointCount} joints found, but no mesh is bound to a skin.` : 'No skin definitions at all.'],
fixes: ['Re-export with skinning enabled, or host the mesh and run it through the auto-rigger (POST /api/forge?action=rig with a glb_url) to get a humanoid skeleton bound to it.'],
drivable: false,
};
}
if (!drivable) {
// A non-humanoid rig (a creature, a prop, anything UniRig/SkinTokens or
// AniGen rigged) never maps canonical joints and lands here by design;
// its own drivability question isn't "does the clip library retarget"
// but "did the skinning step actually weight every vertex it rigged".
const failNotes = [
`Detected convention: ${s.convention.label} (${s.convention.evidence}).`,
s.unmapped.length ? `${s.unmapped.length} joint names were not recognised, including ${s.unmapped.slice(0, 3).join(', ')}.` : 'The skeleton has very few joints.',
];
if (s.skinnedVertices > 0) {
failNotes.push(
s.unweightedVertices > 0
? `${s.unweightedVertices} of ${s.skinnedVertices} skinned vertices have no joint influence at all (max ${s.maxInfluences} influences elsewhere).`
: `Every one of ${s.skinnedVertices} skinned vertices has a joint influence (up to ${s.maxInfluences} at once), so the skin itself is sound even though no canonical bone mapped.`,
);
}
return {
level: 'fail',
headline: `Only ${s.mapped} of this rig's joints map to the canonical skeleton, under the ${MIN_CANONICAL_BONES} needed to drive a clip.`,
detail: 'three.ws falls back to the default rig for models like this rather than leaving them in a T-pose, so your own mesh will not be the one moving.',
notes: failNotes,
fixes: [
'Rename the joints to the canonical set below, or let the auto-rigger rebuild the skeleton (POST /api/forge?action=rig).',
'If this is a common rig convention we should already know, the unmapped names below are exactly what belongs in src/glb-canonicalize.js.',
],
drivable: false,
};
}
const frozen = s.groups.filter((g) => !g.driven);
if (frozen.length) {
for (const g of frozen) {
notes.push(`${g.label}: ${g.have}/${g.total} joints mapped, missing ${g.missingKey.join(', ')}.`);
}
fixes.push('Rename the missing joints listed under Coverage. Every other group will animate regardless.');
if (frozen.some((g) => g.id === 'legs')) fixes.push('Legs specifically: without them a walk cycle plays as a slide. This is the most-reported rig complaint.');
return {
level: 'warn',
headline: `This rig animates, but ${frozen.map((g) => g.label.toLowerCase()).join(' and ')} will not move.`,
detail: `${s.mapped} of ${s.total} canonical joints mapped. Clips retarget onto the joints that resolved and leave the rest at their authored bind pose.`,
notes,
fixes,
drivable: true,
};
}
notes.push(`${s.mapped} of ${s.total} canonical joints mapped from a ${s.convention.label} rig.`);
if (report.morphs.lipSync) notes.push(`${report.morphs.visemeCount} visemes present, so lip-sync will work too.`);
else notes.push('No viseme blendshapes, so this avatar animates but cannot lip-sync.');
if (!report.morphs.lipSync) fixes.push('Add the 15 Oculus visemes (viseme_aa, viseme_PP, …) if you want speech.');
if (report.geometry.triangles > 150000) fixes.push(`${report.geometry.triangles.toLocaleString()} triangles is heavy for a web avatar. Decimate toward 60k for smooth mobile playback.`);
if (report.textureBytes > 12 * 1024 * 1024) fixes.push('Textures exceed 12 MB. Compress with KTX2/Basis to cut first-load time.');
return {
level: 'pass',
headline: 'Every limb group is drivable. This rig performs the full clip library.',
detail: 'Torso, arms, hands, and legs all resolved to canonical joints, so retargeted clips will move the whole character.',
notes,
fixes,
drivable: true,
};
}
/**
* Build a schema-v1 avatar manifest skeleton from a report. Everything the
* report can know is filled in; the caller supplies identity (id/name/owner)
* and the public mesh URI, which no local file can provide.
*
* @param {object} report from analyzeGlb
* @param {{ id: string, name: string, meshUri: string, owner: string, sha256?: string, createdAt: string }} identity
* @returns {object} manifest matching packages/avatar-schema/schema/avatar.v1.json
*/
export function manifestFromReport(report, identity) {
const manifest = {
schemaVersion: 1,
id: identity.id,
name: identity.name,
mesh: {
uri: identity.meshUri,
sha256: identity.sha256 || '',
format: 'glb',
kBytes: Math.round(report.bytes / 1024),
},
skeleton: report.skeleton.convention.schema,
traits: {
triangles: report.geometry.triangles,
joints: report.skeleton.jointCount,
canonicalJoints: report.skeleton.mapped,
morphTargets: report.morphs.total,
lipSync: report.morphs.lipSync,
},
owner: { chain: 'solana', address: identity.owner },
createdAt: identity.createdAt,
};
if (report.animations.length) {
manifest.traits.embeddedClips = report.animations.map((a) => a.name);
}
return manifest;
}
/**
* Human-readable byte size. Used in the UI and in the CLI-style summary, so it
* lives here rather than in the page module.
* @param {number} n
* @returns {string}
*/
export function formatBytes(n) {
if (!Number.isFinite(n) || n <= 0) return '0 B';
if (n < 1024) return `${n} B`;
if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
return `${(n / (1024 * 1024)).toFixed(1)} MB`;
}