# 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 点拓扑。