arkavo-org / arkavo-org/VRMMetalKit

Bone-name heuristics: support Mixamo, Blender, namespace prefixes

Open
#135 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.