# 用户角色接入记录

接入日期：2026-10-03。默认角色来自用户提供的 `stylized+fantasy+character+3d+model.glb`，文件生成器标识为 Tripo。原文件保留在下载目录，未覆盖或上传第三方服务。模型及其贴图的授权由用户提供；本项目不将其重新声明为 CC0。

## 模型与转换

- 原文件：25,221,320 字节，65 个蒙皮关节，13,631 个顶点，单个蒙皮网格，内嵌颜色、法线和金属度／粗糙度贴图，不含动画。
- 原文件 SHA-256：`e665077666f1015ae0369e3f8deda257d9f417e2a53fc5c16529a4ae8f50b61e`。
- 游戏文件：`FantasyTraveler.glb`，2,499,848 字节。保留几何、蒙皮权重和原有材质通道，颜色贴图缩至最长边 2,048 像素，其他贴图缩至 1,024 像素。JPEG 压缩为有损处理。
- 模型静态高度统一为 1.75 m，保留正面朝向 +Z。骨骼别名映射到现有动画控制接口，原名称保存在节点 `extras.originalBoneName` 中。
- 11 个动作来自已有 [KayKit CC0 动作库](../kaykit/SOURCE.md)，通过世界静止姿态旋转差重定向，以 30 帧每秒烘焙。保留新模型的骨长、关节层级与手指绑定，不直接复制不兼容的局部骨轴。
- 地面动作烘焙时校正最低蒙皮点，坐姿移除重复的水平髋部位移。游戏物理根节点仍由原有步行、跳跃与上下车路径控制。

转换脚本为 `scripts/prepare-custom-hero.mjs`，使用项目现有 Three.js 依赖和 macOS 自带的 `sips`，无需额外安装软件。可在项目根目录重新生成：

```sh
node scripts/prepare-custom-hero.mjs /absolute/path/source.glb public/assets/hero/FantasyTraveler.glb
```

## 动作与限制

默认加载用户角色，网络加载失败时尝试原 KayKit 骨骼角色，再失败则保留程序角色。原角色和许可文件均保留，便于恢复和追溯动画来源。测试要求自定义模型实际加载成功，不把回退角色计为替换成功。

走跑、起跳、空中、落地、Q 引力搬运、滑翔和上下车继续使用原控制逻辑。Q 是牵引施力姿势，不是双手抱住方块。上下车采用通用坐下、起身片段与程序路径，不是专门为新角色制作的动作捕捉。

本轮没有重新制作蒙皮权重、手指抓握、表情动画、服装物理或脚底地形 IK。重定向不能保证所有极端姿态下都没有衣物或关节穿插。角色替换不改变材料、任务、建筑、车辆或存档格式，也不涉及 Vercel 发布。