chore(contracts): 同步契约 0.5.0(模型一律转 VRM,Model 增 usable/unusableReason)

来自 opendance-web 的契约变更,按 DSH 文档 7.2「先改 Web 端 contracts/ 再同步另两端」:
- model-formats.md -> 0.5.0:主力格式 VRM + humanoid 门槛与回退
- data-models.md -> 0.5.0:Model 增 usable / unusableReason
- VERSION 同步
This commit is contained in:
opendance
2026-09-17 00:05:02 +08:00
parent 4913760a8b
commit efb2484125
3 changed files with 32 additions and 9 deletions
+26 -5
View File
@@ -1,20 +1,41 @@
# contracts/model-formats.md - 模型与动作格式契约 v0.4.0
# contracts/model-formats.md - 模型与动作格式契约 v0.5.0
## 1. 角色模型(models)
**系统以 GLB / VRM 为主力格式**(两个客户端都原生加载),其余格式一律在服务端转换。
**v0.5.0 起模型主力格式为 VRM**:**所有上传的模型都转换为 VRM**(`MODEL_CONVERT_FORMAT`
默认 `vrm`);GLB 退为**转换中间产物**与 **humanoid 不达标时的回退交付**。
两个客户端(Godot `godot-vrm` / 管理端 `@pixiv/three-vrm`)都原生加载 VRM。
| 格式 | 扩展名 | 支持级别 | 服务端行为 |
|--|--|--|--|
| glTF Binary | `.glb` | **主力(P0)** | **直接导入**,不重编码 |
| VRM | `.vrm` | **主力(P0)** | **直接导入**; = GLB + VRM 扩展(humanoid / 表情 / springBone / meta) |
| glTF Binary | `.glb` | 输入(P0) | 导入后**包装为 VRM**(含 `VRMC_vrm`);humanoid 不齐时保留 GLB 并标记 `usable=false` |
| glTF | `.gltf` (+ `.bin`, 贴图) | P1 | 直接导入(分离文件在 zip 内可用;单文件上传会缺.bin) |
| MMD 压缩包 | `.zip` | P1 | **自动搜索包内可用模型**:优先直接导入 `.vrm`/`.glb`/`.gltf`,否则转换 `.pmx`/`.fbx`,见 1.1 |
| MMD 模型 | `.pmx` | P2(输入) | 服务端转换(优先 GLB、其次 VRM);单文件上传无贴图 |
| FBX | `.fbx` | P2(输入) | 服务端转换(优先 GLB、其次 VRM) |
| MMD 模型 | `.pmx` | P2(输入) | 服务端转换:`assimp -> GLB -> VRM`;单文件上传无贴图 |
| FBX | `.fbx` | P2(输入) | 服务端转换:`assimp -> GLB -> VRM` |
### 1.1 上传与转换策略
**v0.5.0 起的一律转换链路**:
```
.vrm -> 直接导入(已是 VRM)
.glb / .gltf -> 包装为 VRM 1.0(写 VRMC_vrm)
.pmx / .fbx -> assimp -> GLB -> 包装为 VRM 1.0
.zip -> 自动搜索包内模型,按上面三种处理
```
**humanoid 门槛(硬性)**:VRM 1.0 要求 humanoid 必需骨骼齐全。服务端判定规则:
| 情况 | 交付 | `models.usable` | 是否进入客户端目录 |
|--|--|--|--|
| humanoid 必需骨齐全 | **VRM**(`format=vrm`,`vrmVersion=1.0`) | `true` | ✅ 可发布、可选用 |
| humanoid 不齐(如 MMD 日文骨名未重绑定) | 回退交付 **GLB**,`vrmVersion=null`,`conversionNote` 注明原因 | `false` | ❌ 不进入 `catalog/export` |
即:**不达标模型仍可入库与审核,但标记为不可用、不进入已发布目录**;
待骨骼按 `skeleton-topology.md` 的标准重绑定成功后重新转换即变为可用。
**`.glb` / `.vrm` / `.gltf` 直接导入**(不重编码,零损失);**`.pmx` / `.fbx` 由服务端转换**:
**优先 GLB,其次 VRM**。