98 lines
4.1 KiB
Markdown
98 lines
4.1 KiB
Markdown
# opendance-windows
|
||
|
||
OpenDance Studio **阶段二**：Windows 客户端（Godot 4）。
|
||
|
||
接收 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.7.x（MIT） |
|
||
| VRM 加载 | Godot 内置 GLTFDocument |
|
||
| 通信 | WebSocketPeer（服务端）+ HTTPRequest |
|
||
| 评分 | DTW + 关节角度差异（纯 GDScript） |
|
||
|
||
## 架构
|
||
|
||
```
|
||
Android 辅助 App ──239 字节关键点帧──▶ 本端 WebSocket 服务端 :8765
|
||
│
|
||
Web 服务端 ──GET /api/catalog/export────────┤
|
||
──GET /api/motions/:id/keypoints ┘
|
||
▼
|
||
VRM 驱动 + DTW 评分
|
||
```
|
||
|
||
```
|
||
src/
|
||
├── autoload/ AppConfig / CatalogStore / PoseReceiver / ScoreService
|
||
├── net/ 239 字节编解码、WebSocket 服务、REST 客户端、NDJSON 解析
|
||
├── model/ VRM 加载、humanoid 骨骼名映射
|
||
├── anim/ 关键点 → 骨骼重定向
|
||
├── score/ 特征提取、DTW、评分规则
|
||
└── ui/ 主界面 / 游戏界面 / 结算 / 关于 / 来源展示
|
||
```
|
||
|
||
界面**全部用 GDScript 代码构建**（不手写 `.tscn`），因此可被无头导入与单元测试覆盖。
|
||
|
||
## 依赖的契约（opendance-web v0.1.0 冻结）
|
||
|
||
- [`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) 修改并提升版本，
|
||
再在本仓库创建适配任务。
|
||
|
||
## 已知限制
|
||
|
||
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 点拓扑。
|