docs: 消除 Gitea 模棱两可 Unicode 告警（全角标点紧邻 ASCII 时改为半角）
依据 Gitea v1.27.3 modules/charset/escape_stream.go 的判定规则 （analyzeDetectResults：仅当左右相邻字符都不是非 ASCII 时才标记， 且 _common 表恒定生效），把说明文档中会被标记的全角标点 （，：；？！（） 等）改为半角，并保证成对括号宽度一致。 中文语境中的全角标点（左右均为中文）保持原样，不动代码与契约语义。
This commit is contained in:
opendance
@@ -1,6 +1,6 @@
|
||||
# opendance-windows
|
||||
|
||||
OpenDance Studio **阶段二**：Windows 客户端（Godot 4）。
|
||||
OpenDance Studio **阶段二**: Windows 客户端（Godot 4）。
|
||||
|
||||
接收 Android 辅助 App 通过 WebSocket 推送的 33 点骨骼关键点，驱动 VRM 角色，
|
||||
并与 Web 管理服务端下发的参考动作做实时 DTW 评分。
|
||||
@@ -9,14 +9,14 @@ OpenDance Studio **阶段二**：Windows 客户端（Godot 4）。
|
||||
|
||||
## 状态
|
||||
|
||||
**阶段二已完成**：T-WIN-001 -> T-WIN-011 全部落地。
|
||||
**阶段二已完成**: T-WIN-001 -> T-WIN-011 全部落地。
|
||||
|
||||
| 验收项 | 结果 |
|
||||
|--|--|
|
||||
| 脚本编译 | OK 全部通过（无 SCRIPT ERROR） |
|
||||
| 无头测试 | OK **580 项全部通过**（8 个测试套件） |
|
||||
| 脚本编译 | OK 全部通过(无 SCRIPT ERROR) |
|
||||
| 无头测试 | OK **580 项全部通过**(8 个测试套件) |
|
||||
| 应用启动 | OK 180 帧无运行时错误 |
|
||||
| Windows 导出 | OK 生成 `OpenDance.exe`（104 MB，PE 头校验通过）+ `OpenDance.pck` |
|
||||
| Windows 导出 | OK 生成 `OpenDance.exe`(104 MB, PE 头校验通过)+ `OpenDance.pck` |
|
||||
| 真实 VRM 验证 | OK 154 骨骼 VRoid 模型，humanoid 覆盖率 **100%** |
|
||||
| 骨骼重定向 | OK 关键点方向与骨骼实际指向点积 **1.0000** |
|
||||
| 跨实现交叉校验 | OK 关节角与 Web 服务端 TypeScript 实现**逐帧一致** |
|
||||
@@ -45,10 +45,10 @@ bash build/package-release.sh 0.1.0
|
||||
|
||||
| 项 | 要求 |
|
||||
|--|--|
|
||||
| 操作系统 | 运行客户端：Windows 10/11（x86_64）。开发与导出：Windows 或 Linux 均可 |
|
||||
| Godot | **4.7.x**（`project.godot` 声明特性 `4.7`，本仓库按 4.7.2 验证）。使用**标准版**（GDScript），**不需要 .NET / C# 版** |
|
||||
| 操作系统 | 运行客户端：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`） |
|
||||
| 导出模板 | **仅打包导出时需要**：必须安装与编辑器**完全同版本**的 export templates(`.tpz`) |
|
||||
| 磁盘与网络 | Godot 编辑器 + 导出模板约数百 MB；导出产物 `OpenDance.exe` 约 104 MB、`OpenDance.pck` 约 107 KB。本端需能访问 Web 服务端 API（默认 TCP 3000），并与 Android 设备处于同一局域网、放行本端 **TCP 8765 入站** |
|
||||
|
||||
### 2. 获取代码
|
||||
@@ -75,7 +75,7 @@ cd opendance-windows
|
||||
|
||||
- 位置：主界面顶部「**服务端地址**」输入框，填好后点「**保存并测试**」。
|
||||
- 配置字段名（`opendance.cfg`）：`api_base_url`。
|
||||
- **端口区分**：客户端只访问 Web 服务端的 **API 端口（默认 3000）**；管理端页面在**管理端口（默认 3001）**，客户端不使用该端口。
|
||||
- **端口区分**：客户端只访问 Web 服务端的 **API 端口(默认 3000)**；管理端页面在**管理端口(默认 3001)**，客户端不使用该端口。
|
||||
- 示例占位符：
|
||||
|
||||
```
|
||||
@@ -89,8 +89,8 @@ 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`） | 需先在服务端**发布**曲目 / 动作 / 模型，动作还须**完成关键点预处理**，否则目录为空或动作不可选 |
|
||||
| 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`) | 需先在服务端**发布**曲目 / 动作 / 模型，动作还须**完成关键点预处理**，否则目录为空或动作不可选 |
|
||||
|
||||
- **Android 侧无本端可配置项**：接收地址由 Android App 自己填写；本端只监听固定端口 8765（可在 `opendance.cfg` 改 `listen_port` 后点「重新连接接收服务」生效）。
|
||||
- 已知限制：Godot 的 `WebSocketPeer` 不暴露握手请求路径，本端**接受任意 path**，只校验子协议 `opendance.pose.v1`（见「已知限制」1）。
|
||||
@@ -111,8 +111,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.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/` |
|
||||
|
||||
@@ -133,9 +133,9 @@ bash build/package-release.sh 0.1.0
|
||||
|
||||
| 现象 | 原因 | 处理 |
|
||||
|--|--|--|
|
||||
| 游戏界面提示「模型加载失败：缺少骨骼」或「骨骼绑定失败，模型可能不受支持」 | 模型没有 `Skeleton3D`，或骨骼命名不在 humanoid 映射表内；驱动至少需要 hips / spine / neck / head + 四肢共 16 根核心骨骼 | 换用标准 VRM（VRoid Studio 导出）；看「人形覆盖率」，低于 60% 会提示「骨骼覆盖偏低，动作可能不完整」；必要时在 `src/model/humanoid_map.gd` 增加命名映射 |
|
||||
| 游戏界面提示「模型加载失败：缺少骨骼」或「骨骼绑定失败，模型可能不受支持」 | 模型没有 `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\` |
|
||||
| 导出失败：「未找到导出模板」 | 未安装 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` |
|
||||
|
||||
@@ -143,10 +143,10 @@ bash build/package-release.sh 0.1.0
|
||||
|
||||
| 组件 | 选型 |
|
||||
|--|--|
|
||||
| 引擎 | Godot 4.7.x（MIT） |
|
||||
| 引擎 | Godot 4.7.x(MIT) |
|
||||
| VRM 加载 | Godot 内置 GLTFDocument |
|
||||
| 通信 | WebSocketPeer（服务端）+ HTTPRequest |
|
||||
| 评分 | DTW + 关节角度差异（纯 GDScript） |
|
||||
| 评分 | DTW + 关节角度差异(纯 GDScript) |
|
||||
|
||||
## 架构
|
||||
|
||||
@@ -173,7 +173,7 @@ src/
|
||||
|
||||
## 依赖的契约（opendance-web v0.1.0 冻结）
|
||||
|
||||
- [`contracts/websocket-keypoints.md`](contracts/websocket-keypoints.md) - 239 字节关键点帧与文本控制消息（本端为**接收方**）
|
||||
- [`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 优先规则
|
||||
@@ -185,7 +185,7 @@ src/
|
||||
|
||||
## 已知限制
|
||||
|
||||
1. Godot 的 `WebSocketPeer` 不暴露握手请求路径，因此**无法校验 path 是否为 `/pose`**，
|
||||
1. Godot 的 `WebSocketPeer` 不暴露握手请求路径，因此**无法校验 path 是否为 `/pose`**,
|
||||
实现接受任意 path，仅校验子协议 `opendance.pose.v1`。
|
||||
2. 文档原选型 `godot-vrm` GDExtension 不发布预编译产物，改用 Godot 内置 glTF 导入器
|
||||
+ 自实现骨骼名映射；理由见 `DSH.md` 6。
|
||||
|
||||
Reference in New Issue
Block a user