zijunchiang/opendance-windows
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

feat(scene): 场景选择与物理落地 + 整包发布（T-WIN-012/013/014）

Browse Source 
T-WIN-013：API 升级与场景选择
- 契约快照同步到 rest-api 0.5.0 / data-models 0.7.0 / database 0.4.0
- catalog_types.gd 新增 SceneConfig（物理/环境/出生点/相机）与 Scene；
  CatalogBundle 增加 scenes[]；from_dict 按契约 7.1 再收敛一次
  （缺项默认、越界夹紧、非法枚举回退），与服务端 normalizeSceneConfig 同规则
- 新增 src/scene/scene_runtime.gd：GLB 载入 -> 碰撞体（mesh 三角网 /
  auto 命名约定 *_col、*_colonly / none 不兜底）-> 场景级重力（Area3D
  SPACE_OVERRIDE_REPLACE，不改全局 ProjectSettings）-> 风（每物理帧
  apply_central_force，阵风正弦叠加，支持 local 坐标系）-> 环境光与雾
  -> 出生点与相机（follow/fixed/orbit）；无碰撞体时兜底地面
- CatalogStore 增加 scenes/default_scene/find_scene/ensure_scene_cached/
  fetch_thumbnail（场景缓存带 sha256 指纹，避免换包后仍用旧 GLB）
- 主界面改为 2x2 四个选择器（曲目/动作/模型/场景）+ 场景参数面板
  （缩略图 + 重力/摩擦/弹性/碰撞体/风摘要）
- 游戏界面载入场景并落地物理，角色落在出生点；场景缺失/下载失败/
  解析失败一律回退内置空场景并提示，不阻塞开始跟练

T-WIN-012：「关于」清单展示当前版本号
- 版本唯一来源为 project.godot 的 application/config/version（v0.2.0）
- about_manifest() 输出版本/引擎/契约/协议/地址/隐私清单；
  无头测试无 autoload，读取 AppConfig 走 get_node_or_null 容错
- Credits 的单个 CONTRACT_VERSION 常量改为 CONTRACT_VERSIONS 字典
  （六项契约各自独立递增），并双向核对 contracts/VERSION

T-WIN-014：发布必须是单个完整包
- build/package-release.sh 重写：只产出单个 zip + SHA256SUMS，
  清理历史 .partN，超限时告警而非回退分卷；新增源产物与解压后完整性
  自检（PE 头 MZ / pck 魔数 GDPC / exe+pck 同目录同名）与体积-上限对比
- deploy/proxy 相关的 Gitea IIS 256MB 上限说明见 opendance-web

测试：tests/test_scene_config.gd（12 例）+ tests/test_about.gd（4 例）；
无头测试 687 通过 / 0 失败（10 个套件），verify.sh 全部通过
This commit is contained in:
zijunchiang
2026-09-17 00:45:23 +08:00
parent 47e11af7d0
commit 5581cbe05d
27 changed files with 2031 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+37 -11
View File
@@ -9,17 +9,20 @@ OpenDance Studio **阶段二**: Windows 客户端（Godot 4）。
## 状态
**阶段二已完成**: T-WIN-001 -> T-WIN-011 全部落地。
**阶段二已完成**: T-WIN-001 -> T-WIN-014 全部落地（含场景选择与整包发布）。
| 验收项 | 结果 |
|--|--|
| 脚本编译 | OK 全部通过(无 SCRIPT ERROR) |
| 无头测试 | OK **580 项全部通过**(8 个测试套件) |
| 无头测试 | 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 单个 `opendance-windows-v0.2.0.zip` + `SHA256SUMS`(不拆分卷) |
| 版本号展示 | OK 「关于」清单显示 `v0.2.0`，来源唯一(`project.godot`) |
## 快速开始
@@ -30,10 +33,13 @@ 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
# 打包发布产物（单个完整 zip + SHA256SUMS）
bash build/package-release.sh 0.2.0
```
当前版本：**v0.2.0**（`project.godot` 的 `application/config/version`，
与 `project.yaml`、导出产物名、Git tag、「关于」清单展示一致）。
详细使用说明见 [`README.txt`](README.txt)，工程约束见 [`DSH.md`](DSH.md)。
## 初次部署（从零跑起来）
@@ -90,7 +96,10 @@ http://192.0.2.10:3000
| 对端 | 方向 | 本端配置 | 说明 |
|--|--|--|--|
| 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`) | 需先在服务端**发布**曲目 / 动作 / 模型，动作还须**完成关键点预处理**，否则目录为空或动作不可选 |
| 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）。
@@ -105,8 +114,8 @@ GODOT_BIN=/path/to/godot bash build/export-windows.sh release
# Windows 上兜底导出
powershell -ExecutionPolicy Bypass -File build\export-windows.ps1
# 打成可分发的 zip（可选）
bash build/package-release.sh 0.1.0
# 打成可分发的 zip（单个完整包 + SHA256SUMS）
bash build/package-release.sh 0.2.0
```
| 产物 | 位置 | 说明 |
@@ -114,7 +123,8 @@ bash build/package-release.sh 0.1.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.1.0.zip` | `dist-release/` | 发布包：exe + pck + `THIRD_PARTY.md` + `README.txt` + `contracts/` |
| `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，否则脚本会报「未找到导出模板」。
@@ -123,7 +133,7 @@ bash build/package-release.sh 0.1.0
| 检查 | 命令 | 预期输出 |
|--|--|--|
| 一键验证（编译 + 测试 + 启动） | `GODOT_BIN=/path/to/godot bash build/verify.sh` | 末行「验证全部通过」，退出码 0 |
| 无头单元 / 集成测试 | `$GODOT --headless --path . --script res://tests/run_tests.gd` | `== 结果：580 通过 / 0 失败 ==` 与 `全部通过`（仓库基线 580 项 / 8 个套件；缺 VRM 素材或服务端不可达时相关用例显式跳过，数字会减少） |
| 无头单元 / 集成测试 | `$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` |
@@ -165,19 +175,30 @@ src/
├── net/ 239 字节编解码、WebSocket 服务、REST 客户端、NDJSON 解析
├── model/ VRM 加载、humanoid 骨骼名映射
├── anim/ 关键点 -> 骨骼重定向
├── scene/ 场景实例化与物理落地(重力/风/碰撞/环境/机位)
├── score/ 特征提取、DTW、评分规则
└── ui/ 主界面 / 游戏界面 / 结算 / 关于 / 来源展示
└── ui/ 主界面 / 游戏界面 / 结算 / 关于 / 来源展示 / 场景参数面板
```
界面**全部用 GDScript 代码构建**（不手写 `.tscn`），因此可被无头导入与单元测试覆盖。
## 依赖的契约（opendance-web v0.1.0 冻结）
## 依赖的契约（opendance-web 冻结，逐项独立版本）
| 契约 | 版本 |
|--|--|
| `rest-api` | 0.5.0 |
| `data-models` | 0.7.0 |
| `websocket-keypoints` | 0.1.0 |
| `skeleton-topology` | 0.2.0 |
| `model-formats` | 0.5.0 |
| `database` | 0.4.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/database.md`](contracts/database.md) - 数据库表结构(客户端只读快照，不直连数据库)
`contracts/` 是**只读快照**。任何跨端契约变更必须先回到
[`opendance-web`](https://<Gitea 地址>/<owner>/opendance-web) 修改并提升版本，
@@ -193,6 +214,11 @@ src/
两条路径共用同名导出预设与相同的 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`。
## 第三方开源声明