40250 classic: G1 integrate W3 (§8.3 in-game help window)

Doc conflicts resolved by W0: kept all four 增量 50 change-log bullets and appended the W3 C.5 batch record. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014yvAPqPivoY7vmBbzgqK4W
2026-09-02 16:10:48 +09:00
parent 61ddf791fa d7711ba5f0
commit 804744c28f
8 changed files with 431 additions and 15 deletions
@@ -2545,18 +2545,53 @@ BOOL bMainFlareEnable;  std::string strMainFlareTextureFileName;  float fMainFla

 ### 8.3 帮助窗口未实现

-**参考**：`POC/assets/root/uihelp.py`（136 行）+ uiscript `helpwindow.py`。
-入口：`game.py:459 __PressHKey()` —— 非 Ctrl 时 `self.interface.OpenHelpWindow()`
+**状态**：🟡 开发中（首版落地，真服 / 视觉未验收）—— 批次 2026-09-02 / W3。
+
+**参考**：`assets/root/uihelp.py`（`HelpWindow`，单页版 `ENABLE_HELP_MULTIPAGE = 0` →
+`LoadDialogSinglePage()` 装 `UIScript/HelpWindow.py`）+ uiscript
+`assets/uiscript/uiscript/helpwindow.py`（19 条 `help_XX` 浮动文本 + `taskbar_help_*`
+贴纸标签 + `close_button`，文本取自 `uiScriptLocale.HELP_*`）。
+入口：`game.py __PressHKey()` —— 非 Ctrl 时 `self.interface.OpenHelpWindow()`
 （Ctrl+H 是 `/user_horse_ride`）。

-**当前**：`POC/project/ui/system_menu_ui.gd:91` 只显示占位提示。
+> 注：本仓 `uihelp.py` 并非“136 行含键位/说明行”的版本；帮助行文本实际在
+> `helpwindow.py` uiscript 里以 `uiScriptLocale.HELP_*` 引用，逐字值在
+> `locale/locale/<lang>/locale_interface.txt`。故“逐字对齐 `uihelp.py`”按“逐字对齐
+> `helpwindow.py` + `uiScriptLocale.HELP_*`（英文表）”落实。

-**修改**
+**当前**：`system_menu_ui.gd` 的 `help_button` 已由占位提示改为打开 `help_ui.gd`。

-1. 新建 `POC/project/ui/help_ui.gd`，按样板装 `helpwindow.py` uiscript，
-   内容绑定逐字对齐 `uihelp.py`。
-2. 挂 `H` 键（非 Ctrl）与 ESC 菜单的 `help_button`，替换 `system_menu_ui.gd:91` 的占位。
-3. 配 `help_ui_test.gd`。
+**改动**
+
+- 新增 `project/ui/help_ui.gd`：`ui.open_script("helpwindow.py")`（UiScript → UiBuild）
+  非模态开窗；`_relabel()` 把 `helpwindow.py` 解析出的 `<HELP_*>` / `<CLOSE>` 占位
+  （`UiManager` 未接 locale 回调时产生）用本工程 `Locale`（`en`）表 + 逐字英文兜底补回，
+  覆盖原脚本重名的两个 `help_02`（右键 / 中键相机说明）；`open/close/toggle/is_open`、
+  `close_button` → `close`、ESC 由 `UiManager` 窗口栈统一关顶层。
+- `project/ui/system_menu_ui.gd`：`help_button` → `close()` + `open_help()`；新增
+  `const HelpUI`、可注入的 `help_ui` 成员、`_ensure_help()`（懒建，复用菜单的
+  `ui/client/assets_root`）、`open_help()`、`toggle_help()`；`setup()` 追加可选第 6 参
+  `help_win`（旧 5 参调用不受影响）。
+- `project/game_scene.gd`：`_unhandled_input` 加**单条** `elif` —— `KEY_H` 且
+  `not ctrl_pressed and not meta_pressed` → `system_menu_ui.toggle_help()`；`Ctrl+H`
+  未占用，仍留给 `/user_horse_ride`。
+- 接口 / 数据结构变化：仅 `SystemMenuUI.setup()` 追加可选尾参；无网络 / EntityStore 改动。
+
+**测试**
+
+- 新增 `project/help_ui_test.gd`（headless SceneTree）：helpwindow.py 装载、19 条帮助行
+  逐字绑定且非 `<KEY>` 占位、任务栏标签、`close_button` 文本 = `Close`、`rows()` 便捷器、
+  `close_button` 关窗、`open/toggle`、ESC 栈顶、`SystemMenuUI.open_help()` 懒建并打开。
+- `godot --headless --path project --script res://help_ui_test.gd` → `PASS`（exit 0）。
+- 回归：`system_menu_ui_test`、`gamescene_test`、`ui_test` 全 `PASS`；附加
+  `system_option_ui_test`、`char_status_ui_test` 亦 `PASS`。
+- skip：本 worktree 无 `build/`，未跑 C++ `ctest`（本条无 C++ 改动）。
+
+**验收**
+
+- 真服 / 双账号 / Mac App：未验证（§8.3 为纯本地 UI，无服务端依赖）。
+- 视觉：`helpwindow.py` 的 `.sub` / `help_stick.tga` 贴图未逐像素比对；字体描边
+  （`"outline": 1`）按 `ui.py` 默认，未单独标定。

 ---

@@ -3076,7 +3111,7 @@ var _pw := "123456789"
 | W0 公共基础 / 集成 | 🟡 开发中 | DirectEnter、Classic Warp endpoint、`world_reset`、场景重建首版；增量 49 接口冻结批次（`Entity` 字段 + `mut_spawn_full/mut_ownership/mut_map_bgm/drain_dirty` + `bgm_changed` 信号 + `bgm_director.gd` + §8.6 键位入口）已提交，C++ `ctest` 16/16 + 9 项 GDScript 回归通过 | 接收 Phase 1 W1/W2/W3/W4 批次并执行 G1 |
 | W1 协议 / 账号会话 | 🟡 开发中（增量 50：§1.5 / §1.10 / §2.2 已落地，待真实验收） | 角色槽地址透传、发送结果、unknown / unhandled 错误链路、断线回 LOGIN；§1.5 locale 分支 + `CGClientVersion2`(0xf1)；§1.10 `text_codec.h` + `to_wire` 路由 + `net_text_codec_test`（套件 16→17）；§2.2 `GC_CHARACTER_ADD` 隐身丢弃 / PC·NPC 暂存 / 其余按 `npclist.txt` 命名立即 spawn，`GC_CHAR_ADDITIONAL_INFO` 无 pending 丢弃、命中则 `mut_spawn_full` 合并；G1 已接线 `set_executable_name` / `set_npclist_path` / `mut_affect_flags` | locale 代码页转码（CP949/CP1252）、真实双连接、进场延迟 |
 | W2 实体 / 世界 / 战斗 | 🟡 开发中（Phase 1 批次已交） | 增量 50：§2.1 两层模型（`EntityStore` 纯数据层 + `net_world._update_visibility()` 按 `CHAR_STAGE_VIEW_BOUND` / `AFFECT_SHOW_ALWAYS` / `IsWall` 建 / 淡出节点）、§2.3（`mut_spawn`→`mut_spawn_full` 整行替换 + 节点重建 + 上下马保坐标）、§2.4（点数快照清尾 / 单索引边界）、§2.5（`mut_affect_flags` 两段拼装 + 参考调用序刷新）已落地；`ctest` 16/16 + 7 项 GDScript 回归 + 新增 `net_world_vis_test` 全绿 | 远服端到端可见性 / VID 复用 / affect 表现验收；`state_flags` 表现层枚举 |
-| W3 玩法 UI / 输入 | 🟡 已有首版 | 多数窗口、背包 / 任务 / 社交、键位和输入已有回归；§8.6 数字键 / F1–F4 / Ctrl+数字入口已收敛 | §8.3 帮助窗；§8.6 剩余逐行键位、LSHIFT 翻页、表情包 |
+| W3 玩法 UI / 输入 | 🟡 已有首版 | 多数窗口、背包 / 任务 / 社交、键位和输入已有回归；§8.6 数字键 / F1–F4 / Ctrl+数字入口已收敛；§8.3 帮助窗（`help_ui.gd` = `helpwindow.py` + `uiScriptLocale.HELP_*` 逐字，`H` / ESC 菜单 `help_button` 入口，`help_ui_test` 绿）已落地 | §8.6 剩余逐行键位、LSHIFT 翻页、表情包；帮助窗视觉 / `.sub` 贴图与真服未验收 |
 | W4 渲染 / 资产 / 音频 | 🟡 已有首版 | GR2 / `.msa` / `.mse`、地图 / 水体 / 天气 / BGM 部分链路已有；`bgm_director.gd` 消费点就位 | §9.1 地图 BGM 曲目解析 + 音量、§9.2 后台恢复曲目、§9.3 生命周期单一属主 |
 | W5 打包 / 发布 / 验收 | ⬜ 未开始 | 已有 Godot 导出配置和构建入口 | 自包含资源包、Intel / Apple Silicon、签名和 Mac App 验收 |

@@ -3216,3 +3251,33 @@ var _pw := "123456789"
  - m2dev apply() 内联 touch() 路径（GC_CHARACTER_ADD 等旧协议分支）不在 §2.2 范围，未改
 下一批次：W1 接线 mut_affect_flags + §2.2 两包合并；Phase 2 由 W0 执行 G1 集成
 ```
+
+```text
+批次：2026-09-02 / W3 / §8.3（帮助窗）
+状态：🟡 开发中（首版落地；真服 / 视觉未验收）
+参考：assets/root/uihelp.py（HelpWindow.LoadDialogSinglePage）；
+  assets/uiscript/uiscript/helpwindow.py（help_01..help_19 + taskbar_help_* + close_button）；
+  assets/locale/locale/en/locale_interface.txt（HELP_* / CLOSE 逐字）；
+  game.py __PressHKey（H 非 Ctrl → interface.OpenHelpWindow()，Ctrl+H = /user_horse_ride）
+改动：
+  project/ui/help_ui.gd（新）—— ui.open_script("helpwindow.py") 非模态；_relabel() 用
+    Locale(en) + 英文兜底把 <HELP_*>/<CLOSE> 占位补回（含重名的两个 help_02）；
+    open/close/toggle/is_open、close_button→close、ESC 走 UiManager 窗口栈、rows() 便捷器
+  project/ui/system_menu_ui.gd —— help_button 由占位提示改为 close()+open_help()；
+    +const HelpUI、+help_ui 成员、+_ensure_help()/open_help()/toggle_help()；
+    setup() 追加可选第 6 参 help_win（旧 5 参调用不受影响）
+  project/game_scene.gd —— _unhandled_input 加单条 elif：KEY_H 且非 ctrl/meta →
+    system_menu_ui.toggle_help()（Ctrl+H 未占用）
+  接口变化：仅 SystemMenuUI.setup() 追加可选尾参；无 net / EntityStore 改动
+测试：godot --headless --path project --script res://help_ui_test.gd → PASS（exit 0）；
+  system_menu_ui_test / gamescene_test / ui_test 全 PASS；附加 system_option_ui_test /
+  char_status_ui_test 亦 PASS
+  skip：本 worktree 无 build/，未跑 C++ ctest（本批次无 C++ 改动）
+验收：真服 / 双账号 / Mac App 未验证（§8.3 纯本地 UI，无服务端依赖）；
+  helpwindow.py 的 .sub / help_stick.tga 贴图与字体描边未逐像素比对
+风险与依赖：依赖 W0 冻结的 UiManager/UiScript/UiBuild 与 Locale；未改共享文件，
+  game_scene.gd 仅加 1 条 elif（W3 许可范围）。1:1 偏差：本仓 uihelp.py 非“136 行含
+  键位行”版本，逐字源实际为 helpwindow.py + uiScriptLocale.HELP_*（已在 §8.3 注明）；
+  帮助窗按非模态实现（原版 Lock()），ESC/关闭行为等价
+下一批次：Phase 2 由 W0 执行 G1 集成；§8.6 剩余逐行键位与表情包仍在 W3 范围
+```
@@ -58,7 +58,7 @@
 | W0 公共基础 / 集成 | 🟡 | DirectEnter、Classic Warp endpoint、`world_reset`、场景重建首版已落地；增量 49 接口冻结批次（`Entity` 补字段 + `mut_spawn_full/mut_ownership/mut_map_bgm/drain_dirty`、`bgm_changed` 信号、`bgm_director.gd`、§8.6 键位收敛）已提交 | Phase 1 4 工作流并行完成后执行 G1 集成 |
 | W1 协议 / 账号会话 | 🟡 | 增量 50：§1.5 版本包按 locale 分支（EUROPE 发 `CG_CLIENT_VERSION2` 0xf1 + `"1215955205"`，其余发 0xfd + `MT_BUILD_TIMESTAMP`）、可执行名 setter；§1.10 `text_codec.h` UTF-8 安全定长文本裁剪 + `net_text_codec_test`，会话侧所有定长 name/sign/comment 填充改走 `to_wire()`；§2.2 `GC_CHARACTER_ADD` 按 invisible-race 丢弃 / PC·NPC 暂存 `m_pending_actor` / 其余即时 `mut_spawn`（名字取自 npclist.txt），`GC_CHAR_ADDITIONAL_INFO` 无暂存则记录并丢弃、命中则合并 9 字段 `mut_spawn_full` 后清表 | 真实 locale codepage 转码、真实双连接、enter delay；GDScript 名称长度校验统一（G1 已收） |
 | W2 实体 / 世界 / 战斗 | 🟡 | §2.1 两层模型（`EntityStore` 纯数据层 + `net_world.gd` 每帧 `_update_visibility()` 按 `CHAR_STAGE_VIEW_BOUND` / `AFFECT_SHOW_ALWAYS` / `IsWall` 建 / 淡出节点）、§2.3（`mut_spawn`→`mut_spawn_full` 整行替换 + 节点销毁重建 + 上下坐骑保坐标）、§2.4（点数快照截断 / 尾部清零 + 单索引边界）、§2.5（`mut_affect_flags` 两段拼装 + 参考调用序节点刷新）已落地并回归（增量 50） | 远服 40250 端到端可见性 / VID 复用 / affect 表现验收；`state_flags` 表现层枚举与眩晕 / 隐身等表现 |
-| W3 玩法 UI / 输入 | 🟡 | 多数窗口、背包 / 任务 / 社交、键位和输入已有首版；§8.6 数字键 / F1–F4 / Ctrl+数字入口已收敛 | §8.3 帮助窗；§8.6 剩余逐行键位与表情包 |
+| W3 玩法 UI / 输入 | 🟡 | 多数窗口、背包 / 任务 / 社交、键位和输入已有首版；§8.6 数字键 / F1–F4 / Ctrl+数字入口已收敛；**§8.3 帮助窗（`help_ui.gd` = `helpwindow.py` uiscript + `uiScriptLocale.HELP_*` 逐字，`H` 键 / ESC 菜单 `help_button` 入口，`help_ui_test` 绿）已落地** | §8.6 剩余逐行键位与表情包；帮助窗视觉 / `.sub` 贴图与真服未验证 |
 | W4 渲染 / 资产 / 音频 | 🟡 | GR2 / `.msa` / `.mse`、地图 / 水体 / 天气 / BGM 部分链路已有；`bgm_director.gd` 消费点已就位 | §9.1 地图 BGM 曲目解析 + 音量、§9.2 后台恢复曲目、§9.3 生命周期单一属主 |
 | W5 打包 / 发布 / 验收 | ⬜ | 已有 Godot 导出配置和构建入口 | 自包含资源包、Intel / Apple Silicon、签名和 Mac App 验收 |

@@ -162,6 +162,22 @@
 >   `wire_classic.h` 的 `GCPoints` 已有 `static_assert(sizeof == 1 + 255*4)`；`ClassicParser`
 >   需在 `GC_CHARACTER_ADD[2]` / `GC_CHARACTER_UPDATE` 后调用 `mut_affect_flags()` 把
 >   `affect_flag[2]` 送进实体（`mut_char_update` 无 affect 形参，未接线）。G1 集成已接线（见下）。
+> - **2026-09-02 增量 50（Phase 1 W3 / §8.3 帮助窗）**：新增 `project/ui/help_ui.gd` —— 1:1
+>   迁移 `assets/root/uihelp.py` 的 `HelpWindow`（单页版 `ENABLE_HELP_MULTIPAGE = 0` →
+>   `LoadDialogSinglePage`），布局走真 `assets/uiscript/uiscript/helpwindow.py`（UiScript →
+>   UiBuild），19 条浮动帮助行 + 10 个任务栏贴纸标签 + `close_button` 的文本逐字对齐
+>   `uiScriptLocale.HELP_*`（`locale/locale/en/locale_interface.txt`）；`UiManager` 未接 locale
+>   回调时 `helpwindow.py` 里的 `uiScriptLocale.X` 被解析成 `<X>` 占位，`_relabel()` 用本工程
+>   `Locale` 表 + 英文兜底补回（含原脚本重名的两个 `help_02`）。入口：`game_scene.gd`
+>   `_unhandled_input` 加单条 `elif`（`H` 且非 Ctrl / 非 Meta → `system_menu_ui.toggle_help()`；
+>   `Ctrl+H` 仍留给 `/user_horse_ride`）；`system_menu_ui.gd` 的 `help_button` 由占位提示改为
+>   `close()` + `open_help()`，新增 `_ensure_help()` 懒建 / `open_help()` / `toggle_help()` 与
+>   可注入的 `help_ui` 成员（`setup()` 追加可选第 6 参，旧 5 参调用不受影响）。新增
+>   `project/help_ui_test.gd`（helpwindow.py 装载 + 19 行逐字绑定 + 任务栏标签 + close_button +
+>   open/close/toggle + ESC 栈顶 + `SystemMenuUI.open_help()` 懒建）。`help_ui_test` /
+>   `system_menu_ui_test` / `gamescene_test` / `ui_test`（附加 `system_option_ui_test` /
+>   `char_status_ui_test`）全绿；本 worktree 无 `build/`，未跑 C++ `ctest`。视觉 / `.sub` 贴图
+>   与真服未验证。
 > - **2026-09-02 增量 49（W0 接口冻结批次）**：为 Phase 1 的 4 个并行工作流一次性落地跨工作流
 >   共享文件的骨架，冻结接口后再拆分。`EntityStore`：`Entity` 补 `empire / affect_flags /
 >   owner_vid / state_flags` 字段；新增 `mut_spawn_full()`（§2.3 两包合并的单次落地入口）、