zijunchiang/opendance-windows
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity
Files
c3a227c6dfabd70a15813c602a014ecc5d42c040
opendance-windows/README.md
T
zijunchiang c3a227c6df feat(net): 连接保活 / 设备去重 / 连接状态机（T-WIN-015，契约 websocket-keypoints 0.2.0） 
与 Android 端 T-AND-011「两端一起改」：契约先在 opendance-web 修改并提升到
websocket-keypoints 0.2.0（向后兼容：子协议名与二进制帧 version 均不变，
只新增可选控制字段与一种新控制类型），再同步三端快照。

修掉本端的 3 处根因/放大器：
1. 静默超时 5s 过短且未声明，客户端无从得知。OkHttp 的协议层 ping 由底层库
   自动应答、**不暴露给应用层**，无法刷新 last_seen_ms，于是"画面里没人"时
   每 5 秒必然踢一次连接 -> 客户端重连 -> 再被踢。
   - CLIENT_TIMEOUT_MS 5s -> 15s，新增 HEARTBEAT_INTERVAL_MS = 5s；
   - welcome_payload() 在 welcome 中声明 silentTimeoutMs / heartbeatIntervalMs，
     config 广播同样带上（契约 §1.1：心跳必须 < 静默超时的一半，5000*2 < 15000）；
   - 处理应用层 ping 并回 pong（回显 sentAtMs + serverAtMs，供对端算 RTT）。
2. 反复重连被计成多台设备。按契约 §5 用 hello.deviceId 去重：同一设备只保留
   最新连接，旧连接以 close(1000) 关闭——刻意用 1000，因为对端按契约 §7
   收到 1000 不会重连，否则会形成"挤掉-重连-再挤掉"的循环；
   新增 device_count() 与 device_replaced 信号，界面一律显示去重后的设备数。
3. 只有 handshaken 布尔量，日志看不出卡在哪一步。按契约 §8 逐客户端维护与
   Android 端同名的状态（connecting -> handshaking -> streaming -> degraded，
   主动停止/超时/被替换为 stopped），并记录 close code/reason、协商子协议、
   连接/握手/首帧时间；degraded 保持时长做成可覆盖字段便于测试。

验收测试（tests/test_pose_server.gd 新增 7 项，总计 720 通过 / 0 失败）：
welcome 声明保活参数、ping->pong 回显、同 deviceId 去重（旧连接 1000 关闭且
设备数仍为 1）、8 个状态名与契约一致、状态随握手/首帧推进到 streaming、
丢帧进入 degraded 后恢复、snapshot 暴露设备数与保活参数。

同时更新 README/README.txt/tasks 与 Credits 的契约版本（0.2.0）。
2026-09-17 01:11:48 +08:00

13 KiB
Raw Blame History

opendance-windows

OpenDance Studio 阶段二: Windows 客户端（Godot 4）。

接收 Android 辅助 App 通过 WebSocket 推送的 33 点骨骼关键点，驱动 VRM 角色， 并与 Web 管理服务端下发的参考动作做实时 DTW 评分。

本客户端只接收关键点坐标，不接收、不存储任何视频画面。

状态

阶段二已完成: T-WIN-001 -> T-WIN-014 全部落地（含场景选择与整包发布）。

验收项 结果
脚本编译 OK 全部通过(无 SCRIPT ERROR)
无头测试 OK 687 项全部通过(10 个测试套件)
应用启动 OK 180 帧无运行时错误
Windows 导出 OK 生成 OpenDance.exe(104 MB, PE 头校验通过)+ OpenDance.pck
真实 VRM 验证 OK 154 骨骼 VRoid 模型，humanoid 覆盖率 100%
骨骼重定向 OK 关键点方向与骨骼实际指向点积 1.0000
跨实现交叉校验 OK 关节角与 Web 服务端 TypeScript 实现逐帧一致
场景选择与物理落地 OK scenes[] 可选、重力/风/摩擦/碰撞体落地并可日志核对
连接保活与设备去重 OK welcome/config 声明静默超时与心跳；应用层 ping/pong；按 deviceId 去重
发布整包 OK 单个 opendance-windows-v0.2.0.zip + SHA256SUMS(不拆分卷)
版本号展示 OK 「关于」清单显示 v0.2.0，来源唯一(project.godot)

快速开始

# 验证（编译 -> 测试 -> 启动）
GODOT_BIN=/path/to/godot bash build/verify.sh

# 导出 Windows 可执行文件
GODOT_BIN=/path/to/godot bash build/export-windows.sh release

# 打包发布产物（单个完整 zip + SHA256SUMS）
bash build/package-release.sh 0.2.0

当前版本：v0.2.0（project.godot 的 application/config/version， 与 project.yaml、导出产物名、Git tag、「关于」清单展示一致）。

详细使用说明见 README.txt，工程约束见 DSH.md。

初次部署（从零跑起来）

本节面向第一次拿到本仓库的人：从安装引擎到跑通「Web 服务端 + 本端 + Android」 三端链路。地址与端口一律使用占位符或产品默认值。

1. 前置条件

项 要求
操作系统 运行客户端：Windows 10/11(x86_64)。开发与导出：Windows 或 Linux 均可
Godot 4.7.x(project.godot 声明特性 4.7，本仓库按 4.7.2 验证)。使用标准版(GDScript), 不需要 .NET / C# 版
显卡与图形界面 渲染后端为 GL Compatibility，运行需支持 OpenGL 3.3 的显卡与驱动。仅无头测试与导出可无 GPU、可无图形界面
导出模板 仅打包导出时需要：必须安装与编辑器完全同版本的 export templates(.tpz)
磁盘与网络 Godot 编辑器 + 导出模板约数百 MB；导出产物 OpenDance.exe 约 104 MB、OpenDance.pck 约 107 KB。本端需能访问 Web 服务端 API（默认 TCP 3000），并与 Android 设备处于同一局域网、放行本端 TCP 8765 入站

2. 获取代码

git clone https://<Gitea 地址>/<owner>/opendance-windows
cd opendance-windows

3. 首次运行（编辑器内）

  1. 启动 Godot 4.7.x，在项目管理器选择「导入」，指向本仓库的 project.godot。
  2. 首次导入会执行资源导入（生成 .godot/），耗时从数十秒到数分钟不等；请等待完成，不要在导入中途关闭编辑器。
  3. 主场景已在 project.godot 中配置为 res://scenes/main.tscn，直接按 F5（或「运行项目」）即可。
  4. 界面全部由 GDScript 代码构建，不需要在编辑器里编辑场景，这是刻意设计（见 DSH.md 6）。
  5. 首次运行会在用户数据目录生成配置与日志：
%APPDATA%\Godot\app_userdata\OpenDance Studio\opendance.cfg
%APPDATA%\Godot\app_userdata\OpenDance Studio\logs\godot.log

4. 配置服务端地址

  • 位置：主界面顶部「服务端地址」输入框，填好后点「保存并测试」。
  • 配置字段名（opendance.cfg）：api_base_url。
  • 端口区分：客户端只访问 Web 服务端的 API 端口(默认 3000)；管理端页面在管理端口(默认 3001)，客户端不使用该端口。
  • 示例占位符：
http://<服务器地址>:3000
http://192.0.2.10:3000

保存后点「刷新目录」；顶部应显示「服务端正常 | DB ...」，左侧列出已发布的曲目 / 动作 / 模型。

5. 与另外两端的联通

对端 方向 本端配置 说明
Android 辅助 App Android -> 本端(WebSocket) listen_host（默认 0.0.0.0）、listen_port（默认 8765）、ws_subprotocol(默认 opendance.pose.v1) 本端是 WebSocket 服务端; Android 端填写本端主界面显示的「接收地址」，形如 ws://<本机局域网地址>:8765/pose
Web 服务端 本端 -> Web(HTTP) api_base_url(默认 http://127.0.0.1:3000) 需先在服务端发布曲目 / 动作 / 模型 / 场景，动作还须完成关键点预处理，否则目录为空或该项不可选

场景不是必需项：服务端没发布任何可用场景（或缺 GLB）时，本端回退到内置空场景 并在界面提示，不会阻塞开始跟练（文档 §5.6 第 4 条）。

  • Android 侧无本端可配置项：接收地址由 Android App 自己填写；本端只监听固定端口 8765（可在 opendance.cfg 改 listen_port 后点「重新连接接收服务」生效）。
  • 已知限制：Godot 的 WebSocketPeer 不暴露握手请求路径，本端接受任意 path，只校验子协议 opendance.pose.v1（见「已知限制」1）。
  • 接收状态可用主界面「查看接收状态」查看：连接数、去重后设备数、累计帧、 丢帧、畸形帧、保活参数，以及每台设备的状态（契约 §8）与首帧时间。

6. 打包导出

# Linux 上直接导出 Windows 可执行文件（推荐）
GODOT_BIN=/path/to/godot bash build/export-windows.sh release

# Windows 上兜底导出
powershell -ExecutionPolicy Bypass -File build\export-windows.ps1

# 打成可分发的 zip（单个完整包 + SHA256SUMS）
bash build/package-release.sh 0.2.0
产物 位置 说明
OpenDance.exe build/windows/ 主程序，约 104 MB；脚本校验前 2 字节为 MZ(合法 PE)
OpenDance.pck build/windows/ 资源包，约 107 KB; 必须与 exe 同目录
OpenDance.console.exe build/windows/ 控制台包装器，可能生成，非必需
opendance-windows-v0.2.0.zip dist-release/ 发布包：exe + pck + THIRD_PARTY.md + README.txt + README.md + contracts/
SHA256SUMS dist-release/ 裸文件名，与 zip 同目录时可 sha256sum -c SHA256SUMS 直接校验

导出前必须安装与编辑器同版本的 export templates，否则脚本会报「未找到导出模板」。

7. 自检清单

检查 命令 预期输出
一键验证（编译 + 测试 + 启动） GODOT_BIN=/path/to/godot bash build/verify.sh 末行「验证全部通过」，退出码 0
无头单元 / 集成测试 $GODOT --headless --path . --script res://tests/run_tests.gd == 结果：687 通过 / 0 失败 == 与 全部通过（仓库基线 687 项 / 10 个套件；缺 VRM 素材或服务端不可达时相关用例显式跳过，数字会减少）
启动冒烟（180 帧） $GODOT --headless --path . --quit-after 180 无 SCRIPT ERROR / ERROR:，进程退出码 0
日志检查 打开 %APPDATA%\Godot\app_userdata\OpenDance Studio\logs\godot.log 无 SCRIPT ERROR、无 ERROR:
导出产物校验 bash build/export-windows.sh release 输出「PE 头校验通过」，且 build/windows/OpenDance.exe 前 2 字节为 4d5a
服务端联通 主界面「服务端地址」->「保存并测试」 顶部显示「服务端正常

8. 常见问题

现象 原因 处理
游戏界面提示「模型加载失败：缺少骨骼」或「骨骼绑定失败，模型可能不受支持」 模型没有 Skeleton3D，或骨骼命名不在 humanoid 映射表内；驱动至少需要 hips / spine / neck / head + 四肢共 16 根核心骨骼 换用标准 VRM(VRoid Studio 导出)；看「人形覆盖率」，低于 60% 会提示「骨骼覆盖偏低，动作可能不完整」；必要时在 src/model/humanoid_map.gd 增加命名映射
顶部「服务端不可达」或「目录拉取失败」 Web 服务端未启动、地址或端口写错（误填管理端口 3001）、或网络不通 确认 api_base_url 为 http://<服务器地址>:3000；浏览器访问 http://<服务器地址>:3000/health 应返回 200；再点「保存并测试」
导出失败：「未找到导出模板」 未安装 export templates，或版本 / 路径与编辑器不一致 编辑器「编辑器 -> 管理导出模板 -> 下载并安装」；Linux 放 ~/.local/share/godot/export_templates/<版本>.stable/, Windows 放 %APPDATA%\Godot\export_templates\<版本>.stable\
提示「接收服务启动失败（端口 8765 可能被占用）」 TCP 8765 被占用或未放行 改 opendance.cfg 的 listen_port 后点「重新连接接收服务」，并同步修改 Android 端填写的接收地址
手机已连接但分数一直是 0 Android 端未开始推流，或帧内关键点置信度都低于 0.5 「查看接收状态」确认累计帧在增长、畸形帧为 0；确认 Android 端子协议为 opendance.pose.v1

技术栈

组件 选型
引擎 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/       关键点 -> 骨骼重定向
├── scene/      场景实例化与物理落地(重力/风/碰撞/环境/机位)
├── score/      特征提取、DTW、评分规则
└── ui/         主界面 / 游戏界面 / 结算 / 关于 / 来源展示 / 场景参数面板

界面全部用 GDScript 代码构建（不手写 .tscn），因此可被无头导入与单元测试覆盖。

依赖的契约（opendance-web 冻结，逐项独立版本）

契约 版本
rest-api 0.5.0
data-models 0.7.0
websocket-keypoints 0.2.0
skeleton-topology 0.2.0
model-formats 0.5.0
database 0.4.0

contracts/ 是只读快照。任何跨端契约变更必须先回到 [opendance-web](https://<Gitea 地址>//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），版权原因不入库； 测试在找不到模型时显式跳过而非伪装通过。
  5. Gitea 附件上传上限：本项目 Gitea 前置 IIS 的默认 maxAllowedContentLength = 30,000,000 字节（≈28.6 MiB），实测 30.5 MB / 40 MB 上传返回 HTTP 413。v0.1.0 因此被拆成 zip.part0/1/2（无法直接解压）。 现改为只上传单个完整包，超限时打包脚本直接告警并要求运维放宽上限， 不再回退分卷；做法见 opendance-web/deploy/proxy/README.md。

第三方开源声明

见 THIRD_PARTY.md，或客户端「关于」页面。 未使用 SMPL 模型及其衍生拓扑，统一采用 MediaPipe 33 点拓扑。

Reference in New Issue View Git Blame Copy Permalink