arkavo-org / arkavo-org/VRMMetalKit
Bone-name heuristics: support Mixamo, Blender, namespace prefixes
- Dominant language
- Swift
- Stars
- 6
- Forks
- 2
- Avg merge
- 18h 51m
- Merged PRs (30d)
- 26
Description
## Background
The fallback heuristic in `Sources/VRMMetalKit/Animation/VRMAnimationLoader.swift` (`heuristicNameToBone`) maps animation node names to `VRMHumanoidBone` only when the VRMA file lacks the `VRMC_vrm_animation` extension or the model lacks humanoid mappings. It currently recognizes:
- Unity / VRM 0.0 style: `J_Bip_L_UpperArm` (matches `_l_` / `_r_` infixes, `left` / `right` substrings)
- VRM 1.0 style: `leftUpperArm`
It does **not** recognize:
- Mixamo: `mixamorig:LeftUpperArm`, `mixamorig:Hips`, etc.
- Blender: `arm.L`, `thigh.R`, `Armature|Hips`
- Common synonyms: `thigh` ↔ `upperleg`, `shin` ↔ `lowerleg`, `forearm` ↔ `lowerarm`
Without these, third-party rigs imported via VRMA fall back to no-mapping and play unanimated.
## Proposal
Extend `heuristicNameToBone` (and the model-side normalization at `modelNameToBone`) to:
1. Strip namespace prefixes before matching: `mixamorig:`, `Armature|`, optional digits.
2. Support side suffix patterns: `.L` / `.R` (Blender), trailing `_l` / `_r`.
3. Add bone synonyms: thigh→upperLeg, shin→lowerLeg, forearm→lowerArm.
## Notes / context
There's an archived branch `archive/animation-coordinate-fix-jan2026` (commit 4cc058e, Jan 19 2026) that implemented a version of these heuristics alongside an unrelated coordinate-conversion approach that has since been superseded. The bone-naming part is salvageable as a starting point; the coordinate conversion in that branch should NOT be carried forward — it was based on a different mental model than the current `convertForVRM0` path. See spike branch `spike/vrma-vrm0-orientation` for the canonical orientation fix.
## Acceptance
- VRMA file with mixamorig-prefixed bones plays correctly on a VRM 1.0 model
- VRMA file with Blender `.L`/`.R` bones plays correctly
- Existing VRM-style and Unity-style names continue to work (regression coverage)
- Tests added in `Tests/VRMMetalKitTests/` covering the new patterns
Contributor guide
Research direction
Start in Sources/VRMMetalKit/Animation/VRMAnimationLoader.swift with heuristicNameToBone and modelNameToBone, then inspect the existing fallback matching behavior and related VRMA animation tests. Add coverage under Tests/VRMMetalKitTests/ for Mixamo prefixes, Blender suffixes and namespaces, synonyms, and regressions for existing names; verify the accepted VRMA cases animate correctly without carrying over coordinate conversion from the archived branch.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- computer-graphics
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100