opendance-windows/README.md

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 实现逐帧一致

快速开始

# 验证（编译 → 测试 → 启动）
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，工程约束见 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 — 239 字节关键点帧与文本控制消息（本端为接收方）
• contracts/skeleton-topology.md — MediaPipe 33 点拓扑、父节点表、9 个关节角特征
• contracts/rest-api.yaml — 目录与关键点序列 API
• contracts/data-models.md — 资源字段与 VRM 优先规则
• contracts/model-formats.md — 模型与动作格式、关键点序列结构

contracts/ 是只读快照。任何跨端契约变更必须先回到 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，或客户端「关于」页面。 未使用 SMPL 模型及其衍生拓扑，统一采用 MediaPipe 33 点拓扑。