Game Asset Vrm Motion

---
name: game-asset-vrm-motion
description: 将 FBX、BVH 或视频动捕映射到 VRM 角色，处理静止姿势、坐标、握持 IK 与时间抖动，适用于角色动作迁移和双手武器动作检查。
---

# VRM 动作映射与武器

输入可使用的 VRM、动作文件或原视频，以及目标帧率、地面和握持要求。优先考虑带正确握法的现成动作包、Rokoko/Blender 约束；已有动捕欠缺接触信息时才用附带补偿流程。

## 执行

1. 核对源/目标 rest pose、骨骼语义、长度单位、帧率与前向。附带 `mocap-to-vrm.py` 主要验证过 CMU 和 SMPL-X 映射，Mixamo 表存在但没有同等实测；A-pose 先做静止姿势校正。
2. 世界旋转传递先消除源静止旋转，再经朝向校正映射到目标静止姿势；根位移按骨长缩放。朝向校正仅包含 yaw，不能把髋到头的前倾当成世界上方向，否则前进会下沉。
3. GVHMR 镜头跟踪依赖背景特征。纯白跟拍素材在历史试验中无法恢复相机；固定机位模式可得到身体动作，但失去跟拍对应的水平位移，不能宣称恢复真实世界轨迹。
4. 手部检测率不是手型正确率。小尺寸、模糊与双手交叠时，MediaPipe/DWPose 的手指都曾不可用；先看叠加图与关节方向，握刀可用明确的固定手型和握点约束。
5. 主手用含朝向和关节限位的整臂 IK，辅助手允许沿柄滑动及有限扭转分配。不要只旋手腕对刀；够不到时记录接触丢失，考虑改动作或全身 IK，不能伪造完全握住。
6. 抖动先记录骨盆、挂点、原始手腕、目标方向、碰撞修正和最终轨迹，定位出现反转的阶段。挂点在骨盆局部滤波；使用现成 SciPy/Blender 滤波，碰撞修正需时间连续。直接平滑最终位置可能重新穿模。

## 配套代码

在 `assets/workspace/`，Blender 先安装 VRM Add-on：

```sh
blender -b --python scripts/mocap-to-vrm.py -- model.vrm motion.fbx work/retarget --map cmu --no-render
blender -b work/retarget/motion.blend --python scripts/vrm-hand-grip.py -- work/grip --arms ik --no-render
```

第二条只启用手型。使用 `--katana` 前必须为新动作准备刀向键、拔刀区间、握点和角色局部朝向；包内旧键只作数据格式参考，绝不能作为新动作的正确标注。

## 验收与边界

比较源/目标的缩放后髋高与脚底，分清骨关节高度、鞋底与腾空帧；接地不等于水平锁脚。统计角速度、反转次数、位置二阶差分、握点距离、手腕限位及碰撞，再看连续视频。快速斩击的大转角不一定是抖动。

历史试验留下落地斩辅助手够不到、宽松上衣接触和一处拔刀小反转；SpringBone 鞘链少穿模可能只是甩得更远。没有完成的锁脚、移动相机、手部高质量重建或游戏验收须继续标为待测。

资源与授权入口见 [sources.md](references/sources.md)，代码及适配边界见 [implementation.md](references/implementation.md)。