opendance-windows/tasks/005-vrm-loader.md

T-WIN-005 VRM 模型加载

• 状态：done
• 依赖：T-WIN-001

目标

加载 VRM 模型，识别 VRM 版本，定位 Skeleton3D 并映射 humanoid 骨骼。

load

DSH.md
contracts/model-formats.md     # 锚点：§1 角色模型
contracts/data-models.md       # 锚点：§4.1 VRM 优先规则
src/model/vrm_loader.gd
src/model/humanoid_map.gd

选型变更

文档原选型 godot-vrm（V-Sekai）GDExtension 不发布任何预编译产物， 需用 godot-cpp 本地编译原生库，会破坏「Linux 导出 Windows exe」的验收路径。 改用 Godot 内置 GLTFDocument：VRM 即 glTF 2.0 容器，实测可完整解析 154 骨骼的 VRoid 模型，且 GLTFState.json 可直接读取 VRM 扩展判定版本。

骨骼名映射

HumanoidMap 覆盖 VRoid / VRM 0.x / Mixamo 三类命名，归一化后精确比较：

• 剥离前缀 jbip / mixamorig / bip01（归一化之后的形态）
• 生成 compact（left→l）与 expanded（l→left）两种变体比较
• 故意不剥离 J_Aim_ / J_Roll_ / J_Sec_：VRoid 用它们标记扭转辅助骨， 剥离后 J_Aim_L_UpperLeg 会与真正的 J_Bip_L_UpperLeg 撞名

验收

tests/test_vrm_loader.gd：

• 三类命名规范的识别（含辅助骨不遮蔽真骨的回归用例）
• 真实 VRM：154 骨骼 / 3 网格 / VRM 1.0，humanoid 覆盖率 100%
• 缺失文件、普通 glTF 不误判