docs(win): 用实现说明替换阶段二占位 README
This commit is contained in:
@@ -2,44 +2,96 @@
|
||||
|
||||
OpenDance Studio **阶段二**：Windows 客户端（Godot 4）。
|
||||
|
||||
> **状态：占位仓库**。按《DSH 开发文档：OpenDance Studio》的开发顺序
|
||||
> （Web 服务端 → Windows 客户端 → Android 辅助 App），本仓库将在阶段一
|
||||
> （`opendance-web`）契约冻结后开始开发。
|
||||
接收 Android 辅助 App 通过 WebSocket 推送的 33 点骨骼关键点，驱动 VRM 角色，
|
||||
并与 Web 管理服务端下发的参考动作做实时 DTW 评分。
|
||||
|
||||
## 计划技术栈
|
||||
> 本客户端只接收关键点坐标，**不接收、不存储任何视频画面**。
|
||||
|
||||
## 状态
|
||||
|
||||
**阶段二已完成**：T-WIN-001 → T-WIN-011 全部落地。
|
||||
|
||||
| 验收项 | 结果 |
|
||||
|---|---|
|
||||
| 脚本编译 | ✓ 全部通过（无 SCRIPT ERROR） |
|
||||
| 无头测试 | ✓ **580 项全部通过**（8 个测试套件） |
|
||||
| 应用启动 | ✓ 180 帧无运行时错误 |
|
||||
| Windows 导出 | ✓ 生成 `OpenDance.exe`（104 MB，PE 头校验通过）+ `OpenDance.pck` |
|
||||
| 真实 VRM 验证 | ✓ 154 骨骼 VRoid 模型，humanoid 覆盖率 **100%** |
|
||||
| 骨骼重定向 | ✓ 关键点方向与骨骼实际指向点积 **1.0000** |
|
||||
| 跨实现交叉校验 | ✓ 关节角与 Web 服务端 TypeScript 实现**逐帧一致** |
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 验证（编译 → 测试 → 启动）
|
||||
GODOT_BIN=/path/to/godot bash build/verify.sh
|
||||
|
||||
# 导出 Windows 可执行文件
|
||||
GODOT_BIN=/path/to/godot bash build/export-windows.sh release
|
||||
|
||||
# 打包发布产物
|
||||
bash build/package-release.sh 0.1.0
|
||||
```
|
||||
|
||||
详细使用说明见 [`README.txt`](README.txt)，工程约束见 [`DSH.md`](DSH.md)。
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 组件 | 选型 |
|
||||
|---|---|
|
||||
| 引擎 | Godot 4 (MIT) |
|
||||
| VRM 加载 | godot-vrm (MIT) |
|
||||
| 多格式导入 | Assimp (BSD-3-Clause) |
|
||||
| 通信 | WebSocket + HttpClient |
|
||||
| 评分 | DTW + 关节角度差异 |
|
||||
| 引擎 | Godot 4.7.x（MIT） |
|
||||
| VRM 加载 | Godot 内置 GLTFDocument |
|
||||
| 通信 | WebSocketPeer（服务端）+ HTTPRequest |
|
||||
| 评分 | DTW + 关节角度差异（纯 GDScript） |
|
||||
|
||||
## 计划任务
|
||||
## 架构
|
||||
|
||||
`T-WIN-001` 骨架 → `T-WIN-002` REST 客户端 → `T-WIN-003` WebSocket 接收 →
|
||||
`T-WIN-004` 239 字节帧反序列化 → `T-WIN-005` VRM 加载 → `T-WIN-006` 骨骼重定向 →
|
||||
`T-WIN-007` DTW 评分 → `T-WIN-008` 游戏 UI → `T-WIN-009` 来源信息展示 →
|
||||
`T-WIN-010` 关于页 → `T-WIN-011` Windows 打包脚本
|
||||
```
|
||||
Android 辅助 App ──239 字节关键点帧──▶ 本端 WebSocket 服务端 :8765
|
||||
│
|
||||
Web 服务端 ──GET /api/catalog/export────────┤
|
||||
──GET /api/motions/:id/keypoints ┘
|
||||
▼
|
||||
VRM 驱动 + DTW 评分
|
||||
```
|
||||
|
||||
## 依赖的契约（已冻结于 opendance-web，v0.1.0）
|
||||
```
|
||||
src/
|
||||
├── autoload/ AppConfig / CatalogStore / PoseReceiver / ScoreService
|
||||
├── net/ 239 字节编解码、WebSocket 服务、REST 客户端、NDJSON 解析
|
||||
├── model/ VRM 加载、humanoid 骨骼名映射
|
||||
├── anim/ 关键点 → 骨骼重定向
|
||||
├── score/ 特征提取、DTW、评分规则
|
||||
└── ui/ 主界面 / 游戏界面 / 结算 / 关于 / 来源展示
|
||||
```
|
||||
|
||||
- `contracts/websocket-keypoints.md` — **239 字节关键点帧**与文本控制消息（本端为接收方）
|
||||
- `contracts/skeleton-topology.md` — MediaPipe 33 点拓扑、父节点表、9 个关节角特征
|
||||
- `contracts/rest-api.yaml` — 曲目/动作/模型 API
|
||||
- `contracts/data-models.md` — 资源字段与 **VRM 优先**的默认模型选取规则（§4.1）
|
||||
- `contracts/model-formats.md` — 模型与动作格式、关键点序列结构
|
||||
- `contracts/open-source-credits.md` — 关于页必须展示的开源声明（三端共用）
|
||||
界面**全部用 GDScript 代码构建**（不手写 `.tscn`），因此可被无头导入与单元测试覆盖。
|
||||
|
||||
契约地址：https://gitea.kasugano.cn/zijunchiang/opendance-web/src/branch/main/contracts
|
||||
## 依赖的契约（opendance-web v0.1.0 冻结）
|
||||
|
||||
**任何跨端契约变更必须先回到 `opendance-web` 修改 `contracts/` 并提升版本**，
|
||||
- [`contracts/websocket-keypoints.md`](contracts/websocket-keypoints.md) — 239 字节关键点帧与文本控制消息（本端为**接收方**）
|
||||
- [`contracts/skeleton-topology.md`](contracts/skeleton-topology.md) — MediaPipe 33 点拓扑、父节点表、9 个关节角特征
|
||||
- [`contracts/rest-api.yaml`](contracts/rest-api.yaml) — 目录与关键点序列 API
|
||||
- [`contracts/data-models.md`](contracts/data-models.md) — 资源字段与 VRM 优先规则
|
||||
- [`contracts/model-formats.md`](contracts/model-formats.md) — 模型与动作格式、关键点序列结构
|
||||
|
||||
`contracts/` 是**只读快照**。任何跨端契约变更必须先回到
|
||||
[`opendance-web`](https://gitea.kasugano.cn/zijunchiang/opendance-web) 修改并提升版本，
|
||||
再在本仓库创建适配任务。
|
||||
|
||||
## 关键约束
|
||||
## 已知限制
|
||||
|
||||
- 客户端消费的目录通过 `GET /api/catalog/export` 一次性拉取，仅含 `status = published` 的资源
|
||||
- 默认模型直接用服务端解析好的 `defaultModelId`，本端无需自行实现优先级
|
||||
- 不使用 SMPL 拓扑
|
||||
- 发布产物必须包含 `THIRD_PARTY.md` 与「关于」页开源声明
|
||||
1. Godot 的 `WebSocketPeer` 不暴露握手请求路径，因此**无法校验 path 是否为 `/pose`**，
|
||||
实现接受任意 path，仅校验子协议 `opendance.pose.v1`。
|
||||
2. 文档原选型 `godot-vrm` GDExtension 不发布预编译产物，改用 Godot 内置 glTF 导入器
|
||||
+ 自实现骨骼名映射；理由见 `DSH.md` §6。
|
||||
3. `build/export-windows.ps1` 未在真实 Windows 上执行过（本环境无 Windows）。
|
||||
两条路径共用同名导出预设与相同的 PE 头校验逻辑。
|
||||
4. 真实 VRM 样例仅放在 `_scratch/`（已 gitignore），版权原因不入库；
|
||||
测试在找不到模型时显式跳过而非伪装通过。
|
||||
|
||||
## 第三方开源声明
|
||||
|
||||
见 [`THIRD_PARTY.md`](THIRD_PARTY.md)，或客户端「关于」页面。
|
||||
未使用 SMPL 模型及其衍生拓扑，统一采用 MediaPipe 33 点拓扑。
|
||||
|
||||
Reference in New Issue
Block a user