zijunchiang
8f303c0595
Web 端需求变更带来的契约字段级改动： - MotionFormat 枚举新增 vmd（MikuMikuDance 动作数据） - rest-api 服务地址说明改为双端口语义（软件 API 端口给客户端 / 管理端端口给浏览器） - model-formats 新增 §2.3 VMD 解析约定（标准 MMD 骨架、腿部 IK/FK 判定、手性转换） 三库契约文件保持逐字节一致。
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— 目录与关键点序列 APIcontracts/data-models.md— 资源字段与 VRM 优先规则contracts/model-formats.md— 模型与动作格式、关键点序列结构
contracts/ 是只读快照。任何跨端契约变更必须先回到
opendance-web 修改并提升版本，
再在本仓库创建适配任务。
已知限制
- Godot 的
WebSocketPeer不暴露握手请求路径，因此无法校验 path 是否为/pose， 实现接受任意 path，仅校验子协议opendance.pose.v1。 - 文档原选型
godot-vrmGDExtension 不发布预编译产物，改用 Godot 内置 glTF 导入器- 自实现骨骼名映射；理由见
DSH.md§6。
- 自实现骨骼名映射；理由见
build/export-windows.ps1未在真实 Windows 上执行过（本环境无 Windows）。 两条路径共用同名导出预设与相同的 PE 头校验逻辑。- 真实 VRM 样例仅放在
_scratch/（已 gitignore），版权原因不入库； 测试在找不到模型时显式跳过而非伪装通过。
第三方开源声明
见 THIRD_PARTY.md，或客户端「关于」页面。
未使用 SMPL 模型及其衍生拓扑，统一采用 MediaPipe 33 点拓扑。