Seven characters shipped "All checks passed" and four were visibly broken
in game — lying on their backs at seven times scale, facing backwards, or
holding a gun that floated near their chest. Nothing in the suite was
wrong; it just never asked the questions that mattered. That distinction
is the whole lesson, and it is now written down in the skill as
references/failure-modes.md, generalised per failure.
Two root causes are measured and certain:
- flatten_and_scale() normalises the bounding box along Blender Z because
Z is up. For a model that arrives lying along Y that measures the
character's THICKNESS, so it scales by ~7 and leaves them on their back.
One assumption, both symptoms. The trap is that the normalised number
always comes out right — the exporter maps Blender Z to glTF Y, so "is
the height 1.75" passes on a character who is 7.5 m tall lying down.
All three casualties are VRM files that went through a Blender
round-trip and came back with a baked axis rotation.
- SkinnedPlayerModel.set_weapon() finds the hand with three hardcoded
spellings, which match none of the four non-Rigify rigs — their hands
resolve perfectly in the sidecar as "Right wrist" and "J_Bip_R_Hand".
When it misses, the weapon is parented to the model root at a fixed
chest offset, so it is not attached to the character at all. Same class
of bug as the leg check that name-matched thigh/shin. rig_map.py exists
so nothing downstream has to guess a bone name; only some consumers read
the roles it publishes.
Three new hard checks, none needing more than the vertices and the
sidecar:
character stands up in world space — against WORLD up, not against the
model's own proportions. "Is the spine the longest axis?" catches
nothing: a model rotated as a whole is internally consistent and
passes it comfortably.
character is a plausible size / height
every role the runtime needs is resolved
They separate the four good characters from the three broken ones on the
first run. Also fixed the posture measurement to read vertices rather than
object.bound_box, which is cached and still stale right after an import —
it reported a 1.75 m character as 1.18 m tall.
Recorded but not yet fixed: kiyoko faces backwards (facing is inferred by
two independent mechanisms and verified by neither), miku's grown hair
chains stretch under animation (generated chains are never validated
against the geometry they drive), and the mannequin's rifle hold does not
convince despite resolving correctly.
Co-Authored-By: Claude Opus 5 <[email protected]>
Kiyoko, Hikari, Aria and Momo, all CC-BY from Sketchfab, licences recorded
beside each skin. Seven GLB characters selectable now.
kiyoko 13 meshes 20 cloth chains (62 bones) 0.0% cross-leg bleed
aria 15 meshes 15 cloth chains (37 bones) 0.0%
momo 5 meshes 9 cloth chains (35 bones) 0.0%
hikari 13 meshes 10 cloth chains (37 bones) 0.2%, 12 twist bones
These are the first characters imported that were NOT authored against the
library's own bone spelling, and every one of them broke something that
had been quietly wrong all along. All four failures were in code that
guesses anatomy from names, which is exactly what tools/rig_map.py exists
to stop doing:
- LIMB ROLES went to the first role in LIMB_ORDER that matched at all, so
shin's catch-all "leg" claimed UpperLeg before thigh's exact "upperleg"
was ever consulted, and the thigh went unassigned. The result depended
on the order bones arrived in. Claims are now granted longest-stem
first. This also broke Mixamo (LeftUpLeg/LeftLeg) and had simply never
been hit, because every character so far used Rigify DEF- names.
- Names cannot settle thigh-vs-shin at all. A bare "leg" is the SHIN on
Mixamo and the THIGH on a rig whose shin is "knee" — both common, same
token, opposite bones. RigRoles now walks the leg from the foot upward
and fills in whatever the names could not, stepping over twist bones.
- verify_character.py looked for legs by the substrings "thigh"/"shin",
which VRoid spells UpperLeg/LowerLeg. It declared every locomotion clip
static while the legs animated perfectly, and the cross-leg bleed check
found no leg vertex groups at all and passed vacuously. Two green-
looking lies from one missing lookup; both now read the sidecar's
resolved roles.
- The cosmetic/spring classifier matched whole tokens only, so Momo's
HairFL / HairFR / HairF_Top tokenised to "hairfl" and matched nothing.
She imported with six chains, all bust, and no hair. Both classifiers
now share one rule that also accepts a two-character positional suffix,
which is short enough that "forearm" and "earring" are still untouched.
Two more pipeline fixes:
- A source model's own clips leaked into the export. Clearing bpy.data
.actions before the library import is not enough — hikari carried two on
a second armature's NLA tracks, and NLA_TRACKS export mode ships
anything in a track anywhere in the file. They export as rest-pose
statues. Now everything not retargeted is stripped from every object.
- verify_character.py gained a check for cloth chains with no measurable
extent. A chain whose bones are zero-length is dropped by the runtime
and simulates nothing, while the sidecar still cheerfully reports it.
Known: hikari's ten cloth chains are all zero-length and her collider fit
found nothing, so her costume does not simulate — her rig has been through
two toolchains and its cosmetic bones are empty terminators. She animates
correctly otherwise. The new check now reports this instead of hiding it.
tools/retarget.py also carries local working-tree changes that predate
this session.
Co-Authored-By: Claude Opus 5 <[email protected]>
A third playable character, built with the pipeline skill from a source
that was already in the repo: the animation library ships a rigged
Mannequin mesh on the exact 53-joint reference skeleton, CC0, so it needed
no download and retargets perfectly. 18 clips, 0.3% cross-leg bleed, 7% of
verts at four influences — a clean authored-weight import. Licence
recorded in mannequin.license.json as the other skins do.
It has no cloth chains, correctly: it is a mannequin and has neither hair
nor clothes.
Importing it turned up two real bugs, both of which would have hit any
flat-coloured or single-piece model:
- LevelMaterials.apply_character_look treated ANY untextured surface on a
character as the model's own outline shell and hid it, so the mannequin
rendered as a solid black silhouette — its body and joint materials are
untextured flat colours, not ink. _is_line_work() now asks whether the
surface is named eyes*, is drawn front-face-culled (the inverted-hull
setup), or is near-black. Taila and Miku are unaffected: their materials
are textured and never reach that branch. Verified by render.
- verify_character.py failed the build for having one mesh. That check
cannot tell "the pipeline joined them" from "the artist authored one
mesh" — Quaternius' mannequin is one piece on purpose. It is advisory
now; the join path's two unambiguous signatures, cross-leg bleed and the
4-influences-everywhere spread, are still hard checks.
Also restored Miku's description, which the re-import had blanked.
3 GLB skins selectable (6 with the built-in colour skins). Smoke 0
failures, 11/11 movement tests, cloth idle 0.024-0.078 deg/frame.
Co-Authored-By: Claude Opus 5 <[email protected]>
