4v5u09Z5a4Yuc/mtgodot-poc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(client): 完成40250客户端核心功能1:1对齐与桥梁高度采样修复

Browse Source 
- 桥梁与静态物体高度采样修复：
  - 严格对齐 40250 CMapOutdoor::GetHeight 与 CAttributeInstance::GetHeight
  - 解析 .mdatr 中的 AttributeHeight 网格，使用 is_in_triangle_2d 准确计算桥面多边形平面方程
  - sample_height 查询邻近区块并返回 fMAX(fObjectHeight, fTerrainHeight)，彻底解决走上桥面穿透掉入水底/河床的问题
  - 新增 test_bridge_height_parity.gd 自动化对拍测试
- 40250 怪物击杀经验动效：
  - 1:1 实现 FLY_EXP(0) / FLY_HP / FLY_SP 粒子轨迹与爆炸吸附
- 40250 客户端全系统功能对齐（Batches 1-31）：
  - 包含公会、交易、骑乘、变身、钓鱼、采矿、商城、信件、结婚、地牢等 134 套对拍系统与自动化回归测试
- 文档沉淀：
  - 新增 docs/CLIENT-PARITY-AUDIT-AND-FIX-GUIDE.md 客户端对拍缺陷发现与修复工程指南
This commit is contained in:
shen
2026-09-19 08:51:25 -07:00
parent 1db9e9a129
commit 66d217b313
650 changed files with 53046 additions and 1586 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CLIENT-GAP.md
+4 -3
View File
@@ -7,7 +7,7 @@
> 本文按“协议、数据、交互、表现均与原客户端等价”的严格 1:1 标准审计；
> `CLIENT-ROADMAP.md` 中的“P0–P10 首版完成”只表示主要纵向流程已有首版，不等于 1:1 完成。
> 渲染细节另见 `PARITY-GAP.md`，动画、材质和资产管线另见 `BACKLOG.md`，网络实现另见
> `CLIENT-PORT.md`。
> `CLIENT-40250-PORT.md`。
>
> **本文末「ClientVS22 实现细节审计（2026-09-02）」每一条的具体修改细节见
> [`CLIENT-GAP-FIX.md`](CLIENT-GAP-FIX.md)**（逐条给出 40250/ClientVS22 的参考
@@ -1604,8 +1604,9 @@
> ⑦ **武器挂点复核**：隔离探针实测 weapon MI 原点 == `equip_right_hand` 骨骼原点
> Δ≤0.06 m（旧「偏 10 m」为 cpu_skin / MapCoord 修复前的失效结论）；新增 grip
> pre-transform `weapon_pre = mul4x3(weaponInvWorld[0], weaponLocal[0])`（对齐
> `ModelInstanceUpdate.cpp:171` 的 `weaponComposite[0]`），30 cm 位移夹断退回原始手部位姿。
> `03150` 类网格在 .gr2 里就离骨骼原点 ~3 m（资产缺陷，非变换）。
> `ModelInstanceUpdate.cpp:171` 的 `weaponComposite[0]`）。2026-09-15 删除错误的 30 cm
> 位移夹断：`03150` 的原始顶点虽离原点约 3 m，但文件内逆绑定矩阵正用于抵消该偏移；
> `weapon_attach_test.gd` 现检查真实可见 AABB 在待机/走/跑/攻击中均接触手骨。
> 新增测试 `eterngrn_polish_test.gd`；`ctest 10/10` + 29 套 GDScript + iOS 全绿。
> - **2026-08-31 增量 38（ESC 系统菜单 + 游戏设置窗）**：
> ① **`system_menu_ui.gd`**（`systemdialog.py` 真 uiscript，thinboard 8 键）= `uisystem.py`
docs/CLIENT-PARITY-AUDIT-AND-FIX-GUIDE.md
+89
View File
@@ -0,0 +1,89 @@
# 40250 客户端对拍缺陷发现与修复工程指南 (CLIENT-PARITY-AUDIT-AND-FIX-GUIDE)
> **目标**：建立系统化的排查、探针探测与修复流程，解决 Godot 客户端从 40250 移植过程中由于“管线实现不完整”、“只实现裸数据漏掉复合层”导致的隐性细节缺陷（典型案例如：桥梁可行走但高度采样遗漏 `.mdatr` 导致掉落穿透）。
---
## 一、问题本质剖析：为何会出现此类缺陷？
在 Metin2 40250 原版中，几乎所有物理、移动、战斗与视觉表现都是**“多层复合叠加”**的。在向 Godot 移植的早期原型阶段，很多系统往往只实现了最底层的第 1 层，缺少了第 2 层和第 3 层的复合逻辑：
```mermaid
flowchart TD
subgraph 原版 40250 表现
L1["基础数据层 (如: PRTerrain height.raw 裸高度图)"]
L2["静态实体层 (如: CGraphicThingInstance / .mdatr 高度多边形)"]
L3["动态状态层 (如: 骨骼动作高度、骑乘偏置、水体/浮力判定)"]
L1 --> L2 --> L3 --> R1["最终真实表现 (如: 角色稳稳立于桥面)"]
end
subgraph 缺陷实现模式
D1["基础数据层 (fmt::terrain_height_at)"]
D1 --> R2["直接作为最终结果 (角色跌落到桥底裸地形)"]
end
```
如果仅依赖玩家跑图偶然触发，发现成本极高且容易重复反弹。必须转为**白盒走查、探针自动化与协议日志审计**。
---
## 二、高危缺陷领域清单与 40250 真实机制对照
| 领域 | 常见隐性缺陷表现 | 40250 原版真实机制（唯一真相源） | 关键代码位置 |
| :--- | :--- | :--- | :--- |
| **1. 空间与地貌 (Terrain & Objects)** | • 桥梁、楼梯、门廊台阶悬空或掉落穿透<br>• 水陆交界处判断错误（干地游泳或踩深水不减速/不可钓鱼）<br>• 地下城/山洞进出门廊穿透掉落 | • `CMapOutdoor::GetHeight` 查询 `.mdatr` 中的 `heights` 网格多边形，与裸高度图取 `fMAX`<br>• `attr.atr` 中的 `ATTRIBUTE_WATER` 与水面多边形绝对高度差<br>• `CDungeonBlock::GetObjectHeight` | `GameLib/MapOutdoor.cpp`<br>`EterLib/AttributeInstance.cpp`<br>`GameLib/AreaTerrain.cpp` |
| **2. 物理与移动 (Physics & Locomotion)** | • 遇到陡坡时直接穿山或以相同速度瞬移上山<br>• 被怪物或技能击退（Knockback）时穿透墙体飞出地图<br>• 自动寻路走直线卡死在栅栏/岩石缝隙 | • `ActorInstanceSync.cpp` 坡度倾角与重力滑落向量计算<br>• `ActorInstanceCollisionDetection.cpp` 击退时沿障碍物法线切向滑动<br>• `CMapOutdoor::is_blocked` 的栅格阻挡光栅化与逐轴滑动降级 | `GameLib/ActorInstanceSync.cpp`<br>`GameLib/ActorInstanceCollisionDetection.cpp` |
| **3. 动作与挂点 (Animation & Attachment)** | • 武器/盾牌朝向偏转或拿反、脱离手部<br>• 骑马时双手未握缰绳或双腿穿透马鞍<br>• 更换头盔/发型时头部穿模或发色异常 | • `CItemData::GetItemScale` 与骨骼挂点矩阵 `m_matBone` 变换<br>• `InstanceBaseMotion.cpp` 的骑乘姿势 override (`COMBO_TYPE_HORSE`)<br>• `CRaceData::SetHair` 的 MSM 顶点隐藏机制与 Alpha Blending 管道 | `GameLib/ActorInstanceAttach.cpp`<br>`UserInterface/InstanceBaseMotion.cpp`<br>`GameLib/RaceData.cpp` |
| **4. 战斗与射弹 (Combat & Flying)** | • 弓箭/法球穿透墙体或直接打入地底<br>• 普攻挥刀动作还没劈下来伤害数值已提前跳出<br>• 怪物死后不立刻倒地或死亡姿势嵌入地面 | • `CFlyingInstance::Update` 中的 `BackgroundHit` 碰撞（与地面/建筑交点）<br>• `.msa` 中的 `MotionEvent`（命中帧 `HIT` 严格帧事件驱动）<br>• `ActorInstanceBlend.cpp` 死亡动作的地面投影与骨骼终帧冻结 | `GameLib/FlyingInstance.cpp`<br>`GameLib/ActorInstanceBattle.cpp`<br>`GameLib/ActorInstanceBlend.cpp` |
| **5. 交互与拾取 (Picking & Decal)** | • 鼠标点击桥面、屋顶或 NPC 拾取点偏移到桥下<br>• 地面范围技能光圈（Decal）漏到桥底或悬空 | • `CMapOutdoor::GetPickingPointWithRay` 射线先求交物体再求交地形<br>• `CTerrainDecal` 的多边形表面投影裁切 | `GameLib/MapOutdoor.cpp`<br>`GameLib/TerrainDecal.cpp` |
---
## 三、四大系统化排查手段（主动发现）
### 手段 1：全图几何与阻挡坐标探针（Headless Coordinate Probes）
由于地图静态放置数据由 `areadata.txt` 和 `attr.atr` 完全定义，无需人工跑图，可由自动化脚本扫盘检测：
1. **特殊静态模型巡检**：
- 提取地图上全部引用了含有 `.mdatr`（带有 `heights` 网格）的物体（桥梁、台阶、悬崖栈道等）。
- 在该物体几何中心上方向下打垂直射线或采样 `sample_height(x, z)`。
- **断言**：采样高度必须落在物体表面标高区间内，与裸地形高度应有明显的阶跃高差；若 `sample_height == terrain_height`，直接报警并定位对应模型路径与坐标。
2. **地貌高度一阶导数（梯度突变）扫描**：
- 按 0.5m 步长对可通行路网进行网格采样。
- 检测相邻点高度差：若连续两点高度差 $> 2.5\text{m}$ 且未标记 `ATTRIBUTE_BLOCK`，判定为地貌穿透或缝隙掉落点。
### 手段 2：40250 核心链路白盒对拍（Static Call-Graph Audit）
以 40250 源码的关键函数为索引，走查当前客户端对应的实现：
- **查阅 40250 源码**：`40250/Server Client TMP4/ClientVS22/source/`
- **重点审查模式**：
- 40250 中包含 `fMAX(...)`、`min(...)`、多层分支判断的函数，当前客户端是否只实现了其中单条简单路径？
- 40250 中从资源读取参数的逻辑（如 `.msa` 帧事件、`.msm` 挂点、`.mdatr` 碰撞体），当前客户端是否被硬编码（hardcoded）常量替代？
### 手段 3：未决协议与资源缺失日志审计（Log & Protocol Auditing）
在测试与实机运行期间，关注并收集控制台日志中的警告：
- 过滤关键 Warning：`unhandled packet`、`missing model`、`cannot find mdatr`、`mesh has no height`。
- 检查服务端发送的所有 GC 封包（如 `GC_MOVE`, `GC_SYNC_POSITION`, `GC_ATTACK`, `GC_FLY_TARGETING`），确认不仅有网络层的解析反序列化，更在表现层驱动了正确的物理与动画状态。
### 手段 4：自动化无头路网巡逻测试（Headless Patrol Suite）
利用 Godot `--headless` 启动无头客户端：
- 让角色沿关键地貌路网（广场 $\to$ 跨河桥梁 $\to$ 仓库台阶 $\to$ 城门通道 $\to$ 郊外野怪区）自动移动。
- 监控指标：
- 角色 Y 坐标是否发生非预期的下坠（掉水、穿地）；
- `_blocked` 是否产生虚假阻挡导致角色提前停步卡死；
- 状态机是否在 `walk` / `run` / `wait` 之间异常震荡。
---
## 四、工程化修改与防回退治理原则
每次发现并修复类似细节问题时，必须严格执行以下三条工程原则：
### 原则 1：拒绝打补丁式硬编码（Treat the Root, Never Patch Coordinates）
- **禁止**针对个别坐标做特殊条件判断（如 `if x > 750 and x < 770: pos.y = 206.0`）。
- **必须**在底层管线实现通用机制（如在 C++ 引擎层解析 `.mdatr` 的 `heights` 并求交平面），确保全服数十张地图、数百座桥梁与所有建筑台阶自动获得修复。
### 原则 2：路线 A（严格 40250 原版实现）
- 不凭空发明“更好”的经验算法，遇到模糊细节直接翻阅 40250 对应 C++ 模块源码，将原版的数学公式、坐标系旋转（Z-up 转 Y-up、米制转换）与浮点容差 1:1 映射。
### 原则 3：修一处问题，必补一个 Parity 自动化回归测试
- 修复缺陷后，必须在 `project/` 下建立对应的 `test_*_parity.gd` 单元/集成测试（例如针对桥梁建立的 `test_bridge_height_parity.gd`）。
- 将测试纳入持续集成验证集（134+ Parity 测试套件），任何一次打包或构建前运行，确保旧缺陷绝不回退。
docs/CLIENT-PORT.md
-252
View File
@@ -1,252 +0,0 @@
# 客户端移植 —— 从素材渲染器到能联机的客户端
> **适用范围（2026-09-08 复核）**：本文描述的是 **m2dev fork 协议**后端。该后端**已不是默认**——
> `project/client_main.gd:14-15` 在 `MT_PROTOCOL` 为空时无条件兜底成 `classic`，当前默认走
> 40250 经典协议。迁移方案与 classic 后端的协议细节见 [`CLIENT-40250-PORT.md`](./CLIENT-40250-PORT.md)。
> 本文仍然有效的部分：m2dev 后端自身的握手 / 封包 / 相位编排（`MT_PROTOCOL=m2dev` 时仍可切回），
> 以及 §2 记录的移植进度。**不要**把本文的封包号或 `Packet.h` 依据用到 classic 后端上。
> 起点：本仓库（`metin2-client`）的渲染纵切「差不多能用」（见 [`PARITY-GAP.md`](./PARITY-GAP.md)）。
> 本文是把它变成**能连服务端玩**的客户端的分层计划。分水岭是**网络层**——别的玩家、
> 物品、战斗、聊天都以封包为数据源。
>
> 玩法 / 客户端系统层面「原始客户端有、这里还没有」的完整差距清单见
> [`CLIENT-GAP.md`](./CLIENT-GAP.md)。
## 0. 目标服务端
- LAN：`192.168.21.203`。~~握手端口 connection refused~~ —— **已解决（2026-08-30）**：真机
端到端已打通到 PHASE_GAME，见本文 §3。
- 默认端口（`assets/root/serverinfo.py`）：auth `11000`，频道/游戏 `11011/11021/11031/11041`。
- 测试账号：`admin` / `123456789`。
## 1. 协议（本 m2dev fork，**不是老 Metin2**）
### 1.1 帧格式
每个包 = `[uint16 header LE][uint16 length LE][payload...]`，`length` = 含 4 字节前缀的整包长度
（≥ 4）。包间的 0 字节是加密对齐 padding，跳过。header 是 `CG::`/`GC::` 命名空间常量
（`UserInterface/Packet.h` + `EterLib/ControlPackets.h`）。
### 1.2 加密握手（libsodium）
`EterBase/SecureCipher` —— X25519 密钥交换（`crypto_kx`）+ 每方向固定 nonce 的 XChaCha20
流加密（带运行字节计数，**顺序敏感**）+ `crypto_auth` HMAC 挑战应答 + XChaCha20-Poly1305
AEAD 加密 session token。
握手序列（连上 auth server 后）：
| 方向 | 包 | header | 动作 |
|---|---|---|---|
| S→C | `GCPhase{phase=PHASE_HANDSHAKE}` | `GC_PHASE` 0x0008 | 进握手态 |
| S→C | `GCKeyChallenge{server_pk[32], challenge[32], server_time}` | `GC_KEY_CHALLENGE` 0x000B | `Initialize()`；`compute_client_keys(server_pk)` |
| C→S | `CGKeyResponse{client_pk[32], challenge_response[32]}` | `CG_KEY_RESPONSE` 0x000A | `get_public_key()`；`compute_challenge_response(challenge)` |
| S→C | `GCKeyComplete{encrypted_token[48], nonce[24]}` | `GC_KEY_COMPLETE` 0x000C | `decrypt_token()`→token；`set_activated(true)`；解密已缓冲的剩余字节 |
| S→C | `GCPhase{phase=PHASE_AUTH}` | `GC_PHASE` | 进认证态 |
| C→S | `CGLogin3{name[31], pwd[17]}` | `CG_LOGIN3` 0x0102 | 明文账号密码（**此时流已加密**）|
| S→C | `GCAuthSuccess{login_key, result}` | `GC_AUTH_SUCCESS` 0x0108 / 失败 `GC_LOGIN_FAILURE` 0x0106 | `result` 真→拿 `login_key` |
拿到 `login_key` 后断开 auth，连**游戏服**（`:11011`），同样握手，然后 `CGLogin2{name, login_key}`
（`CG_LOGIN2` 0x0101）→ 选人 → 加载 → 进游戏相位。
> S→C 流 nonce `[0]=0x01`，C→S `[0]=0x02`。`ping`(`GC_PING` 0x0007)→`pong`(`CG_PONG` 0x0006) 全程要回。
## 2. 进度
| 模块 | 状态 | 位置 |
|---|---|---|
| `SecureCipher`（KX + 流 + AEAD token） | ✅ 端口完成，`net.cipher_roundtrip` CTest（KX / 挑战应答 + 篡改拒绝 / token 往返 / 跨块流加解密 / 字节计数） | `extension/src/net/secure_cipher.{h,cpp}` |
| `wire.h`（帧 + 控制 + KX + auth 结构体） | ✅ `#pragma pack(1)` 尺寸断言 | `extension/src/net/wire.h` |
| `ByteBuffer`（收发暂存） | ✅ header-only | `extension/src/net/byte_buffer.h` |
| libsodium 接入 | ✅ 从源码 vendor（`extension/third_party/libsodium-cmake` + zstd + miniLZO），macOS/iOS 都编过，不再依赖 Homebrew。详见 `docs/THIRD-PARTY.md` | `extension/third_party/CMakeLists.txt` |
| `NetStream`（非阻塞 POSIX socket + `process()` 循环 + 帧解析 + 内建控制面 handler：`GC_PHASE` / `GC_PING`→`CG_PONG` / KX 握手 / 激活后解密已缓冲字节） | ✅ 编译通过 | `extension/src/net/net_stream.{h,cpp}` |
| `AuthClient`（auth 相位：`PHASE_AUTH`→发 `CGLogin3`→收 `GCAuthSuccess`/`GCLoginFailure`） | ✅ 编译通过，等可达服务端端到端测 | `extension/src/net/auth_client.h` |
| `GameClient`（游戏服：`PHASE_LOGIN`→发 `CGLogin2{name, login_key}`→收 `GCLoginSuccess3` 角色列表→`select_character()`→`PHASE_SELECT/LOADING/GAME`） | ✅ 编译通过。角色列表按 `TSimplePlayerInformation`（pack(1)，103B）解析成 `{index,id,name,job,level,x,y}`；游戏相位包暂只回 PING、记未知 header | `extension/src/net/game_client.h` |
| `net_probe` 诊断工具 | ✅ `net_probe <host> <port> <id> <pw>`，打印 state / 握手 / 登录结果 / login_key | `extension/tools/net_probe.cpp` |
| **`M2Client` GDExtension 节点** | ✅ 已注册可用。`connect_to_server(...)` 编排 Auth→（`auth_ok`）→GameConnect→游戏相位；`select_character(index)`。信号 `stage_changed` / `phase_changed` / `auth_ok` / `login_failed` / `char_list` / `entered_game` / `disconnected`。生命周期（F5）：`suspend()`/`resume()`/`reconnect()` + `suspended`/`resumed` 信号，`NOTIFICATION_APPLICATION_PAUSED/RESUMED` 自动触发。烟测：正确报 `auth_connect → login_failed(Connection refused) → failed` | `extension/src/net/m2_client.{h,cpp}` |
| **`M2Client` 游戏内 API** | ✅ 出站 `move(func,arg,rot_deg,x,y)`（rot `/5`、`time` 取帧钟）/ `attack(motion,vid)` / `set_target(vid)` / `say(type,text)`，未入局返回 false。快照 `get_entities()` / `get_entity(vid)`（含 hp/sp/level/dead/stunned，坐标转 Godot 米）/ `get_main_vid()` / `get_points()`（HP/SP/level/exp/gold）/ `get_target()`（vid + hp%）。`pump_game()` 每帧 `EntityStore::set_now/tick` 并抽信号：`entity_spawned/despawned/moved/main_set`、`chat`、`vitals_changed(vid)`、`entity_dead(vid)`（首次去重）、`damage(vid,amount,flag)`、`motion(vid,victim,motion)`、`points_changed(Dict)`、`target_info(vid,hp%)`。`net.loopback_flow` 扩展：出站 `CG_MOVE/ATTACK/TARGET/CHAT` 经加密信道字节级校验 | `extension/src/net/m2_client.{h,cpp}` |
| **游戏相位封包结构** | ✅ `wire.h`：`GC_MAIN_CHARACTER` / `GC_CHARACTER_ADD[2]` / `GC_CHARACTER_DEL` / `GC_CHARACTER_UPDATE` / `GC_MOVE` / `GC_CHAT` + `CG_MOVE` / `CG_ATTACK` / `CG_TARGET` / `CG_CHAT`。**战斗/状态**（对 `Packet.h`）：`GC_PLAYER_POINTS`(0x0214, int32[255] 1024B) / `GC_PLAYER_POINT_CHANGE`(0x0215) / `GC_STUN`(0x0216) / `GC_DEAD`(0x0217) / `GC_MOTION`(0x0307) / `GC_DAMAGE_INFO`(0x0410) / `GC_TARGET_INFO`(0x0A10) + `EPointTypes`（HP/MAX_HP/SP/MAX_SP/LEVEL/EXP/GOLD…）+ `EDamageFlag`（NORMAL/POISON/DODGE/BLOCK/PENETRATE/CRITICAL）。全部 `static_assert` 尺寸 | `extension/src/net/wire.h` |
| **`EntityStore`（封包→世界模型）** | ✅ headless。`apply()` 消化上述包 → `vid → Entity{race,name,x,y,z,angle,parts,func,moving, hp,max_hp,sp,max_sp,level,dead,stunned}`；`GC_MOVE` FUNC_MOVE 插值/其他 func 吸附；`tick()` 按 `now_ms` 插值。战斗：`GC_PLAYER_POINTS`→`points()` 全量属性 + 镜像到主角实体；`GC_PLAYER_POINT_CHANGE`→按 `EPointTypes` 更新单实体 vital；`GC_DEAD`/`GC_STUN`→标记；拉取口 `drain_changes` / `drain_chat` / `drain_vitals` / `drain_damage` / `drain_motions` / `take_points_dirty` / `take_target_dirty`。单测 `net.entity_store` 扩展覆盖全部战斗包 | `extension/src/net/entity_store.{h,cpp}` |
| **`CG_*` 出站构造** | ✅ `GameClient::send_move/send_attack/send_target/send_chat`（`CG_CHAT` 变长） | `extension/src/net/game_client.h` |
| **环回集成测试** | ✅ `net.loopback_flow` CTest：进程内 `MockServer`（真协议：帧 + libsodium KX + 脚本相位包）驱动 `AuthClient`→`GameClient` 走完 auth→角色列表→选人→`PHASE_GAME`→游戏包进 `EntityStore`→NPC 移动插值。服务端一通改个 IP 即可 | `extension/tests/net_loopback_test.cpp` |
| **`EntityStore` 单测** | ✅ `net.entity_store` CTest：合成包 → spawn / 移动插值（半程/到达/func 复位）/ 吸附 / 变长 chat / despawn | `extension/tests/net_entity_test.cpp` |
| **`NetWorld` 场景桥（GDScript）** | ✅ `net_world.gd`：消费 M2Client 实体信号，每 vid 一个子节点，位置向 `get_entity(vid).pos` 平滑逼近（超 `snap_dist` 瞬移）、`rotation.y` 取自 `angle_deg`、动画状态取自 `func`。默认「占位胶囊 + 名字牌 + HP 条」；`set_model_factory(cb)` 换真模型。**战斗**：`vitals_changed`→缩放 HP 条 + emit `vitals(vid,hp,max_hp,dead)`；`damage`→实体头顶飘字（crit 放大变金 / dodge=MISS，tween 上浮淡出）+ emit `damage_number`；`entity_dead`→倒地 + `set_anim_state("dead")`。`main_entity_ready` / `chat_line` 信号。headless 自检 `netbridge_test.gd`（spawn/main/远移吸附/近移插值/chat/伤害数字/HP 条/暴击/死亡/despawn）通过 | `project/net_world.gd` |
| **P0 闭环胶水 + 场景组装** | ✅ `net_play.gd`：`player_controller` ↔ `M2Client` —— 点地→`move(FUNC_MOVE)`（节流）/ 停→`move(FUNC_WAIT)` / 点实体→`set_target` + 进 2.5m 自动 `attack` / 收自己 `GC_MOVE`→位置校正 / `points_changed`+`vitals_changed`+`target_info`→HUD。`hud.gd` 加 `set_vitals/set_exp/set_level/set_target/clear_target`。`game_scene.gd`（简版）把 world+player+camera+pc+net_world+hud+net_play+audio+lifecycle 拼起来，`login.gd` 的 `entered_game`（`--auto` 自动选槽）实例化。`netplay_test.gd` + `gamescene_test.gd` headless 全过 | `project/{net_play,game_scene,hud,login}.gd` |
| **P1 UI 工具层** | ✅ `ui/uiscript.gd` 解析原始 `uiscript/*.py`（子集解释器，**80/80 真实文件通过**）+ `ui/ui_build.gd` dict→Control 树（~20 种 type）+ `ui/ui_assets.gd`（`.sub`/tga/png）+ `ui/ui_manager.gd`（窗口栈 / ESC / modal / 拖动）+ `ui/dialogs.gd`。`ui_test.gd` 全过 | `project/ui/*.gd` |
| **P2 物品数据层** | 🟡 `wire.h`：`GC_ITEM_SET/DEL/UPDATE/USE/GROUND_ADD/GROUND_DEL/GET` + `CG_ITEM_MOVE/USE/DROP/PICKUP`（全 static_assert）。`EntityStore`：`inventory[90]` / `equipment[11]` / ground map + `drain_inv/ground/item_events`。`M2Client`：`get_inventory/equipment/item/ground_items` + `move_item/use_item/drop_item/pickup_item` + 5 信号。新 `Metin2Proto` 节点（`item(vnum)`/`mob(vnum)`，载 5748 真实 item）。⬜ 背包 / 装备窗 UI + 穿脱换模型 | `extension/src/{net/wire.h,net/entity_store.*,net/game_client.h,net/m2_client.*,proto/proto_node.*}` |
| **P3 聊天** | ✅ `wire.h` `GC_WHISPER`/`CG_WHISPER` + `EntityStore` whisper 解析（`ChatMsg` 加 from/sub）+ `M2Client.whisper()` + `whisper_received` 信号。`ui/chat_ui.gd`：4 标签 + 前缀 `/w`/`/g`/`/p`/`/s` + 系统/战斗日志。`net_world._bubble` 头顶气泡 + `main_bubble`。`chat_test.gd` 全过 | `extension/src/net/{wire.h,entity_store.*,game_client.h,m2_client.*}` · `project/ui/chat_ui.gd` |
| **P4 战斗表现** | 🟡 `wire.h` `GC_AFFECT_ADD/REMOVE` + `EntityStore` affect map + `M2Client.get_affects()` / `affect_added`·`affect_removed`。受击硬直（`net_play` + `pc.frozen`）· combo（motion 递增）· 相机抖动（`game_camera.shake`）· 死亡窗（`ui/death_ui.gd` → `/restart_here`·`/restart_town`）· `hud.set_affects` 图标条。`combat_fx_test.gd` 全过。⬜ 武器拖尾 / 相机锁定 | `extension/src/net/*` · `project/{net_play,game_camera,hud}.gd` · `project/ui/death_ui.gd` |
| **P5 特效引擎（首版）** | 🟡 `fx/mse.gd`（`.mse` 花括号树解析，真文件 6 particle）+ `fx/effect_player.gd`（Particle→`GPUParticles3D`：发射形状/速率/寿命/曲线/颜色渐变/billboard/加法混合）+ `fx/effect_registry.gd`（名字→`.mse` + 缓存 + spawn）。`wire.h` `GC_SPECIAL/SPECIFIC_EFFECT` + `M2Client.effect_cue` 信号 → `game_scene` 在实体上播。`fx_test.gd` 全过。⬜ `.dds` 纹理 / `.mde` mesh / 绑骨骼 | `extension/src/net/*` · `project/fx/*.gd` |
| **P6 技能系统（首版）** | 🟢 `wire.h` `GC_SKILL_LEVEL/COOLTIME_END/CREATE_FLY` + `EntityStore` skill 表 + `M2Client.get_skills`/`cast_skill`/`skill_up` + `skills_changed`/`skill_cooldown_end`/`fly_cue` 信号。`ui/skill_table.gd`（skilldesc.txt）+ `ui/skill_ui.gd`（K 键，加点）+ `ui/quickbar.gd`（1-8 施放 + 冷却）+ `net_world` 飞行球。`skill_test.gd` 全过 | `extension/src/net/*` · `project/ui/{skill_table,skill_ui,quickbar}.gd` |
| **P7 任务 / NPC（首版）** | 🟡 `wire.h` `GC_SCRIPT`/`GC_QUEST_CONFIRM`/`GC_QUEST_INFO` + `CG_ON_CLICK`/`SCRIPT_ANSWER`/`SCRIPT_BUTTON`/`QUEST_INPUT_STRING`/`QUEST_CONFIRM`（全 static_assert）。`EntityStore`：`ScriptCue`/`ConfirmCue`/`QuestInfo` map + `drain_scripts/confirms/quest_changes` + `quest(idx)`。`Entity` 加 `ch_type`。`M2Client`：`click_npc`/`script_answer`/`script_button`/`quest_input`/`quest_confirm`/`get_quests` + `script_dialog`/`quest_confirm_ask`/`quest_info` 信号。`ui/quest_dialog.gd`（EventManager 脚本渲染：`[ENTER]`/`[QUESTION]`/`[DONE]` → 文本+选项+确认）+ `ui/quest_log.gd`（J 键）。`net_play._on_pick` NPC 分流。quest 逻辑纯服务器驱动（选型②）。`quest_test.gd` 全过。⬜ `[INPUT]` 输入 UI / 选道具 / 立绘 / 世界任务箭头 | `extension/src/net/*` · `project/ui/{quest_dialog,quest_log}.gd` · `project/net_play.gd` |
| charselect 串场 | ⬜ P10 | — |
| **P8 社交 / 商店 / 仓库（首版）** | 🟡 `wire.h` `GC_PARTY_*`(0x0710-16) / `GC_MESSENGER`(0x0741) / `GC_SHOP`(0x0810) / `GC_EXCHANGE`(0x051C) / `GC_SAFEBOX_*`(0x0830-34) + 对应 CG（全 static_assert；`ShopItem`/`GCExchange`/`GCSubHeader` 等）。`EntityStore`：`PartyMember` map / `Friend` map / `ShopEntry` 表 / `ExchangeState` / `m_safebox[135]` + dirty 标志 + `drain_party_invites`/`drain_shop_errors`。`M2Client`：`party_invite/answer/leave` · `add/remove_friend` · `shop_buy/sell/close` · `exchange_start/add_item/add_gold/accept/cancel` · `safebox_checkin/checkout/move` + `get_party/friends/shop_items/exchange/safebox_items` + 8 信号。`ui/{party_ui,friend_ui,shop_ui,exchange_ui,safebox_ui}.gd`（队员面板常驻 / O 键好友 / 商店·交易·仓库随信号自动开）。`inventory_ui` 右键分流（商店卖 / 交易放 / 仓库存）。`p8_test.gd` + `net.entity_store` / `net.loopback_flow` 扩测全过。⬜ 公会（`PythonGuild` 40 法 + Mark 下载）、精炼 / 强化 / 龙魂、私人商店 / 拍卖、交易道具图标网格 | `extension/src/net/*` · `project/ui/{party,friend,shop,exchange,safebox}_ui.gd` · `project/game_scene.gd` |
| 公会 / 精炼 / 龙魂精炼 / 会徽下载（首版） | 🟡 `GC_GUILD`(0x0730) INFO/LIST/GRADE + `ui/guild_ui.gd`（G，真机 `[GM-TEAM]`）；`GC_REFINE_INFO`(0x051D) + `ui/refine_ui.gd`（`refine_ask` → `refine(pos,type)`）；`GC_DRAGON_SOUL_REFINE`(0x051F)/`CG`(0x050D `grid[15]`) + `DS_SUB_*` + `EntityStore.DragonSoulCue`/`m_dragon_soul[180]` + `M2Client.ds_refine(mode,cells)`/`ds_window_open`/`ds_refine_result` + `ui/dragon_soul_ui.gd`（L / 自动弹，3 模式 + 15 格背包右键填）。**会徽**：`MARK_*` 独立连接（`GC_MARK_IDXLIST`/`BLOCK` 0x0C1x、`GC_MARK_UPDATE` 0x0B15、`CG_MARK_LOGIN/IDXLIST/CRCLIST` 0x0C0x）；`NetStream` 加 `on_cipher_active()`/`on_raw()`（u32 `buf_size` 分帧）；`mark_image.{h,cpp}` `MarkImageSet`（LZO1X → 512×512 → `mark_pixels`）+ `mark_client.h` `MarkClient`；`M2Client.download_guild_marks`/`get_guild_mark_image`→`Image`；`serverinfo` `mark_port` 第 8 列；`app_flow` 进游戏连 + `guild_mark_updated` 冷却重连。**公会战 + 技能页**：`GUILD_GC_SKILL_INFO`(12) `GuildSkillInfoBody`(17)、`WAR`(15) `GCGuildWar`(10)、`GUILD_WAR_LIST`/`END_LIST`(17/18) `GuildWarPair`(8)、`WAR_POINT`(19) `GuildWarPoint`(12)、`NAME`(16) `GuildNameEntry`(16)；`EntityStore` `GuildSkillState`/`GuildWarStatus`/`m_guild_wars`/`m_guild_names` + `drain_guild_war_events`/`_scores`；`GameClient.send_guild_use_skill`；`M2Client` `get_guild_skill`/`get_guild_wars`/`get_guild_war`/`use_guild_skill`/`declare_guild_war`(`/war` 命令) + `guild_skill_changed`/`guild_war_changed`/`guild_war_event`/`guild_war_point` 信号；`ui/guild_ui.gd` 改三页 Tab（成员/技能/公会战）。**会徽上传**：`CG_MARK_UPLOAD`(0x0C03) `CGMarkUpload`(776)、`CG_GUILD_SYMBOL_UPLOAD`(0x0722) `CGSymbolUpload`(8)+文件字节；`NetStream.send_pending()`；`MarkClient` `Mode`(Download/UploadMark/UploadSymbol) + `upload_done()`；`M2Client.upload_guild_mark`(转 RGBA8/缩放)/`upload_guild_symbol`/`get_mark_server` + `guild_mark_uploaded`；`guild_ui` 成员页「上传会徽」按钮。`net.loopback_flow` 加 `MockServer::Mode::Mark` 真 socket 端到端校验（KX → CG_MARK_LOGIN → CG_MARK_UPLOAD 768 字节校验和 → upload_done）。`guild_refine_test.gd` + `dragon_soul_test.gd` + `guild_mark_test.gd` + `guild_war_skill_test.gd` + `net.entity_store` + `net.guild_mark` + `net.loopback_flow`(CTest) 全过。**真机验证（2026-08-31，`net_e2e`）**：`GUILD_GC_SKILL_INFO`(sub 12) 服务器进游戏自动推送，17B body 解析正确（skill_point=19 / guild_point 0/2300 / 12 等级）；`GUILD_GC_WAR`(sub 15) 无战状态解析正确；trace 显示 `GC_GUILD`(0x0730) 多个子包 len=171/40/83/22/21/9/5 均无 unknown / parse 错误。会徽独立连接 + 会徽上传仍未接真机（联调服未开会徽服端口）。⬜ 龙魂属性表、公会等级/日志页 | `extension/src/net/*` · `project/ui/{guild,refine,dragon_soul}_ui.gd` · `project/{net/serverinfo,app_flow}.gd` |
| **私人商店 / 道具商城 / Cube（首版）** | 🟡 `wire.h`：`CG_MYSHOP`(0x0802) `CGMyShopHead`(38，`char sign[33]+u8 count`) + `MyShopItem`(13，`u32 vnum,u8 count,ItemPos,u32 price,u8 display_pos`)×N；`CG_MALL_CHECKOUT`(0x0840) `CGMallCheckout`(8)；`GC_MALL_OPEN`(0x0841) `GCMallOpen`(5)、`GC_MALL_SET`(0x0842)/`GC_MALL_DEL`(0x0843) 复用 `GCItemSet`/`GCItemDel`，全 static_assert。`GameClient`：`send_open_private_shop(sign, vector<MyShopItem>)`（打包头+N项）/ `send_close_private_shop`(=`SHOP_CG_END`) / `send_mall_checkout` / `send_cube_make|material_info|result_list`（`/cube make|mInfo|rList` 走 `send_chat(CHAT_TYPE_COMMAND,…)`）。`EntityStore`：`m_mall[135]` + `mall_open/size/slot/dirty`；`GC_CHAT` 若 `type==CHAT_TYPE_COMMAND` 不进聊天，转 `apply_server_command()` 解析 `cube open/close/info/success/fail/r_list/m_info`（`v,c` 结果列表 + `@`配方 `&`组 `|`槽 `/`金币）→ `CubeState{open,npc,recipes[],results[],need_*}` + `drain_cube_events()`。`M2Client`：`open/close_private_shop`、`get_mall_items`/`mall_checkout`、`get_cube`/`cube_make`/`cube_request_result_list`/`cube_request_materials` + `mall_opened`/`mall_changed`/`cube_opened`/`cube_closed`/`cube_changed`/`cube_result` 信号。`ui/private_shop_ui.gd`（招牌 + 背包挑件 + 定价 + 개설/철수）、`ui/mall_ui.gd`（列表 + 取出到背包空格）、`ui/cube_ui.gd`（配方列表 + 材料/金币 + 제작）；`game_scene` 装配三窗。`net.entity_store`（合成 GC_MALL_* + `GC_CHAT/COMMAND` cube 全家桶）+ `net.loopback_flow`（真 socket：server 推 mall+cube，client 发 `CG_MYSHOP`/`CG_MALL_CHECKOUT`/`/cube` 字节校验）+ `shop_cube_mall_test.gd`（三窗 FakeClient）全过。**真机验证（2026-08-31，`net_e2e MT_E2E_MYSHOP=1`）**：`CG_MYSHOP`(0x0802) 38B head + 13B item×1（vnum 149，price 99999999）被真服接受，无断连 / 无 shop error；`SHOP_CG_END` 关店正常。Cube `/cube rList` 与 `CG_MALL_CHECKOUT` 送出路径不断连，但服务器只在玩家站到对应 NPC 前才回应，`mall_open=0` / `cube open=0` —— 需 NPC 交互才能完整验。⬜ `GC_SHOP_SIGN`/`SYMBOL_DATA` 头顶招牌、他人开店 `START_EX` 多标签、39 格拖放网格 / 鼠标物品态、能量条、NPC 前完整验 cube/mall。**拍卖行**：m2dev-client 无此系统（`0x08xx` 只有 shop/myshop/safebox/mall），非移植项，需自定义协议 + 服务端 | `extension/src/net/{wire.h,game_client.h,entity_store.{h,cpp},m2_client.{h,cpp}}` · `project/ui/{private_shop,mall,cube}_ui.gd` |
| **P9 世界系统（首版）** | 🟡 `wire.h` `GCWarp`(18) / `GCTime`(12) / `GCChannel`(5) / `GCNPCPosition`(6+78×n) / `GCTargetCreate/Update/Delete`(46/16/8) / `GCMount`(21)，全 static_assert。`EntityStore`：`WarpCue` + `drain_warps`、`server_time`/`channel` + dirty、`m_npc_marks` / `m_markers` map、`Entity.mount_vnum` + `drain_mount_changes`。`M2Client`：`get_channel/get_server_time/get_npc_marks/get_world_markers` + `warp`/`time_changed`/`channel_changed`/`npc_marks_changed`/`world_markers_changed`/`mount_changed` 信号。`ui/minimap.gd`（右上圆形，北朝上，实体/NPC/任务标记 + 玩家箭头 + CH 角标）+ `world/world_time.gd`（epoch → 太阳角度/光色/ambient 昼夜）+ `fx/weather.gd`（雪/雨 GPUParticles 跟相机）。`game_scene._on_warp` 同服挪人。`p9_test.gd` + `net.entity_store` 扩测全过 | `extension/src/net/*` · `project/ui/minimap.gd` · `project/world/world_time.gd` · `project/fx/weather.gd` · `project/game_scene.gd` |
| **P10 网络补全（首版）** | 🟢 `wire.h` `CGClientVersion`(0x000D，70B)。`GameClient` 收 `GC_MAIN_CHARACTER` → 自动发 `CG_CLIENT_VERSION` = **打通 LOADING→PHASE_GAME**（真机验证进游戏 + 121 实体）。`net/serverinfo.gd`（`class_name ServerInfo`，TSV 服务器表 + 频道端口偏移）+ `ui/loading_screen.gd`（相位驱动读取遮罩）+ `ui/reconnect_ui.gd`（断线倒计时 + 自动/手动重连）+ `app_flow.gd`（LOGIN→SELECT→GAME 串场状态机，单 `M2Client` 贯穿）。attack CRC 全 0 实测服务器接受。`net_e2e` 加 move+attack poke；`net.loopback_flow` 断言自动版本报文；`p10_test.gd` 全过 | `extension/src/net/{wire.h,game_client.h}` · `extension/tools/net_e2e.cpp` · `project/{app_flow,net/serverinfo}.gd` · `project/ui/{loading_screen,reconnect_ui}.gd` |
| 大地图窗 / 地形贴花 / 钓鱼 / 副本 / 坐骑换模型 / 跨服换图 / 频道人数轮询 / 真机字节校准 | ⬜ 见 [`CLIENT-ROADMAP.md`](./CLIENT-ROADMAP.md) P9·P10 剩余 | — |
| 物品 / 装备（`item_proto` + 背包封包 + 装备挂模型 → 解锁 §2.7 高光 / §2.3 时装） | ⬜ | — |
## 3. 连通性（2026-08-30：真机端到端打通到 PHASE_GAME）
服务端 = **m2dev-fork 协议**。`net_e2e`（`extension/tools/net_e2e.cpp`，`build/extension/net_e2e`）
驱动 auth→game→选人→进游戏全程；`MT_NET_TRACE=1` 打印每包 header/length/consumed。
**真机结果 —— 全程打通**：
- ✅ auth 握手（libsodium KX）+ `CG_LOGIN3` → `GC_AUTH_SUCCESS`
- ✅ game `CG_LOGIN2` → **`GC_LOGIN_SUCCESS4`(0x0105，4 槽)** 角色列表（`[SA]Admin` lv105）
- ✅ `CG_CHARACTER_SELECT` → `GC_PHASE(LOADING)` → 整包洪流全部按正确字节解析
- ✅ **`GC_MAIN_CHARACTER` 后自动发 `CG_CLIENT_VERSION`(0x000D)** → `GC_PHASE(GAME)` / **IN GAME**
- ✅ 进游戏后：121 个实体、HP 14990/15178、level 105、20 格背包、好友列表 1 人
- ✅ `CG_MOVE` + `CG_ATTACK`（CRC 全 0）保持连接不被踢 → **不需要占位 CRC**
**修的 3 个真 bug（对任何真服务器都必需）**：
1. `GC_LOGIN_SUCCESS4`(0x0105) 没处理（只认 3 槽的）→ 加 `GCLoginSuccess4`(492B) + handler。
2. 帧分发器 "did not consume" 误判：连续同 header 的包（一串 `GC_PLAYER_POINT_CHANGE`）会误杀连接
→ 改成按**实际消费字节数**判定（`net_stream.cpp` dispatch()）。
3. **缺 `CG_CLIENT_VERSION`**：服务器收到 `GC_MAIN_CHARACTER` 后等客户端回版本报文，缺它就在
phase 4 断线 → `GameClient` 收到 `GC_MAIN_CHARACTER` 时自动发（fork 固定 timestamp `1215955205`）。
**真机字节校准（2026-08-30，已做）** —— 用 `MT_NET_DUMP=1 net_e2e` 抓真实封包逐字节对：
- **实体名 / 等级 / 公会 / 骑乘** ✅ 走 `GC_CHAR_ADD_INFO`(0x0207，`TPacketGCCharacterAdditionalInfo`
97B)，之前根本没处理。加 `GCCharAddInfo` struct + handler，NPC「Old Man」(race 20009) 名字正确出。
- **`GC_CHARACTER_UPDATE`**(0x0209，38B) ✅ 之前只粗解 parts；现按 `TPacketGCCharacterUpdate` 全解
（parts / guild / alignment / pk_mode / mount，`GCCharacterUpdate` struct）。
- **`ch_type`**：`GC_CHARACTER_ADD.bType` 对 NPC/怪都是 0（服务器不填）。改在 GDScript 按 `race` 查
`mob_proto.type` 分类（`net_play._entity_kind`：0 怪 / 1 NPC / 2 石头 / 3 warp），`_entity_name`
怪名回退 `mob_proto.locale_name`。`game_scene` 现在也载 `mob_proto`。
- **`GC_PLAYER_POINTS`**(0x0214，1024B) —— **本来就对的**。真机 gold=13.5 亿（GM 号）、exp=0、
next_exp=int32 溢出为负都是服务器真实值。`M2Client.get_points` 把 exp/next_exp 按 unsigned 输出。
**第二轮校准（2026-08-30，已做）** —— 又抓了 in-game 洪流里没对过的包：
- **`GC_SKILL_LEVEL_NEW`**(0x021B，1534B) ✅ 这才是本服发的技能包（**没发老的 0x021A**），之前
`get_skills()` 永远空、K 键技能窗没内容、快捷栏没法施放。加 `PlayerSkill{u8 master, u8 level,
u32 next_read}`（6B/条，fork 的 `time_t` 是 32 位）+ `GCSkillLevelNew` + handler。真机实测：33 个
技能全 lvl 40 master 3（GM 号）。`get_skills()` 加 `master`（0 普/1 M/2 G/3 P）。
- **`GC_QUICKSLOT_ADD/DEL/SWAP`**(0x0519/1A/1B) ✅ 之前没处理 → 快捷栏进游戏是空的。加
`QuickSlot{u8 type,u8 position}` + 3 个 handler + `M2Client.get_quickslots()` + `quickslots_changed`。
`ui/quickbar.gd.restore_from_server()` 按服务器内容填 1-8 号格（type 1 道具 / 2 技能）。真机 10 格。
- **`GC_NPC_POSITION`**(0x0A50) —— struct **本来就对**（6 + 78×n，name[65]）。真机 49 条 NPC，名字对
（服务器不 zero-pad name buffer，`strnlen` 已兜住）。
- **`GC_ITEM_UPDATE`**(0x0514，41B) / **`GC_CHAT`**(0x0603，10B 头) / **`GC_AFFECT_ADD`**(0x0A20，25B)
/ **`GC_SPECIAL_EFFECT`**(0x0A30，9B) / **`GC_QUEST_INFO`**(0x0912，7B) —— 逐字节核对，**全部已对**。
- **`GC_GUILD`**(0x0730) sub-header 包（grade/info/list）已解析（见 M4 行）；会徽走 `MARK_*` 独立连接。
**校准后续（2026-08-30，已做）**：
- **3D 名字标签刷新** ✅ `EntityStore` 加 `ChangeKind::Info`；`GC_CHAR_ADD_INFO` 到达时对已存在实体
推 `Info` 变更 → `M2Client.entity_info(vid, dict)` 信号 → `net_world._on_info` 刷 Label3D。
`net_world.name_resolver`（`game_scene` 设为 `net_play._entity_name`）让怪名走 `mob_proto`。
- **跨服换图 `GC_WARP` addr≠0** ✅ `M2Client`：`WarpCue.addr` 是网络序 IPv4，转点分十进制后
`warp_to_game_server(host, port)` —— 拆掉当前 game 连接、复用存下的 `login_key` 直连新 game
server（跳过 auth）。同服 warp 仍只挪玩家。
- **断点快连** ✅ `M2Client.reconnect()` 现在优先用 `last_login_key` 直连 game server（省一次
auth 往返），失败再走完整 auth→game。服务器重发 spawn = 断点续连。
- **频道负载查询** ✅ `net/channel_status.gd`（对齐 `CServerStateChecker`）：明文 TCP 连任一频道口
→ 发 `CG_STATE_CHECKER`(0x000F，len 4) → 跳过杂包到 `GC_RESPOND_CHANNELSTATUS`(0x0010) →
读 `int32 count` + count×`{i16 port, u8 status}`。status：0 关 / 1 正常 / 2 拥挤 / 3 爆满
（Metin2 协议里就是 4 态，不是在线人数）。`app_flow._probe_channels` 先查状态、没答上的频道回退
`_probe_tcp`，下拉项标 ●/◐/✕。**真机实测**：`192.168.21.203:11011` 回 `{11011:1, 11012:1,
11013:1, 11991:1}` —— 也据此把 `serverinfo` 的频道端口步长从 +10 改成 **+1**（可在 serverlist.txt
第 7 列 `port_step` 按服覆盖）。`channel_status_test`（进程内 mock 服务器：请求字节 + 跳杂包 +
解析 + 不可达返回空）。
- **怪 / NPC 真 3D 模型** ✅ `ui/mob_view.gd`（对齐 `player_view.gd`）：`race` = `mob_proto` vnum →
**`root/npclist.txt`**（`<vnum>\t<代号>\t…`，如 `113→bear_brown`、`185→tiger_big`、`102→wolf`；
翻译版 `mob_proto` 把 `szName` 也本地化成 "Brown Bear" 了，解不出目录，必须靠这张表，`mob_proto`
名仅作兜底）→ 目录按代号逐段回退（`bear_brown → bear`），网格 / 贴图用完整代号
（换肤网格都在基础目录里：`bear/bear_brown.gr2` + `bear/bear_brown.dds`）→ 进 `Metin2Model`
（texture_dir = 目录）+ 解 `motlist.txt` → `Metin2AnimPlayer`。扫
`<assets>/*/ymir work/{monster,monster2,npc,npc2}/<folder>/`。npclist 解析一次进 `static` 缓存。
`set_anim_state("wait/run/attack/damage/dead/skill")` 按 motlist 动作名映射。
`game_scene._make_entity_model` 设为 `net_world` 的默认工厂（非主角 + 有 mob_proto 时）；race→是否有模型
缓存，失败回退占位胶囊。`net_world._attach_nameplate` 抽出来，真模型也挂头顶名字 + HP 条。
`mob_view_test`：race 102 Wolf → `wolf/` 目录、Metin2Model（40 骨 762 顶点）、motlist ≥3 动作、状态切换。
实测进游戏「Alpha Grey Wolf」「Hungry Black Bear」等出真模型 + 贴图 + 动作 + 名字牌 / 血条。
- **重连 / 已在局内时补拉实体** ✅ `game_scene.setup()` 现在是协程（分帧避免阻塞漏 PONG），
`net_world.setup()` 接 `entity_spawned` 已晚于 `M2Client` 的初始 spawn 洪流 → `_on_spawn` 0 次触发。
修：`net_world.catch_up()` 遍历 `client.get_entities()` 补 spawn 未镜像的；`game_scene` 已在局内分支里
**先** `net_world.set_local_vid(get_main_vid())` + `net_play._on_main_set(get_main_vid())` 再
`catch_up()`，否则本地玩家会被画成一个压在身上的大蓝胶囊。
**剩的都不是代码问题**：字面「在线人数」（数字）Metin2 协议里没有 —— `bStatus` 就是 4 态负载指示，
要真数字得改服务器；本地 `assets/` 只有 ~85 个 monster 目录（不是全量），没目录的 race
仍是占位胶囊 —— 换全量资产包即可全部出真模型。
**联调路上修的两个真 bug**（对任何真实服务器都必需）：
1. **`GC_LOGIN_SUCCESS4`(0x0105) 没处理** —— 只认 3 槽的 `GC_LOGIN_SUCCESS3`。已加 `GCLoginSuccess4`
结构(492B) + handler。
2. **帧分发器误杀连接** —— 连续同 header 的封包（如一串 `GC_PLAYER_POINT_CHANGE`）会触发
"on_packet did not consume" 误判并断线。改成按**实际消费字节数**判定
（`net_stream.cpp` dispatch()）。此 bug 之前会让 P0–P8 对任何真服务器的端到端全挂。
**当前状态**：P0–P8 的封包层仍以合成封包 CTest + FakeClient GDScript 测试离线验证（14 套 GDScript +
9 CTest 全绿）。真机端到端到 PHASE_GAME 的最后一跳留给 P10。
## 3b. B 轨（不依赖服务端的客户端系统）
| 模块 | 状态 | 位置 |
|---|---|---|
| **eterpack 读写器**（G1）| ✅ 本 fork = `PackLib` 单文件包（header + XChaCha20 加密索引 + zstd 数据 + 可选逐文件加密，硬编码 `PACK_KEY`）。`EterPack`（读，name-field 从 header 反推兼容真实包）+ `write_pack` + `packtool` CLI。`pack.roundtrip` CTest + 真实 `textureset/` 45 文件明文/加密往返 `diff` 一致 | `extension/src/pack/eterpack.{h,cpp}`、`extension/tools/packtool.cpp` |
| **登录 / 选人界面**（首版）| ✅ `charselect.gd`：3 旋转台 × 真实职业模型（`<class>_novice.gr2` + `wait.msa`）+ 真实 `board` 九宫格面板（槽位按钮 + 进入游戏）。数据来自 `M2Client.char_list`（联机）或 `--mock`（离线开发）。`login.gd`：服务器/账号/密码 + 连接，接全部 `M2Client` 信号（`--auto` 测试）。`ui_kit.gd`：从 `hud.gd` 抽出的九宫格助手。⬜ 创建/删除角色、旋转台微调、login→charselect→world 串场 | `project/{login,charselect,ui_kit}.gd` |
| **正式选人页（Metin2 风）** | ✅ `ui/char_select_screen.gd`：`app_flow._build_char_list` 用它替掉原来的裸按钮列表。全屏背景 `d:/ymir work/ui/intro/select/select.sub`（=select.jpg）+ 右侧 `SubViewport`（`own_world_3d`）里 `PlayerView` 真模型（正面朝相机 + `wait` + 缓摆）+ 左上职业名（locale `name_<class>.sub` → `select.dds`，DDS 走 `Metin2World.load_dds`；解不出退中文描边字 猛将/刺客/术士/巫女）+ 左侧 `board` 信息板（帮会徽 `get_guild_mark_image` / **国家名 `get_empire()`→`EMPIRE_A/B/C` locale + 国旗 `empireflag_<a/b/c>.sub`** / 帮会名 / 名称 / 等级 / 游戏时间 / 体力·智力·力量·敏捷 条）+ 开始 / 创建 / 删除 / 退出 + 多角色 ◀ ▶ 槽位切换（`_pad_slots` 按 `get_slot_count()` 补空槽，◀▶ 能走到空槽建号）。**建号 / 删号（1:1 对齐 `PythonNetworkStreamPhaseSelect.cpp`）**：`CG_CHARACTER_CREATE`(0x0201) `CGCreateCharacter`(77，job 是 **u16**)、`CG_CHARACTER_DELETE`(0x0202) `CGDeleteCharacter`(13，`private_code[8]`)、`GC_PLAYER_CREATE_SUCCESS`(0x020C) `GCPlayerCreateSuccess`(108=`{u8 slot, SimplePlayerInfo}`)、`GC_PLAYER_CREATE_FAILURE`(0x020D) `{u8 type}`、`GC_PLAYER_DELETE_SUCCESS`(0x020E) `{u8 slot}`、`GC_PLAYER_DELETE_WRONG_SOCIAL_ID`(0x020F)。`GameClient`：`create_character`/`delete_character` + `drain_char_events()`（`CharEvent{CreateOk/CreateFail/DeleteOk/DeleteFail}`）+ `replace_slot`/`clear_slot`（服务器只补丁槽位不重发列表）+ `slot_count()`。`M2Client`：`create_character(slot,name,job,shape,con,int,str,dex)`/`delete_character(slot,code)`/`get_empire`/`get_slot_count` + `char_created`/`char_create_failed`/`char_deleted`/`char_delete_failed` 信号（建 / 删成功后重发 `char_list`）。选人页建号弹窗（职业下拉 + 名称 + 各职业起始四维只读）、删号弹窗（secret 删除码）；`app_flow._on_char_list` 在 SELECT 态只 `set_chars()` 不整屏重建。会徽：`app_flow._goto_select` 也发 `download_guild_marks`，`guild_marks_ready`(one-shot) → `refresh_crest()`。相机改按**包围球** `r/sin(fovV/2)` 自适应 + 沿 -X 推 `r*0.5`（横向视锥更宽，不切远侧手），蒙皮定型后多 fit 4 帧。C++：`CharSlot` + `char_list` dict 补 `play_minutes/st/ht/dx/iq/main_part/hair_part`。`ui_assets.gd` 加 `load_dds_image()`。`net.loopback_flow` MockServer 加 `CG_CHARACTER_CREATE/DELETE` 真 socket 端到端（名称字节校验 + 成功补丁槽位 + 名称冲突 fail + 错误删除码拒绝）；`char_create_delete_test.gd`（弹窗 → 假 client 收 `create_character(slot1,"Newbie",job1,con3/int3/str4/dex6)` + 短名拒绝 + `char_created` 关窗 + 删号码 + 失败清框 + `set_chars` 保持选中）；`p10_test` 选人断言改点「开始」 | `project/ui/char_select_screen.gd` · `project/ui/ui_assets.gd` · `project/app_flow.gd` · `extension/src/net/{wire.h,game_client.h,m2_client.{h,cpp}}` · `extension/tests/net_loopback_test.cpp` |
| **角色状态窗（1:1 窗口迁移样板）** | ✅ `project/ui/char_status_ui.gd`：`UiScript`+`UiBuild` 直接装载 `assets/uiscript/uiscript/characterwindow.py` 真布局（4 页 tab：STATUS/SKILL/EMOTICON/QUEST，`SetState` 切页；技能 / 表情 / 任务的数据仍走各自专用窗）。STATUS 页数值逐字对照 `assets/root/uicharacter.py.RefreshStatus`：`Level_Value`=`points[LEVEL]`、`Exp_Value`=`u32(exp)`、`RestExp_Value`=`u32(next_exp)-u32(exp)`、`HP/SP_Value`=`cur/max`、`STR/DEX/HTH/INT_Value`=`points[ST/DX/HT/IQ]`、`ATT_Value`=`(MIN_ATK|MAX_ATK)+ATT_GRADE_BONUS+PARTY_ATT_GRADE`（min==max 取单值，全 0 退 `ATT_POWER`）、`DEF_Value`=`DEF_GRADE(+DEF_GRADE_BONUS 若非 0)`、`MATT_Value`=`MAGIC_ATT_GRADE+(MIN|MAX)_MAGIC_WEP`、`MDEF_Value`=`MAGIC_DEF_GRADE`、`ASPD/MSPD/CSPD/ER_Value`=`points[ATT_SPEED/MOV_SPEED/CASTING_SPEED/EVADE_RATE]`（EPointTypes 索引取自 m2dev `src/UserInterface/Packet.h`）。加点：`HTH/INT/STR/DEX` 的 `_Plus`/`_Minus` 按钮 → `client.say(0, "/stat ht"|"/stat- ht" …)`，与原 `statusPlusCommandDict`/`statusMinusCommandDict` 完全一致；`Status_Plus_Value`=`points[STAT]`，`>0` 才显示 `_Plus` 按钮和 `Status_Plus_Label`。名称 / 帮会 / 职业头像取 `get_entity(get_main_vid())`（`race%4` → `face_warrior/assassin/sura/shaman.sub`）。`points_changed` 信号刷新。`game_scene`：`char_status_ui` 节点 + V / C 热键。`char_status_ui_test.gd`：假 client 灌 points → 断言全部 Value label 文本 + `/stat` 命令 + `STAT==0` 隐藏加点按钮 + tab 切换页可见性。后续选道具网格 / 商店 START_EX / 私人商店 39 格照抄这套（uiscript 装载 + 逐字数值绑定 + 原聊天命令 / 封包）| `project/ui/char_status_ui.gd` · `project/game_scene.gd` · `project/char_status_ui_test.gd` |
| **组队成员信息板（`uiparty.PartyMemberInfoBoard`）** | ✅ `wire.h`：`CGPartySetState{u16 hdr,u16 len,u32 pid,u8 role,u8 on}`（static_assert 10）+ `EPartyRole` 枚举（NORMAL 0 / LEADER 1 / ATTACKER 2 / TANKER 3 / BUFFER 4 / SKILL_MASTER 5 / BERSERKER 6 / DEFENDER 7，PythonPlayer.h）。`game_client.send_party_set_state(pid,role,on)`（`CG_PARTY_SET_STATE` 0x0704，注意结构字段名 `dwVID` 实际传 PID —— 对齐 `uiparty.py OnSelectState` 的 `net.SendPartySetStatePacket(self.pid,...)`）。`M2Client.party_set_state(pid,role,on)` + bind；`get_party()` dict 补 `state`（完整角色字节，bit0=leader）+ `affects[7]`（int×7）。`project/ui/party_ui.gd` 从「名字+一条 HP」重做成 `partymemberinfoboard.py` 布局（每员 106×36 条：StateButton 22px 角色图标 + NameSlot + Gauge + 附加图标行）：`_strip(m)` → 角色状态按钮（`_local_is_leader()` 才可点 → `_open_role_popup` 弹 普通/攻击/坦克/狂战/辅助/宗师/防御 + 踢出；普通=`party_set_state(pid, cur_role, false)` 清角色；踢出=`party_leave(pid)`=`SendPartyRemovePacket`）+ 名字(★队长) + HP `ProgressBar` + `affects[i]!=0` → chip（`AFFECT_LABEL` 暂定 经验/攻击/防御/辅助/宗师/时间/回复，tooltip 带值）。点名字 → `set_target(vid)`（`OnMouseLeftButtonDown` 选中）。header：EXP 分配开关 `_toggle_distribute` → `party_set_distribute`（`EPartyExpDistributionType` 0 NON_PARITY / 1 PARITY）+ 组队治疗 `_party_heal` → `party_use_skill(PARTY_SKILL_HEAL=1, 0)`。`_local_is_leader()` = `get_party()` 里 `vid == get_main_vid()` 那条的 `leader`。角色菜单按党技能等级门控（`uiparty.__ShowStateButton` Tanker≥10…Defender≥40）暂略。`p8_test` 组队段扩：affect chip 渲染 + 队长点 StateButton 弹菜单 + 「攻击」→ `party_set_state(pid, 2, true)` + 踢出 → `party_leave` + 分配切换 → `party_set_distribute(1)` + 治疗 → `party_use_skill(1,0)` + 点名字 → `set_target` + 非队长 StateButton disabled。**顺带修 `p8_test._init` 未 `await _run()` 的隐患**（第一个 `await` 之后所有断言从未生效，含增量 34 `shop_ex`）→ 改 `await` 后暴露 `shop_ui.refresh()` `queue_free` 延迟 bug（旧 row 当帧未消失），改 `remove_child`+`queue_free` | `extension/src/net/{wire.h,game_client.h,m2_client.{h,cpp}}` · `project/ui/party_ui.gd` · `project/ui/shop_ui.gd` · `project/p8_test.gd` |
| **ESC 系统菜单 + 游戏设置窗（`uisystem.SystemDialog` + `uigameoption.OptionDialog`）** | ✅ `project/ui/system_menu_ui.gd`（`systemdialog.py` 真 uiscript，thinboard 8 键）= `uisystem.py __LoadSystemMenu_Default` 1:1：`system_option_button`→`system_option_ui.open()`，`game_option_button`→`game_option_ui.open()`，`change_button`→`client.say(0,"/phase_select")`（`net.ExitGame()` 在有 ping 时发 `SendChatPacket("/phase_select")`），`logout_button`→`"/logout"`（`net.LogOutGame()`），`mall_button`→`"/in_game_mall"`，`exit_button`→`get_tree().quit()`，`help_button`→占位 `toast`，`cancel_button`/标题栏→关。modal 打开。`game_scene`：ESC 从直接 `system_option_ui.toggle()` 改成 `system_menu_ui.toggle()`。<br>`project/ui/game_option_ui.gd`（`gameoptiondialog.py` 真 uiscript）= `uigameoption.py`：`BLOCK_BITS` = `block_{exchange,party,guild,whisper,friend,party_request}_button`(toggle_button) → `_toggle_block(bit)`：`_block_mode ^= bit` + `client.say(0, "/setblockmode %d" % _block_mode)`（`Packet.h EBlockAction` 位 `1<<0..1<<5`，逐字对照 `__OnClickBlock*` 的 `net.SendChatPacket("/setblockmode " + str(blockMode ^ player.BLOCK_*))`）+ 持久化 `[gameopt] block_mode`（服务器回包同步待补）。`PK_CMD` = `pvp_{peace,revenge,free,guild}`(radio) → `client.say(0,"/pkmode %d")` 值 `{0,1,2,4}`（`__OnClickPvPMode*`；guild 是 `/pkmode 4`，`PK_MODE_PROTECT`=3 跳过）。`DISPLAY_RADIOS`：`name_color`/`target_board`/`view_chat`/`always_show_name`/`show_damage`/`salestext` 的 on/off/normal/empire radio → `_display[key]` + 持久化 `user://system_option.cfg [gameopt]`（等价 `systemSetting.Set*Flag`；渲染侧钩子——头顶名字配色 / 伤害数字 / 聊天显隐——待补）。`_bind_radio` 处理 radio 배타성，`_sync`/`_sync_block` 开窗回填，`_relabel` 中文兜底（uiScriptLocale 未接全局 Locale）。`system_menu_ui_test.gd`：两窗装载 + `/setblockmode 1`→`3`→`2`（位 XOR）+ `_block_mode` 跟踪 + `/pkmode 1`/`4` + radio 배타 + 显示开关落 cfg + 二次实例读 `block_mode` 回填按钮态 + menu 各键 `/in_game_mall`/`/phase_select`/`/logout` + `system_option_button`/`game_option_button` 开子窗关菜单 + `cancel` 关。C++ 无改动 | `project/ui/system_menu_ui.gd` · `project/ui/game_option_ui.gd` · `project/game_scene.gd` · `project/system_menu_ui_test.gd` |
| **系统设置窗（`uisystemoption.OptionDialog`）** | ✅ `project/ui/system_option_ui.gd`：`UiScript`+`UiBuild` 装 `assets/uiscript/uiscript/systemoptiondialog.py`（board + titlebar + `music/sound_volume_controller` sliderbar + `camera_short/long` + `fog_level0/1/2` + `tiling_cpu/gpu` + `tiling_apply` + `bgm_button`）。控件绑定逐字对照 `assets/root/uisystemoption.py`：`OnChangeMusicVolume`→`snd.SetMusicVolume`+`systemSetting.SetMusicVolume`（接 `Audio.master_bgm` + 即时改在播 `_bgm[_bgm_cur].volume_db`），`OnChangeSoundVolume`→`Audio.master_sfx`（`play_ui`/`play_at` 每次读），`camera_short/long`→`game_camera.max_dist`（`CAMERA_MAX=[11,20]`，并 `dist=min(dist,max)`），`fog_level0/1/2`(浓/중/淡)→`__SetFogLevel` = `Environment.fog_enabled=true`+`fog_density=[0.055,0.018,0.004][i]`，`tiling_*`/`tiling_apply`（原 CPU/GPU 分块渲染 + `net.ExitGame` 重启）Godot 渲染器无对应 → 保留占位。`_bind_radio` 处理 radio 배타성。持久化 `user://system_option.cfg`（section `audio`/`video`，= `systemSetting` 配置文件）；`setup()` 读回并 `_apply_all()` 即时生效；`game_scene._on_main_set` 在 `.msenv` 换 `Environment` 后再 `_apply_all()`。`game_scene`：ESC 呼出（`ui_manager._unhandled_input` 先 `close_top()` 吃事件，无窗时才落到 `game_scene`）。uiScriptLocale 未接全局 Locale → `LABELS` 中文兜底。`system_option_ui_test.gd`：装载 + `music/sound` slider `value_changed` 已连 + `_on_*_volume` 应用到 `master_bgm/sfx` + camera radio→`max_dist`+dist 夹 + fog radio→`fog_density` + cfg 落盘 + 二次实例读 cfg 即时应用。C++ 无改动 | `project/ui/system_option_ui.gd` · `project/game_scene.gd` · `project/system_option_ui_test.gd` |
| **私人商店开设窗（`PrivateShopBuilder` 模型）** | ✅ `project/ui/private_shop_ui.gd` 从「前 5 行 checkbox」重做成 1:1 复刻 `assets/root/uiprivateshopbuilder.py`（**增量 36：布局改走真 uiscript `privateshopbuilder.py` —— board + TitleBar + `NameLine`(盖 LineEdit) + `ItemSlot` 5×8=40 grid + Ok/Close；背包候选面板挂窗右侧**）：`_stock` = `itemStock`（`{格号 -> {cell,vnum,count,price}}`）。左侧 `_inv_list` 背包候选（排除已上货的 cell），点一件 → `_pick` 设 `_picked`（= `mouseModule` attached item）；点右侧 40 格（`GRID_SLOTS=40` = `shop.SHOP_SLOT_COUNT`，5×8）空格 → `_ask_price`（`uiCommon.MoneyInputDialog`，`SpinBox`）→ `_place(slot, price)` 写 `_stock`（= `AddPrivateShopItemStock` + `itemStock[targetSlotPos]=(src)`）；点已占用格 → `_stock.erase` （= `OnSelectItemSlot` / `DelPrivateShopItemStock`）。`_ok()`（OkButton → `BuildPrivateShop`）：`_stock` 按格号 `sort()`、`display_pos = 格号`、`items.size() >= PRIVATE_SHOP_ITEM_MAX(39)` 截断 → `client.open_private_shop(sign, [{vnum,count,inv_cell,price,display_pos}])`（`MyShopItem`/`TShopItemTable` 字段 1:1：`{u32 vnum, u8 count, ItemPos pos, u32 price, u8 display_pos}`）。`_close_shop()` = `close_private_shop()` = `SHOP_CG_END`。测试拆成独立 `private_shop_ui_test.gd`（真 uiscript，缺资产跳过）：`_cells` 40 格 / `NameLine` 盖 LineEdit / 2 候选 / 空 stock 不发 / 拿起→价格弹窗→`_place` / 개설按格号排序（格 0 在格 3 前）+ `display_pos` / 点占用格撤下 / 철수；`shop_cube_mall_test` 私人商店段移除。C++ 无改动（`open_private_shop` / `MyShopItem` 早已就位）| `project/ui/private_shop_ui.gd` · `project/game_scene.gd` · `project/private_shop_ui_test.gd` · `project/shop_cube_mall_test.gd` |
| **`SHOP_GC_START_EX` 多货架商店** | ✅ `wire.h`：`ShopTabHead{char name[SHOP_TAB_NAME_MAX=32]; u8 coin_type}`（static_assert 33）+ `SHOP_TAB_COUNT_MAX=3`。`entity_store`：`SHOP_GC_START_EX`(10) 解析 `TPacketGCShopStartEx{u32 owner_vid; u8 tab_count}` + `tab_count` × `{ShopTabHead, ShopItem[SHOP_HOST_ITEM_MAX_NUM=40]}`（对齐 `PythonNetworkStreamPhaseGame.cpp RecvShopSub_StartEx`）。`ShopEntry` 加 `u8 pos`（货架内槽位）；`ShopTab{name, coin_type, items}` + `m_shop_tabs`；`SHOP_GC_START` 也改为按固定 40-槽数组填 `pos`（空槽计入，与参考 `SetItemData(j,...)` 一致）；`SHOP_GC_END` 清 `m_shop_tabs`。`shop_items()` 保持是 `m_shop_tabs[0].items` 的镜像，旧 `get_shop_items()` 不动。`M2Client.get_shop()` → `{vid, open, tabs:[{name, coin_type, items:[{pos,vnum,price,count}]}]}`。`shop_ui.gd`：`tabs.size()>1` 时显示货架 `Button` 行，切货架重建列表；买位置 = `_active_tab * SHOP_SLOT_COUNT(40) + it.pos`（1:1 对齐 `uishop.py GetIndexFromSlotPos` = `tabIdx * shop.SHOP_SLOT_COUNT + slotPos`，`shop_buy` 的 `u8 pos` 容得下 3×40）。`net_entity_test`：双货架合成包 → 断言名称 / coin_type / 槽位保留 / tab0 镜像 / END 清空；`p8_test`：多货架 UI + 切页 + `buy pos 5`（tab0 slot5）/ `buy pos 43`（tab1 slot3） | `extension/src/net/{wire.h,entity_store.{h,cpp},m2_client.{h,cpp}}` · `project/ui/shop_ui.gd` · `extension/tests/net_entity_test.cpp` · `project/p8_test.gd` |
| **选魔石窗（样板第 2 例）** | ✅ `project/ui/select_item_ui.gd`：`UiScript`+`UiBuild` 装 `assets/uiscript/uiscript/selectitemwindow.py`（`ItemSlot` = 5×8 `grid_table`，`ui_build._slot_cells` 按 `x_count/start_index/x_step/y_step` 生成 `slot_0..39`）。填格逐字照 `assets/root/uiselectitem.py.RefreshSlot`：遍历背包 `range(INVENTORY_PAGE_SIZE*2=90)` 格，`_is_metin`（`proto.item(vnum).type == 10 = ITEM_TYPE_METIN`）+ `_item_grade(vnum) <= 2`（= `proto.item(vnum).name` **内部名**最后一位数字，非数字按 0，复刻 `PythonPlayerModule.GetItemGrade`），`slotPos > 54` 截断，按背包格号升序映射到选择窗格 `_slot_to_inv[slotPos]=invCell`。点格 → `client.script_select_item(invCell)`（`send_script_select_item` → `CGScriptSelectItem{CG_SCRIPT_SELECT_ITEM 0x0903, len, selection}`，= `net.SendSelectItemPacket`）+ 关窗；`ExitButton` / 标题栏关闭 → `script_select_item(0)`（`uiselectitem.Close`），`_sent` 标记避免选完再补发 0。**触发链 1:1**：`quest_dialog.gd.parse_script` 新识别 EventManager `[SELECT_ITEM]` token → `has_select_item` → `_on_script` 发新 `select_item_requested` 信号（对应 `PythonEventManager EVENT_TYPE_SELECT_ITEM` → `interfacemodule.BINARY_OpenSelectItemWindow` → `wndItemSelect.Open()`）；`game_scene` 在 `proto`/`item_list` 就绪后建 `select_item_ui` 并把该信号接到 `.open`。`select_item_ui_test.gd`：`[SELECT_ITEM]` token 解析 + 非 metin / grade>2 过滤 + 升序映射 + 点格发 `script_select_item(7)` + 关窗不补发 + 空手关窗发 `script_select_item(0)` | `project/ui/select_item_ui.gd` · `project/ui/quest_dialog.gd` · `project/game_scene.gd` · `project/select_item_ui_test.gd` |
| **`item_proto` / `mob_proto` 读取器** | ✅ `mtproto::load_proto` —— 外层 `MIPX`(item：`[fourcc][ver=1][stride][elements][datasize]`) / `MMPT`(mob：`[fourcc][elements][datasize]`)；内层 `MCOZ` CLZO 容器 = **XChaCha20**（本 fork 把 TEA 换成 libsodium：key=BLAKE2b(key16,"M2DevPackEncrypt")，nonce=BLAKE2b(key16,"M2DevNonce")[:24]）解密 + **LZO1X** 解压。两把硬编码 4-DWORD key（`ItemManager.cpp` / `PythonNonPlayer.cpp`）。`ItemRecord`/`MobRecord` 解前导字段（`bSpecular`@234 → §2.7；**`alValues[6]`@191** —— aLimits[2]×5 @166 + aApplies[3]×5 @176 后，`bSpecular`@234 锚定整链）。armor 的 `alValues[3]` = race `.msm` 的 body shape index（对齐客户端 `__ArmorVnumToShape` `SHAPE_VALUE_SLOT_INDEX=3`）—— 实测 "Monk Plate Armour" 11200-09 全 = shape 3，specular 随强化 0→100 递增。`proto.item_mob` CTest 断言 11209 `values[3]==3` + `specular==100`。5748 items（stride 236）+ 1338 mobs（stride 335） | `extension/src/proto/proto.{h,cpp}` |
| **`AssetResolver` 接包**（首版）| ✅ `mtpack::PackMount` —— 挂载多个 `.epk`，按虚拟路径（盘符 + 反斜杠 + 大小写不敏感 + `ymir work/` 后缀）resolve/read，`metin2_patch_*` 包后挂覆盖。`mtpack::AssetSource` —— 散文件 + 包统一：`read()` 取字节；`to_path()` 把包内文件解到缓存目录一次（路径型调用方不用改）。散文件优先于包（dev overlay，对齐客户端 `pack/` 覆盖）。`pack.roundtrip` CTest 扩：2 包挂载 + 覆盖 + 虚拟路径 + 非 ymir 路径。⬜ 把 `Metin2World`/`Metin2Model` 等 ~6 处 `resolver->resolve()` 换成 `AssetSource::to_path()`（机械改动）| `extension/src/pack/{pack_mount,asset_source}.{h,cpp}` |
| **输入 & 游戏相机**（首版）| ✅ `game_camera.gd` = `GameCamera`：右键拖拽环绕（yaw/pitch clamp）+ 滚轮缩放（3.5–20m）+ 目标平滑跟随 + 地形防穿。`player_controller.gd` = `PlayerController`：**点地移动**（射线求地表交点 → 走过去，沿途 `is_blocked`（`attr.atr` bit0）判可行走，贴墙磨蹭按实际位移切回 wait —— 客户端预测，无服务端纠正）+ WASD 覆盖 + **选目标**（射线取最近 pickable → `target_selected` 信号）+ `anim_state`/`moved` 信号。已换进 `world_demo.gd`（去掉 ~70 行临时相机/输入）。⬜ 相机撞建筑/树淡出（§8.2）、格子 A* 寻路、NPC 交互/拾取 | `project/{game_camera,player_controller}.gd` |
| **本地化**（首版）| ✅ `locale.gd` = `Locale`：加载 `locale/locale/<lang>/{locale_interface,locale_game,itemdesc,skilldesc}.txt`（`KEY\tVALUE`，UTF-8）。`t(key, args)` —— `%` 格式化 + 缺失回 `<KEY>`（开发期可见）；`set_lang()`；`apply_font()` 挂 CJK ttf。已接 `charselect`（`JOB_*` 职业名 / `SELECT_LEVEL` / `SELECT_SELECT`=Start / `SELECT_CREATE`）+ `login`（`LOGIN_ID`/`LOGIN_PASSWORD`/`LOGIN_CONNECT`）。18 语言（拉丁/西里尔/希腊/阿拉伯，Godot 原生，无需打包字体；CJK 需外挂 ttf）| `project/locale.gd` |
| **声音**（首版）| ✅ `audio.gd` = `Audio` 节点：**BGM 交叉淡**（2× `AudioStreamPlayer`，`bgm/*.mp3`）+ **UI 音效池**（8×，`**/sound/ui/*.wav`）+ **3D 定位音效**（`AudioStreamPlayer3D`，`**/sound/<rel>`）。路径解析走 11 个声音根 + `bgm/`（`.mss` 不用，Godot 原生解 mp3/wav/ogg）。已接：`charselect`→`characterselect` BGM + `<class>_select` 选人音；`login`→`loginok`/`loginfail`；`world_demo`→`Metin2AnimPlayer.motion_event` 的 `sound` 字段 → `play_at(model_pos)`（脚步/挥击）。⬜ 按地图 BGM（服务端 `GCMainCharacter.szBGMName`）、`.msenv` 环境音循环、战斗/怪物/NPC 语音 | `project/audio.gd` |
| 登录 / 选人界面 | 🟡 首版 | `project/{login,charselect,ui_kit}.gd` |
| 声音（`AudioLib`→Godot audio）| 🟡 首版 | `project/audio.gd` |
| `item_proto` / `mob_proto` 读取器 | ✅ | `extension/src/proto/proto.{h,cpp}` |
| 本地化（`EterLocale`）| ✅ 首版 | `project/locale.gd` |
| 输入 & 游戏相机 | 🟡 首版 | `project/{game_camera,player_controller}.gd` |
| `AssetResolver` 从包读取（接 eterpack）| 🟡 | `extension/src/pack/{pack_mount,asset_source}.{h,cpp}` |
## 3c. C 轨（渲染打磨，PARITY-GAP 不卡 §0 门禁的项）
| 项 | 状态 | 位置 |
|---|---|---|
| §8.2 相机遮挡淡出 + §8.3 相机撞建筑防穿 | ✅ 首版 | `extension/src/metin2_world.cpp`（层 2 盒碰撞）+ `project/game_camera.gd` |
| §2.2 GPU 路径发型 | ✅ | `extension/src/metin2_model.{h,cpp}` |
| §2.10 角色 LOD 距离切换 | ✅ 首版 | `extension/src/metin2_model.{h,cpp}` |
| §3.5 地形 patch 裁剪 | ✅ 首版（拆 4×4 patch + 逐 patch 视锥剔除 + 远景剔除）| `extension/src/metin2_world.{h,cpp}` |
| §2.6 顶点色 | ✅ 排查=不适用（全资产 gr2 无顶点色成员；逐顶点色是地形雾运行时 VB + `.mse` colorfactor）| — |
| §1.2 `.mse` EffectLib 端口 | ⬜（大工程）| — |
## 4. 下一步
> **本节 1–4 项已于 2026-08-30 全部完成**（见 §3 与 [`CLIENT-ROADMAP.md`](./CLIENT-ROADMAP.md)
> 的 P0–P10）。保留为当时的计划记录，不要再当作待办执行。
1. ~~打通到 `.203` 的连通性~~ ✅。可达后立即能测：
- `./build/extension/net_probe 192.168.21.203 11000 admin 123456789` → 完整握手 + `CGLogin3` → `login_key`
- GDScript 里 `M2Client.connect_to_server(...)` → 一路到 `char_list` / `entered_game`
2. **`GCLoginSuccess3` 布局对真实字节校准**：`net_probe` / `M2Client` 收到后 dump 原始字节，
核对 `TSimplePlayerInformation`（现假设 pack(1)、字段顺序照 `Packet.h:1161`）。size 不符会走
`login_failed` 兜底。
3. 游戏相位包解码：`GC_CHARACTER_ADD/DEL` / `GC_MOVE` / `GC_CHARACTER_UPDATE` →
`NetworkActorManager` 端口 → 每实体一个 `Metin2Model`+`Metin2AnimPlayer`，用现有
`Metin2World` 当场景。里程碑「角色连上、站在地图里、别的实体在动」。
4. 输入（点地移动 → `CG_MOVE`）、聊天（`CG_CHAT`/`GC_CHAT` 接 HUD）。
## 5. 风险
- **协议版本漂移**：`Packet.h` 结构体要和服务端 build 一致。冻结一对 client/server commit。
- ~~**端到端测试阻塞**：目前握手端口 refused，走不到 `CGLogin3` 之前的验证。~~ 已解除（§3）。
- **移动端 libsodium**：Android/iOS 要静态 vendor（本身可移植，非阻塞）。
- 自用范围可跳过：商城 / GM 工具 / 部分社交系统。**反作弊（`CG_HACK` / `ProcessCRC` /
`ProcessScanner`）已在 `CLIENT-GAP.md`「不做清单」标注 ❌ 不做**，除非服务端强制校验。
## 6. 移植面（客户端源码）
`EterBase/SecureCipher` · `EterLib/{NetStream,ControlPackets,NetPacketHeaderMap}` ·
`UserInterface/{Packet.h, AccountConnector, PythonNetworkStream, PythonNetworkStreamPhase*}` ·
`UserInterface/NetworkActorManager`（实体） · `GameLib`（玩法）。
docs/CLIENT-REFACTOR-40250-PLAN.md
+263
View File
@@ -0,0 +1,263 @@
# 客户端重构与 40250 逻辑对齐实施方案
## 1. 现状诊断与核心痛点
### 1.1 现状与优势
- **渲染层（已基本稳定）**：
- `extension/src/metin2_model.{h,cpp}`：基于开源 libgr2 的模型网格解析、材质贴图加载、GPU/CPU 骨骼蒙皮。
- `extension/src/metin2_anim.{h,cpp}`：骨骼动画采样、双动画平滑融合（Crossfade）、挂点武器同步。
- `extension/src/metin2_world.{h,cpp}`：地形高度场采样、贴图混合、水体、静态建筑碰撞。
- `project/game_camera.gd`：轨道摄像机、防穿模逻辑。
- **结论**：渲染层已具备优秀的跨平台能力（macOS/iOS/Android/Linux/Web），**无需推倒，纯粹作为“哑终端”画面渲染器（View）予以保留**。
### 1.2 逻辑层的混乱根源
当前各种 Bug（“WASD翻跟头”、“连击不流畅/手感怪异”、“NPC交互后商店空白”、“任务无法打开”）的共同根源在于：
1. **庞大的 GDScript 意大利面条代码**：
- `net_play.gd` (~2200 行)、`game_scene.gd` (~1800 行)、`net_world.gd` (~1760 行) 试图用 GDScript 凭空重写 40250 的几万行 C++ 客户端逻辑。
2. **凭感觉实现的“伪逻辑”**：
- 没有严格对照 40250 C++ 源码的状态机（如按键优先级、阻尼公式、连击输入窗、NPC点击距离分流、封包处理链），而是用自制计时器和启发式逻辑拼接，导致产生大量边界 Bug 和时序脱节。
3. **数据没有单一真实来源（Single Source of Truth）**：
- 实体数据同时散落在 C++ `EntityStore`、`net_play.gd`、`net_world.gd`、`client.ents` 和 `node.meta` 中，互相通过数十个信号来回同步，极易丢状态或时序错乱。
---
## 2. 1:1 复刻的边界与原则（复刻哪些，不复刻哪些）
> [!IMPORTANT]
> **核心原则**：**“形式上”不要 1:1 照搬类文件，但“内核上”必须 1:1 严格对齐封包、状态机与数学公式。**
### 2.1 坚决不要 1:1 复刻的部分（直接使用 Godot 原生）
40250 源码中超过 60% 的代码是在重复造 2004 年 DirectX 8 / Windows 的轮子，这些在现代跨平台环境中是沉重的技术包袱：
| 40250 原版模块 | 为什么不要 1:1 复刻 | Godot 现成替代方案 |
| :--- | :--- | :--- |
| **`EterLib` 图形底层**<br>(`CGraphicDevice`, `CStateManager`, `CRenderTarget`) | 深度强绑定 DirectX 8/9，引入会导致无法在 macOS (Metal) 及移动端 (Vulkan) 编译。 | **Godot 渲染引擎**（原生支持 Metal / Vulkan / WebGL） |
| **`EterPythonLib` 2D UI 系统**<br>(`CWindowManager`, `CWindow`, `CButton`, `CScrollBar`) | 20 年前手工编写的固定坐标 2D 贴图拼接系统，不支持高分屏自适应、矢量字体、触屏手势。 | **Godot Control 体系**（完善的锚点自适应、触屏支持） |
| **`milesLib` 音频系统** | 2004 年的 Miles 闭源声卡驱动库。 | **Godot AudioServer / AudioStreamPlayer** |
| **`CCamera` 摄像机类** | 自行维护的 D3D 视锥矩阵，死板且不灵活。 | **Godot `Camera3D`**（现有的 `game_camera.gd` 表现良好） |
| **`EterGrnLib` 模型封装** | 依赖 Granny 2.8 闭源 Windows DLL。 | **现有 `metin2_model` + `metin2_anim`**（基于开源 libgr2，功能已完备） |
| **内嵌 Python 2.7 解释器** | Python 2.7 早已停止维护，在 iOS / Android 上打包极其臃肿且受 App Store 审核限制。 | **C++ 纯逻辑导出给 GDScript 调用** |
### 2.2 必须 1:1 严格复刻的部分（下沉至 C++ GDExtension 核心逻辑层）
下面这些是 Metin2 的“灵魂与运行规则”，必须 100% 对齐 40250 源码，漏掉一个判断分支就会导致手感完全走样：
1. **网络协议与封包结构（1:1 严丝合缝）**：
- 对应源码：`Packet.h`
- 要求：每个 `TPacketGC*`（如 `TPacketGCShop`、`TPacketGCCharacterAdd`、`TPacketGCDamageInfo`）的结构体字段、字节对齐、Subheader 常量 100% 照搬。
2. **角色移动与物理状态机（1:1 算法复刻）**：
- 对应源码：`PythonPlayerInput.cpp`、`InstanceBaseMovement.cpp`、`ActorInstanceMovement.cpp`
- 要求：按键优先级判定（`NEW_GetMultiKeyDirRotation`）、转向角 45° 阻尼与防过冲单向贴齐（`GetRotatingDirection`、`SetAdvancingRotation`）、碰撞切线滑移（`AdjustDynamicCollisionMovement`）、位移累加（`__AccumulationMovement`）。
3. **战斗与打击判定状态机（1:1 状态机复刻）**：
- 对应源码：`ActorInstanceBattle.cpp`、`InstanceBaseBattle.cpp`
- 要求：连击段位状态转移（Combo 1→2→3→4）与按键输入时间窗（`ComboInputData`）、`.msa` 多命中时间窗（`HitDataContainer`）的毫秒级触发、普通受击方位判定与击倒击飞硬直。
4. **业务数据模型与操作上下文（1:1 逻辑复刻）**：
- 对应源码：`PythonShop.cpp`（商店货架数据）、`PythonQuest.cpp`（任务状态树）、`PythonPlayerSkill.cpp`（技能冷却与释放条件三门）。
---
## 3. 架构重构结论与策略
### 3.1 架构重构的必要性
现有项目积累了大量技术债务，表面上看是“连击不连贯”、“WASD翻跟头”、“NPC打不开商店”等散发 Bug，深层原因是架构失衡：
1. **“上帝文件（God Class）”过载**：`net_play.gd` (2200+行) 与 `game_scene.gd` (1800+行) 把网络封包解码、角色状态、背包/商店业务、3D渲染节点管理、点击拾取、UI开关全部混在一起，牵一发而动全身。
2. **缺乏单一真实来源（No Single Source of Truth）**：角色坐标、朝向、连击段位在 `player_controller`、`net_play`、`net_world` 和 C++ `EntityStore` 中各自维护，靠数十个信号来回同步，极易时序混乱或丢状态。
3. **启发式“伪逻辑”**：没有遵循 40250 的严密数学公式与状态机，而是用散落的计时器和直觉代码修补。
### 3.2 重构策略：拒绝推倒重来，采用“绞杀者式渐进解耦（Strangler Fig Pattern）”
- **保留成果（绝不推倒）**：已稳定的 C++ GR2 渲染层（`metin2_model`、`metin2_anim`、`metin2_world`）和摄像机防穿模逻辑完全保留。
- **业务逐块下沉**：按“战斗 -> 商店/NPC -> 任务 -> 背包”的顺序，把上帝文件中的业务逐个抽成独立的 Manager/状态机，先解耦跑通，再下沉对齐 40250。
---
## 4. 推荐的目标系统架构（`extension/src/m2_core/`）
在 C++ GDExtension 中建立清晰、模块化、无 DirectX 依赖的逻辑层：
```
extension/src/m2_core/
├── protocol/ # 1:1 严格对齐 40250 的网络层
│ ├── packets.h # 1:1 复制 40250 Packet.h 的所有包结构体
│ └── packet_dispatcher.h # 1:1 复制 PythonNetworkStreamPhaseGame 的封包解析分发
│
├── player/ # 1:1 复制 CPythonPlayer 的核心逻辑
│ ├── player_input.cpp # 1:1 移植 PythonPlayerInput.cpp (按键优先级、朝向合成、预约动作)
│ ├── player_state.cpp # 1:1 移植 玩家属性、金币、背包、技能CD数据
│ └── player_combat.cpp # 1:1 移植 连击判定、攻击输入窗
│
├── world/ # 1:1 复制 CPythonCharacterManager & CInstanceBase
│ ├── instance_entity.cpp # 1:1 移植 实体状态机、45°阻尼移动、切线碰撞滑移
│ └── combat_resolver.cpp # 1:1 移植 命中范围、受击硬直计算
│
└── gameplay/ # 1:1 复制业务逻辑数据源
├── shop_system.cpp # 1:1 移植 PythonShop.cpp (解决商店商品空白)
└── quest_system.cpp # 1:1 移植 PythonQuest.cpp (解决NPC任务交互)
```
### 运行时数据与渲染流向：
```mermaid
flowchart TD
subgraph View ["Godot 4 表现与输入层 (View & Input)"]
InputHandler["Input / Touch / UI 事件捕获"]
GodotNodes["PlayerView / MobView (Metin2Model + Metin2AnimPlayer)"]
UI_Screens["ShopUI / QuestUI / InventoryUI / CharacterUI"]
end
subgraph LogicCore ["GDExtension 40250 纯逻辑核心 (Core Logic)"]
CPP_Input["PlayerInput (按键优先级/朝向合成/输入队列)"]
CPP_Move["InstanceEntity (45°阻尼/切线滑动/累积位移)"]
CPP_Combat["Combat & Combo (命中窗/连击状态机)"]
CPP_Net["NetworkStream & Dispatcher (收发严丝合缝对齐 40250)"]
CPP_Data["Shop & Quest Data (货架缓存/任务对话树)"]
end
subgraph Server ["40250 游戏服务端"]
GameServer["TCP Server"]
end
InputHandler -->|按键/点击事件| CPP_Input
CPP_Input --> CPP_Move
CPP_Move -->|状态包| CPP_Net
CPP_Combat <--> CPP_Net
CPP_Net <-->|TCP 封包| GameServer
CPP_Move -.->|输出权威坐标 (x,y,z) 与朝向 yaw| GodotNodes
CPP_Combat -.->|输出当前动作名、时间与打击帧| GodotNodes
CPP_Data -.->|响应数据变动通知| UI_Screens
```
---
## 5. 移动端（iOS / Android）操作界面与跨端支持设计
> [!NOTE]
> **结论**：**当前规划的解耦架构天然、完美支持后续无缝接入移动端专属操作界面与触控系统。**
### 5.1 核心解耦机制：输入意图抽象层（Input Intent Abstraction）
重构后的架构将**“硬件输入采集”**与**“游戏角色行为”**彻底解耦。底层逻辑不再监听 `KEY_W`、`KEY_SPACE` 或鼠标点击，而是消费高阶**输入意图（Input Intents）**：
```mermaid
flowchart TD
subgraph InputSources ["输入源采集（多端隔离）"]
PC_Input["PC 桌面端输入<br>(WASD / 鼠标左右键 / 快捷键 1~4 / 空格)"]
Mobile_Input["移动端触控输入<br>(虚拟摇杆 / 技能轮盘 / 普攻大按钮 / 目标切换)"]
end
subgraph IntentLayer ["输入意图抽象接口 (PlayerInputIntent)"]
I_Move["move_intent(dir: Vector2, is_run: bool)"]
I_Attack["attack_intent()"]
I_Skill["skill_intent(slot_idx: int)"]
I_Target["target_intent(vid: int)"]
I_Interact["interact_intent(vid: int)"]
end
subgraph CoreLogic ["40250 核心状态机 (跨平台纯逻辑)"]
M2_Move["45° 转向阻尼 / 切线滑移碰撞"]
M2_Combat["连击输入时间窗 / 多段命中判定"]
M2_Target["500cm 距离门限 / 预约走向交互"]
end
PC_Input -->|转换映射| IntentLayer
Mobile_Input -->|转换映射| IntentLayer
IntentLayer --> CoreLogic
```
1. **移动控制无缝适配**：
- PC 端：WASD 键位经过 40250 `NEW_GetMultiKeyDirRotation` 算成方向向量。
- 移动端：屏幕左侧的**虚拟摇杆（Virtual Joystick）**直接输出方向向量给 `move_intent`，底层 45° 转向阻尼与碰撞滑移算法无需修改一行代码。
2. **战斗与技能轮盘**：
- 移动端右侧可布局经典“大按键普攻 + 环形技能轮盘”，普攻按钮每次点击触发 `attack_intent()`，底层直接进入 40250 的 `ComboInputData` 输入缓冲队列。
### 5.2 双端自适应 UI 表现层（Dual-Mode Adaptive UI）
由于业务数据（`ShopManager`、`InventoryManager`、`QuestManager`）已与界面彻底解耦：
- **数据核心统一**：所有数据模型只负责维护商品列表、道具属性、背包格子、对话选项，通过信号/事件对外广播。
- **UI 视图按端加载**：
- PC 端：加载 `DesktopHUD.tscn`（支持鼠标 Hover 查看装备 Tooltip、右键穿戴、拖拽格子）。
- 移动端：根据 `OS.has_feature("mobile")` 或屏幕分辨率动态加载 `MobileHUD.tscn`（更大的触控热区、点击弹出操作抽屉 Drawer、全屏大卡片商店展示）。
- **完全零冗余**：两套 UI 共享 100% 的底层数据逻辑、网络协议与状态机。
---
## 6. 分阶段实施路线图
按照“**先主要解决战斗系统不一致，再解决 NPC/商店/任务交互混乱**”的优先级分步推进：
### 阶段一：战斗与连击系统精准对齐（优先级：最高）
> 对应 40250 源码：`ActorInstanceBattle.cpp`、`InstanceBaseBattle.cpp`、`formats/msa.h`
1. **普通攻击与连击链（Combo Chain）1:1 复刻**：
- 移植 40250 `ActorInstanceBattle.cpp:157-308` 状态机：
- `m_dwcurComboIndex`（连击段数 1→2→3→4）
- `ComboInputData`：严格按照 `.msa` 的 `InputStartTime`、`InputEndTime`、`NextComboTime` 判定是否允许按下一次普攻。
### 阶段一：移动与战斗核心状态机 40250 对齐（优先级：最高）✅ [COMPLETED]
> 对应 40250 源码：`PythonPlayerInput.cpp`、`ActorInstanceBattle.cpp`、`InstanceBaseBattle.cpp`
1. **废弃原有人为的外层普攻 CD 拦截**：
- 彻底废除 `_attack_cd` 吞键逻辑，完全对齐 40250 普攻/连击内禀门控机制。
2. **严格 1:1 接入 `.msa` 的连击输入数据窗**：
- 读取并严格应用 `duration`、`InputStartTime`、`NextComboTime`、`InputEndTime`。
- 完美支持长按空格连续 4 击（1→2→3→4 段无缝切换与回 Wait 重置）与快速连点。
3. **受击与击倒对齐**：
- 动作播放时长内动态释放受击锁，触发屏幕震颤与击退同步。
### 阶段二：NPC 交互与商店系统修复（优先级：高）✅ [COMPLETED]
> 对应 40250 源码：`PythonPlayerInputMouse.cpp`、`PythonNetworkStreamPhaseGame.cpp`、`PythonShop.cpp`、`uishop.py`
1. **NPC 点击与预约走向交互（__OnClickActor）**：
- 点击 NPC：距离 `<= 500 cm`（`CLICK_DIST_NPC`）立即停步、面朝 NPC 发送 `HEADER_CG_ON_CLICK` (26)。
- 距离 `> 500 cm`：进入 `m_eReservedMode = CLICK_ACTOR` 预约模式，驱动角色寻路靠近，进入 500cm 瞬间停步交互。
- 加入 40250 `CPythonPlayer::__SendClickActorPacket` 的 1000ms 狂点节流保护。
2. **修复商店数据流与属性丢失（彻底解决白板商品 Bug）**：
- C++ `mtnet::ShopEntry` 补齐 `sockets[3]` 与 `attrs[7]`，解析 `START` / `START_EX` / `UPDATE_ITEM` 全量属性。
- `m2_client` 修复切页被冲掉问题，仅在初次打开触发 `shop_opened`，格位更新触发 `shop_updated(pos)`。
- UI 接入 40-slot 货架、多 Tab 切换（`tabIdx * 40 + slot`）、右键直接秒买（`UnselectItemSlot`）、超出 10m 离开自动关闭窗口。
### 阶段三：任务系统与对话流对齐（优先级：中）✅ [COMPLETED]
> 对应 40250 源码：`PythonEventManager.h/cpp`、`PythonQuest.cpp`、`PythonNetworkStreamPhaseGame.cpp`（`RecvScriptPacket`）、`uiquest.py`
1. **40250 任务与 NPC 交互协议全套对齐**：
- 封包层精准对齐：`HEADER_GC_SCRIPT` (45)、`HEADER_CG_SCRIPT_ANSWER` (29)、`HEADER_CG_SCRIPT_BUTTON` (66)、`HEADER_CG_QUEST_INPUT_STRING` (30)、`HEADER_GC_QUEST_CONFIRM` (46)、`HEADER_CG_QUEST_CONFIRM` (31)。
- 在 C++ 网络会话层 (`ClassicSession`) 与 `M2Client` 实现全套安全发包接口：`send_script_answer`、`send_script_button`、`send_quest_input`、`send_quest_confirm`、`send_quest_cancel`。
2. **40250 `CPythonEventManager` 脚本语法与表现层 1:1 解析**：
- 支持标准 40250 分号/管道符问题格式 `[QUESTION 1;选项一|2;选项二|...]`，0-indexed 答案映射，保留向后兼容旧格式。
- 实现 40250 `uiquest.py` 8 选项多页分页机制（`MAX_CHOICES_PER_PAGE = 8`），自动挂载 `[上一页]` / `[下一页]` 导航行，精确计算全局索引 `page * 8 + slot`。
- 皮肤与立绘对齐：`SKIN_NOWINDOW` (1) 与 `SKIN_CINEMA` (5) 隐藏背景板；`LEFTIMAGE` 自动偏移文本与按钮内容区宽度。
- 支持 `[INPUT]` 文本输入框即时提交、`[NEXT]` 剧情推进与 `[DONE]` 流程收尾（`script_answer(254)`），以及 ESC 键安全取消（`OnCancel`）。
- 编写 `test_quest_dialog_parity.gd` 覆盖 9 大测试场景 45 项断言全部 100% 通过。
### 阶段四：角色属性面板、背包与技能系统对齐（优先级：中）✅ [COMPLETED]
> 对应 40250 源码：`PythonPlayerSkill.cpp`、`PythonSkill.h`、`PythonItem.cpp`、`GameType.h`、`Packet.h`、`uicharacter.py`
1. **主动技能释放链与三层完整门控（40250 CheckSkillUsable 对齐）**：
- 严格 1:1 实现死亡状态（`CANNOT_ACT`）、安全区攻击拦截（`IN_SAFE`，增益 Buff 技能放行）、武器类型匹配（`NOT_MATCHABLE_WEAPON`）、弓箭数量检验（`EMPTY_ARROW`）、SP/HP 消耗门检（`NOT_ENOUGH_SP`）、冷却时间阻断（`WAIT_COOLTIME`）以及施法距离/目标判定（超出距离进入 `RESERVED` 预约模式，进入范围后放行）。
2. **装备与背包双端线协议对齐（40250 ItemPos 对齐）**：
- `_to_wire` 严格映射 40250 `TItemPos`：背包槽位 `0..89` 映射 `WINDOW_INVENTORY (1)`；装备槽位 `90..100` 映射 `WINDOW_EQUIPMENT (2)` 且内部 cell 严格从 `0` 开始偏移；时装槽位 `109..113` 映射 `WINDOW_INVENTORY (1)`。
- 右键穿脱发送 `HEADER_CG_ITEM_USE` (11)，拖拽移动发送 `HEADER_CG_ITEM_MOVE` (12)，并严格走 `EquipRules` 职业、等级（`LIMIT_LEVEL`）与性别门控。
3. **角色属性面板实时换算与指令对齐（uicharacter.py:RefreshStatus 对齐）**：
- 物攻格式严格呈现 `min-max`（或相等时单值显示）、物防 `DEF_GRADE + DEF_BONUS`、魔攻 `MAG_ATT + MAGIC_WEP` 纯正公式。
- 加点与洗点协议通过安全网络通道发送原生 `/stat ht`、`/stat iq`、`/stat st`、`/stat dx` 与 `/stat-` 指令。
4. **快捷栏（Quickbar）持久化与全量同步（40250 TQuickSlot 协议）**：
- 快捷栏配置新增发送 `HEADER_CG_QUICKSLOT_ADD` (16)（支持技能、物品、动作表情）、交换发送 `HEADER_CG_QUICKSLOT_SWAP` (18)、清空发送 `HEADER_CG_QUICKSLOT_DEL` (17)，并支持全量 36 格状态本地与服务端双向恢复。
- 编写 `test_skill_inventory_parity.gd` 覆盖 4 大领域 42 项测试断言全部 100% 通过。
---
## 7. 技术实施规范
1. **严禁“自造算法”**：
- 任何涉及移动、旋转、连击、受击、技能、网络包逻辑的代码，必须明确注明对应的 40250 源码文件和行号（例如 `// 对齐 40250 ActorInstanceBattle.cpp:215`），1:1 复刻其状态转移条件。
2. **职责边界分明**：
- **C++ (GDExtension)**：拥有所有数据、状态机、网络封包、物理数学计算。
- **GDScript / Godot Node**：只做两件事：① 把 C++ 的位置和动作画在屏幕上；② 把屏幕上的按键和点击事件传给 C++。
3. **严格单向数据流**：
- 废除 GDScript 层各节点之间混乱的信号交叉监听，所有状态统一归拢到核心状态机。
---
## 8. 验证计划
1. **单元测试与 Headless 自动化测试**：
- 为连击状态机编写类似 `test_wasd_steering_parity.gd` 的无头自动化回归测试。
- 模拟封包注入测试商店数据解析与 NPC 交互流程。
2. **实服联机验证**：
- 配合真实 40250 服务端，联机点击杂货商/铁匠，验证商品列表 100% 正常展示并成功购买。
- 联机打怪，验证普通攻击连击节奏、打击僵直与伤害数字飘字时机与原版客户端完全吻合。
docs/CLIENT-ROADMAP.md
+4 -4
View File
@@ -1,7 +1,7 @@
# 客户端玩法开发计划
> 把 [`CLIENT-GAP.md`](./CLIENT-GAP.md) 的缺口排成可执行的阶段计划。
> 网络栈进度见 [`CLIENT-PORT.md`](./CLIENT-PORT.md)，渲染见 [`PARITY-GAP.md`](./PARITY-GAP.md) / [`BACKLOG.md`](./BACKLOG.md)。
> 网络栈进度见 [`CLIENT-40250-PORT.md`](./CLIENT-40250-PORT.md)，渲染见 [`PARITY-GAP.md`](./PARITY-GAP.md) / [`BACKLOG.md`](./BACKLOG.md)。
>
> 规模：S ≤ 3 天 · M ≈ 1 周 · L ≈ 2–3 周 · XL ≈ 1 月+
> 标记：🌐 需服务器端到端 · 💻 离线可做（mock server / 合成封包 / 假 client）
@@ -197,7 +197,7 @@ motion_name 就是特效基名，上一轮列偏移修好后自然接上）；
**已验证**：`net.entity_store` 扩展（`GC_SCRIPT` 带 `[QUESTION]` → `ScriptCue`；`GC_QUEST_CONFIRM` → `ConfirmCue`；`GC_QUEST_INFO` 带 TITLE+COUNTER flag → `QuestInfo` 变长尾解析，`length` 字段回填）；`quest_test.gd`（`parse_script`：纯文本保留 / `[ENTER]`→换行 / `[QUESTION]`→2 选项 / `[DONE]`→继续钮；`script_dialog` 信号 → 弹窗 + 3 选项钮 + 选 B → `script_answer(1)` + 关窗；无选项 → 继续 → `script_answer(255)`；`quest_confirm_ask` → 接受 → `quest_confirm(true,999)`；quest_log 只显示有标题的 quest + `quest_info` 刷新不炸）。13 个 GDScript 测试套件全绿，ctest 9/9，iOS 编过。
**未完成**：`[INPUT]` 文本输入 UI（`CGQuestInputString` 封包已备）、`SCRIPT_SELECT_ITEM` 选道具、NPC 对话左右立绘、`[QUESTBUTTON]` → `script_button`、地图 / 世界任务箭头（`TARGET_CREATE_TYPE_LOCATION`）、端到端（见 `CLIENT-PORT.md` §3：握手 + 认证已联通，进游戏串场归 P10）。
**未完成**：`[INPUT]` 文本输入 UI（`CGQuestInputString` 封包已备）、`SCRIPT_SELECT_ITEM` 选道具、NPC 对话左右立绘、`[QUESTBUTTON]` → `script_button`、地图 / 世界任务箭头（`TARGET_CREATE_TYPE_LOCATION`）、端到端（见 `CLIENT-40250-PORT.md`：握手 + 认证已联通，进游戏串场归 P10）。
## P8 — 社交 / 商店 / 仓库（XL，🌐）
@@ -290,7 +290,7 @@ motion_name 就是特效基名，上一轮列偏移修好后自然接上）；
（协程化的 `setup()` 让 `entity_spawned` 接得晚，会漏初始 spawn 洪流）；`game_scene` 先
`set_local_vid` + `net_play._on_main_set` 再 `catch_up`，避免本地玩家被画成压身的蓝胶囊。
详见 `CLIENT-PORT.md` §3。**23 套 GDScript + 10 CTest + 项目导入 + macOS/iOS 扩展全绿。**
详见 `CLIENT-40250-PORT.md`。**23 套 GDScript + 10 CTest + 项目导入 + macOS/iOS 扩展全绿。**
**剩的不是代码问题**：字面在线人数（Metin2 协议只有 4 态负载，要数字得改服务器）、全量 monster 资产。
---
@@ -313,7 +313,7 @@ PHASE_GAME —— 收到 121 个实体、HP/SP/等级、20 格背包、好友列
1. ~~真机字节校准第二轮~~ ✅ 已做（2026-08-30）：`GC_SKILL_LEVEL_NEW`(0x021B，本服才发这个，
之前技能窗全空) + `GC_QUICKSLOT_*`(0x0519/1A/1B) 补上；`GC_NPC_POSITION` / `GC_ITEM_UPDATE` /
`GC_CHAT` / `GC_AFFECT_ADD` / `GC_SPECIAL_EFFECT` / `GC_QUEST_INFO` 逐字节确认全对。详见 `CLIENT-PORT.md` §3。
`GC_CHAT` / `GC_AFFECT_ADD` / `GC_SPECIAL_EFFECT` / `GC_QUEST_INFO` 逐字节确认全对。详见 `CLIENT-40250-PORT.md`。
2. ~~换装完整~~ ✅ 已做（2026-08-30）：`Metin2Model` 加第二刚体挂点（盾，`Bip01 L Hand`，`_load_attach`
抽公共加载器）；`equip_model` 补 WEAR_SHIELD / WEAR_HEAD（头盔覆盖 hair 槽）/ 头发随 `parts[HAIR]`。
**armor→shape 真表**：proto 读器加 `alValues[6]`@191，`equip_model._armor_shape_default` = `item_proto
docs/FIRST-MAC-PLAYABLE-STATUS.md
-115
View File
@@ -1,115 +0,0 @@
# 首个 Mac 联网内测版：实施状态与已知问题（REL-01）
日期：2026-09-11。对应计划：`docs/FIRST-MAC-PLAYABLE-IMPLEMENTATION.md`。
后续审查：提交 `f39a55fd` 的观察器缓存保留、运行取消清理、外部内存门禁与异常 JSON 处理问题，见 [审查与修复记录](REVIEW-f39a55fd.md)。以下环境数据是原实施时的快照。
本文只记录已核对的事实。**当前没有可放行的候选包，也没有任何实网证据**；所有依赖服务器、测试账号、环境负责人确认或人工签核的条目均为 BLOCKED。离线/假进程测试 PASS 只证明门禁和状态机按契约工作，不能代替联网验收。
## 1. 结论
| 项 | 状态 | 说明 |
| --- | --- | --- |
| INF-01 契约与配置校验 | 离线 PASS | `playable_harness_test.gd` 负向用例、`validate_playable_report.mjs` 静态夹具全部通过 |
| INF-02 运行器与退出门禁 | 离线 PASS | `script/playable_gate_test.sh` 用假签名 arm64 包覆盖 PASS/退出码/信号/超时 TERM→10s→KILL/残留 FIFO/RID 与泄漏警告/凭据脱敏/聚合 |
| NET-01 真实联网闭环 | **BLOCKED** | 包内入口已实现；缺 `scenario.local.json`、测试账号、环境负责人确认的路线/怪物/掉落，未联网运行 |
| CBT-01 四职业技能矩阵 | **BLOCKED** | `test/playable/skill-cases.json` 全部 `unconfirmed`；脚本不补技能 ID |
| MAP-01 树怪资源与离线 Metal 截图 | 离线 PASS，**待人工签核** | 12 个候选树怪 × CPU/GPU × wait/run/attack/damage/dead 全部组装通过；截图需人工看过 |
| MAP-02 实际地图定位与落地 | **BLOCKED** | `forest-viewpoints.example.json` 机位均 `unconfirmed`；坡地脚/根接触需人工检查 |
| STB-01 2 小时稳定性 | 工具已实现，**未实跑**，BLOCKED | `script/playable_soak.sh` 可运行（见 §4）；真实断网与切图需环境确认 |
| REL-01 放行 | **BLOCKED** | 无重建候选包；上述必测项均未产生实网证据 |
## 2. 候选包与环境
- 计划中的候选包 `build/export-native-trees-20260911/mtgodot-poc.app` 和自编译引擎 `build/godot-particle-diagnostic/bin/godot.macos.template_release.arm64` 在当前工作树**不存在**。仅有 `build/export/mtgodot-poc.app`（2026-09-08），早于本轮全部 playable 代码，**不能**作为候选包。
- 本轮修改了 GDScript（包内测试入口、流程、指标、窗口适配），**必须重新导出 PCK**；若最终修复涉及 C++，还需 `./build.sh Release` 重建扩展、重新签名打包。重建后对最终包重新跑退出门禁。
- 官方 Release 模板的粒子退出警告未修复；必须显式使用经过验证的自编译 arm64 引擎。不宣称已修复官方模板或 Intel 平台。
- 数据盘剩余约 7.5 GiB（99% 已用）。2 小时 soak 的 `events.jsonl`、`rss.jsonl`、截图与日志会持续写盘，实跑前需由用户腾出空间；脚本不会自行清理任何文件或系统缓存。
## 3. 已知问题与限制
### 3.1 树怪动作（MAP-01）
- `ent_trent`（2301/2311）的 motlist 只有 WAIT、WAIT1、NORMAL_ATTACK、NORMAL_ATTACK1、FRONT_DAMAGE、FRONT_DEAD，**没有 RUN/WALK**。按旧客户端 `CRaceData::GetMotionKey` 未命中→`SetLoopMotion` 直接返回的规则，移动时继续播放当前循环（`reference_keep_current_motion`）。`forest_mob_render_test` 报告记为 4 条 fallback（2 个 race × CPU/GPU），标注“需实网确认：服务器移动该种族时位置变化且保持原循环”。未经实网确认前不能宣称行走表现与原版一致。
- 七种 ent 目录的 motlist 均只有 FRONT_DEAD，没有 BACK_DEAD。背后击杀时的死亡动作按旧客户端回退规则判定，需实网对照确认。死亡姿态、材质、轮廓已进入接触表截图，**必须人工签核**；AABB 底部不是脚部接触，离线测试不能证明坡地脚/根贴地。
- `mob_winding_test.gd` 仍固定覆盖 101/110/20001；树怪由 `forest_mob_render_test.gd` 单独覆盖。
### 3.2 帧时间（离线合成 suite，非实网）
`rendering_scenario_test.gd`（Metal，suite=`offline_synthetic`，FakeClient + 真实资源）本轮结果：
- 689 帧，>50ms 14 帧，全部已归因（unattributed=0）；>100ms：loading 6、gameplay 2。
- gameplay 的 2 帧（119.5ms、237.0ms）都带 `viewport_resize` 标记，发生在测试主动切换窗口尺寸时。它们不属于正常游玩的重复交互，但在实网 soak 中要继续按“同一交互 3 次中 2 次 >100ms 即阻断”规则判定。
- loading 段：同步模型构建 447–746ms，切图 1861ms 与 4489ms。首次加载预算尚未固定（计划要求基线采集后再定，不临时放宽）。
- CPU 蒙皮 8/16 角色时 p99 分别为 70.1ms/50.5ms（90 帧窗口，p99 即最大值）；GPU 蒙皮 1/8/16 角色 p99 ≤ 26.1ms。
- 视口 1280×720、1920×1080、2560×1440 均按请求尺寸生效（screen_scale=1）；Retina 缩放下的物理/逻辑换算由 `testing/playable_window.gd` 记录，未在 Retina 屏实测。
- 冷启动：进程冷启动/系统缓存状态未知，测试不清空系统缓存。
- 显存：`gpu_memory_kib=null`（unavailable）。Godot RenderingDevice 计数 843,616 KiB 不是系统显存，不据此判断显存泄漏。探针开销：每次采样 CPU 约 1.26µs；开/关探针 p50 差 −0.018ms，处于帧节奏噪声内。
### 3.3 稳定性工具的边界（STB-01）
- **切图**：`soak.warp.status` 默认 `unconfirmed`，STB-WARP-01 为 BLOCKED。只有环境负责人确认合法传送入口（`portal_cm`、`return_portal_cm`、`destination_map_key`、`cross_server`、偶数且 ≥20 的往返次数）后才会走传送门；不以直接改客户端节点位置代替。跨服切图须核实测试服支持。
- **真实断网**：`soak.faults.status` 默认 `unconfirmed`，STB-DISCONNECT-01 为 BLOCKED；主动 `reconnect()`（STB-RECONNECT-01）与真实传输故障分开计数，不能互相替代。确认后由 `run_client_gate.sh` 在 127.0.0.1 上启动 `script/playable_fault_proxy.mjs`，只代理本测试客户端的连接（`server.*` 与 serverlist 必须指向代理端口，`soak.faults.upstream` 为真实测试服）。不修改全局路由、防火墙，也不关闭任何服务。
- **已知限制**：如果服务器传送时下发了直连的 game 地址，之后的连接会**绕过代理**，故障注入对切图后的连接无效。需要在确认故障条件时一并核实，或在同一地图服务器内完成故障用例。
- **窗口**：headless、全屏、最大化窗口不可切换尺寸；请求尺寸（含标题栏）超出屏幕可用区域时如实记为 BLOCKED，不缩小目标冒充通过。
- **内存**：父运行器每秒采样子进程 RSS（KiB），在每轮静置 30s 后取低水位；必须 ≥ warm-up + 10 轮才判定。连续 5 轮增长，且后 5 轮中位数比前 5 轮高出 max(50MiB, 5%) 时 FAIL。低于阈值也不能证明长期无泄漏。
- 10 次正常退出由 10 个独立进程完成，每次都经过完整退出门禁；任何一次失败，后续运行（包括 2 小时 soak）不会启动，记为 BLOCKED。
### 3.4 人工项（不能自动化替代）
- 真实鼠标/键盘闭环（点击移动、选怪、普攻、技能栏、拾取）需要单独的人工证据。
- MAP-01/MAP-02 Metal 截图人工签核（`forest_map_render_test` 报告里 `manual_signoff.status` 恒为 `PENDING`，自动 PASS 不代表视觉签核）。
- CBT-01 技能特效截图需人工看过一次。
## 4. 已可运行的命令
以下命令在 `metin2-client/` 下执行。账号只通过 `MT_ACCOUNT`/`MT_PASSWORD` 环境变量或隐藏输入提供，禁止写进配置、参数或命令历史。
离线（不连服务器，本轮均 PASS）：
```bash
bash script/playable_gate_test.sh
node script/playable_soak_metrics_test.mjs
node script/playable_fault_proxy_test.mjs
node script/audit_playable_maps_test.mjs
(cd project && godot --headless --path . --script playable_harness_test.gd)
(cd project && godot --path . --script forest_mob_render_test.gd)
bash script/rendering_batch_test.sh
```
联网（需要重建候选包、`test/playable/scenario.local.json` 与测试账号；**本轮未运行**）：
```bash
bash script/playable_test.sh --app "$PWD/build/export-playable-rc1/mtgodot-poc.app" --config test/playable/scenario.local.json --suite full --allow-gameplay --repeat 3
bash script/playable_soak.sh --app "$PWD/build/export-playable-rc1/mtgodot-poc.app" --config test/playable/scenario.local.json --allow-gameplay --duration-seconds 7200
node script/validate_playable_report.mjs --release-dir <本批次输出目录>
```
`playable_soak.sh` 行为：
- 先用 soak suite 校验配置和资源。缺少 `--allow-gameplay` 时只做校验，返回 2，不启动客户端。
- 依次运行 `exit-1..exit-N`（suite playable，N ≥ 10）和 `soak-1`（suite soak，墙钟时长 = `soak.duration_seconds`，超时 ≥ 时长 + 900s）。
- 写出只列本批次运行的 `release-manifest.json`（required_runs `{playable:N, soak:1}`），再聚合。
- 退出码：0 PASS / 1 FAIL / 2 BLOCKED / 124 超时。
## 5. 放行检查表对照（计划 §11）
| 检查项 | 当前 |
| --- | --- |
| INF-01/02 负向用例通过，必测项缺失不能 PASS | ✅ 离线通过 |
| 同一候选包 3 轮联网闭环 + 鼠标键盘证据 | ❌ BLOCKED（无候选包、无账号/夹具、无人工证据） |
| 四职业基础战斗、技能及异常路径 | ❌ BLOCKED（技能矩阵未确认） |
| 首测地图和树怪资源/动作/Metal 画面 | ⚠️ 离线组装通过；机位未确认、人工签核未做、实网未跑 |
| 2 小时、切图、故障恢复、窗口、退出次数 | ❌ BLOCKED（工具就绪，未实跑；切图/断网条件未确认） |
| P0/P1 清零 | ❌ 未知：没有实网运行，无法判定 |
| 所有 BLOCKED 明确处理 | ⚠️ 本文已列出；首测必测项不得以“已知问题”绕过 |
| 包哈希、签名、引擎来源、设备信息一致 | ❌ 需重建候选包后由运行器生成 |
| 已知 P2、未覆盖地图/装备/技能及未验收平台列出 | ⚠️ 本文 §3；未覆盖：首测三图以外的地图、Intel、官方模板 |
## 6. 需要环境负责人提供
1. 自编译 arm64 引擎和重新导出的候选包（含本轮脚本），以及足够的磁盘空间。
2. `test/playable/scenario.local.json`：由 `scenario.example.json` 复制，填写 serverinfo 中的地址、角色槽位、map_key、安全路线、怪物/掉落 vnum；soak 需 `timeout_seconds ≥ duration_seconds + 900`。
3. 专用测试账号（等级、装备、已学技能、掉落条件由负责人准备），以及 `skill-cases.local.json` 中各职业的确认记录。
4. 如需 STB-WARP/STB-DISCONNECT：合法传送入口的确认；确认可在 127.0.0.1 代理后运行，并核实传送是否下发直连地址。
5. 树怪机位（平地/坡地/密林/传送点）的确认，以及 Metal 截图人工签核人。
docs/PARITY-GAP.md
+2 -2
View File
@@ -109,10 +109,10 @@ TreeSize/TreeVariance。当前实现已移除这些随机变换；若替代树
| # | 项 | 现状 | 目标 | 工作 | 规模 | BACKLOG |
|---|---|---|---|---|---|---|
| 2.1 | 武器 mesh | 🟡 **首版已做 + 2026-08-31 复核**：`Metin2Model.weapon_gr2` / `weapon_bone`（默认 `equip_right_hand`，warrior bone[10]）。加载武器 gr2 → `build_mesh`（rigid）→ 子 `MeshInstance3D`；每帧 `update_weapon_pose(world_pose[bone])`。**隔离探针实测**：`warrior_novice`/`warrior_cheongrin` × 8 个武器文件，weapon MI 全局原点 == `equip_right_hand` 骨骼全局原点，Δ = 0.00–0.06 m；world_demo 目视剑握在手里。之前记忆里「武器偏 ~10 m」是 cpu_skin `>=` / MapCoord 修复前的旧状态，已失效。新增 **grip pre-transform**（`weapon_pre = mul4x3(weaponInvWorld[0], weaponLocal[0])`，对齐客户端 `weaponComposite[0]` = `ModelInstanceUpdate.cpp:171`），`update_weapon_pose` 里 `mul4x3(weapon_pre, world_pose[hand])`；标准武器多校准 ~4–6 cm 握点。个别非标准文件（`02010`/`03010`/`03150`）骨骼带米级偏移 → 30 cm 夹断退回原始手部位姿（不回退）。`mul4x3` 提到 `gr2_bridge.h` 与 anim 共用 | 右手单持跟手 1:1；`03150` 类网格在文件里就离骨骼原点 ~3 m（资产缺陷，非变换问题）—— 需 per-weapon 偏移数据或修 .gr2。⬜ 左手/双持/盾、`_lod` 变体 | M | C5 / D2 |
| 2.1 | 武器 mesh | 🟢 **已做 + 2026-09-15 复核**：`Metin2Model.weapon_gr2` / `weapon_bone` 按职业挂到 `equip_right_hand` / `equip_right`，左右手规则覆盖剑、匕首、弓和扇；每帧 `update_weapon_pose(world_pose[bone])`。刚性网格采用 `weapon_pre = weaponInvWorld[0]·weaponLocal[0]` 后再乘手骨世界矩阵，对齐 `ModelInstanceUpdate.cpp:148` 的附属模型采样及 composite。已删除错误的 30 cm 夹断：`03150` 原始网格离原点约 3 m，逆绑定矩阵正好抵消该偏移，并非资产损坏。`weapon_attach_test.gd` 现用真实 `03150` 可见 AABB 检查 8 种族的待机/走/跑/攻击，避免只测节点原点的假阳性 | 后续仅剩武器拖尾、特殊武器独立目视验收 | M | C5 / D2 |
| 2.2 | GPU 蒙皮路径的发型 | ✅ **已做**：`_build_gpu_mesh()` —— `enable_gpu_skin` 带发型时，把发型 mesh 以 bind pose 并入 GPU mesh，每个 `ARRAY_BONES` 值经 `hair_bone_remap`（发型骨 idx → base 骨 idx）重映射。**无需改 shader / 第二骨索引区**（warrior 74/74 全匹配）—— `SRC_SKIN` + 共享 `bones_tex` 直接形变。`_apply_materials` 给追加的发型 surface 上「skinned + alpha-test + hair 贴图」材质。实测 5 base + 1 hair surface，红发（TargetSkin）贴头、镂空干净、跟动画 | M（完成）| A1 |
| 2.3 | 换装 / 时装 / 翅膀 | 无 | 多 `MeshInstance3D` 绑同一骨架 + 部位遮挡 / 隐藏规则 | `.msm` + 物品系统的上层 | L | D1 / D4 |
| 2.4 | 贴图换色 `SourceSkin→TargetSkin` | ✅ **首版已做**：`Metin2Model.hair_skin` —— 设了就用该 dds 当发型 albedo（代替 gr2 sibling 的 SourceSkin），对齐客户端 `SetMaterialImagePointer(part, SourceSkin, load(TargetSkin))`（`ActorInstanceData.cpp:152/225`）。`get_hair_options()` 现返回解析成绝对路径的 `source_skin` / `target_skin`。`formats.msm_hair` CTest 钉了 HairData 解析（同 gr2+SourceSkin、不同 TargetSkin）。demo 用红色变体 | ⬜ 非发型部位（护甲/时装）的 skin 表；`warrior_cheongrin` 头盔挡住发型，换色需换模型目视 | S（首版完成） | D3 |
| 2.4 | 贴图换色 `SourceSkin→TargetSkin` | ✅ **已做**：发型走 `Metin2Model.hair_skin`；盔甲/时装走材质 basename 映射 `set_skin_texture(SourceSkin, TargetSkin)`，由外层 `PlayerView` 明确转发到原生模型，对齐 `SetMaterialImagePointer(part, SourceSkin, load(TargetSkin))`。真实 12019 Blue Steel Armour 已断言加载 `warrior_4-1.GR2` 并将全部同名身体 surface 换为 `warrior_4-2.dds`，保留独立脸部材质 | 扩展装备集合的目视抽检 | S（完成） | D3 |
| 2.5 | 固定功能材质状态覆盖 | 单 stage `MODULATE(TEX,DIFFUSE)` 近似；**sphere-map 分支已按源码端口**（见 §2.7）。**blend / two-sided 改读 `gr2::MaterialInfo`**：`metin2_model::decide_blend()` 优先 `alpha_blend`（`dump_materials` 端口 `Material.cpp:233` = Name `Blend*` + MapCount>1），`decide_two_sided()` 读 `two_sided`（+ hair/cloak 名兜底），`m2_material` 加 `cull_disabled` shader 变体。仅 hair 镂空 / effect 加法这两类 GR2 没编码的仍按表面名 | 复现最终机位实际触发的 alpha-test ref、多贴图组合 | 逐分支盘点 `EterGrnLib/Material.cpp`；GR2 不承载任意 D3D stage 状态 | M | B2/B4 |
| 2.6 | 顶点色 | ✅ **排查完毕：不适用**。全资产 `.gr2`（PC / monster2 / effect）**零** `DiffuseColor`/`Color0` 顶点成员（grep 整个 assets 目录 = 0）。Metin2 的「逐顶点颜色」实际是：① 地形雾 —— `MapOutdoorRenderSTP` 运行时动态 VB 里 `dwDiffuse`/`dwSpecular` 存雾色/雾系数（非资产，已由 Godot `Environment` 雾覆盖）；② `.mse` 特效 `colorfactor` / 粒子 `TimeEventColor`（属 §1.2 `.mse` 端口）。libgr2 无需改，`build_mesh` 无需补 `ARRAY_COLOR` | — | B7 |
| 2.7 | 镜面 / 球面反射（护甲金属光） | 🟡 **管线已端口**：`SRC_MIX` / `SRC_SKIN` 加 `spec_map`/`spec_power`/`spec_enable`。按 `EterGrnLib/Material.cpp:305 __ApplySpecularRenderState` 复现：仅不透明面（客户端 alpha-blend 时回退纯 diffuse）、相机空间 `reflect(VERTEX,NORMAL).xy` 查 sphere map、`MODULATEALPHA_ADDCOLOR` = `EMISSION += sphere.rgb * tex.a * power`（`tex.a` = 护甲高光遮罩，`power` = `D3DRS_TEXTUREFACTOR.a`）。sphere map = 全局 `ETC/ymir work/special/spheremap.jpg`（客户端 index 0），`Metin2Model::_load_sphere_map()` 沿模型目录上溯解析。`Metin2Model.specular_power` 属性。**默认 0 = 完全休眠**，与之前逐字节一致 | 端口 `__ApplySpecularRenderState`（✅）；接装备层用 `item_proto bSpecular/100` 驱动（✅ 身体/护甲：`project/ui/equip_model.gd:283-288` `_apply_body()`；⬜ 武器 / 发型 / 时装等其余部位未接）；受控帧标定 power（⬜，§0 门禁） | M | B9 |
docs/REVIEW-f39a55fd.md
-38
View File
@@ -1,38 +0,0 @@
# f39a55fd 审查与修复
审查对象：`f39a55fdd5f14cb2d14d67929cf45f438f572a06`。修复基于该提交，位于本地分支 `fix/playable-f39a55fd`。
## 已确认的问题
| 优先级 | 问题与触发条件 | 影响 | 修复 |
| --- | --- | --- | --- |
| P1 | `PlayableProbe._connections` 用强引用保存 `EffectRegistry`；重连或切图重建注册器 | 旧注册器及其解析缓存一直保留，观察器自身污染长跑内存结果 | 弱引用订阅源；重新绑定和统计时移除失效订阅 |
| P1 | 终止联网/地图运行器或批量入口时，没有完整的子进程清理 | 客户端可能继续联网执行操作，代理、日志处理器、采样器可能残留 | 共用进程清理模块；保留信号退出码，仅对仍持有的子 PID 执行 TERM、有界等待、KILL 和 wait；批量入口转发终止 |
| P1 | 外部 RSS 检查尚未写回时，已有干净退出的中间 `report.json`；之后直接聚合 | 缺失 `STB-MEMORY-01` 的 soak 仍可被发布汇总判 PASS | 汇总 soak PASS 时必须同时存在唯一的内存 PASS 用例和 PASS verdict |
| P2 | 客户端报告、事件行或发布清单包含合法 JSON `null` 等错误类型 | 校验器抛出异常，无法生成应有的失败报告 | 校验 JSON 根类型、事件类型和单调时间字段；错误输入写出 FAIL 报告 |
## 复现证据与回归入口
- 注册器释放用例：模拟 30 次注册器替换。原实现出现 59 项断言失败；修复后 `playable_harness_test: failures=0`。
- 取消运行用例：原联网和地图运行器均在收到 TERM 后留下客户端；回归检查终止入口后客户端已被回收，入口退出码为 143，并覆盖普通批量与 soak 入口。
- 发布汇总用例：`node script/playable_release_test.mjs --baseline` 读取原提交的校验器，复现缺少内存检查仍然 PASS（该命令预期断言失败）。正常命令使用修复后的校验器。
- 异常 JSON 用例：检查返回失败码的同时，要求实际生成失败报告，避免只根据异常退出码误判测试通过。
可重复运行：
```bash
godot --headless --path project --script playable_harness_test.gd
bash script/playable_gate_test.sh
node script/playable_release_test.mjs
node script/playable_fault_proxy_test.mjs
node script/playable_soak_metrics_test.mjs
node script/audit_playable_maps_test.mjs
bash script/rendering_batch_test.sh
git diff --check
```
本轮修复后结果：门禁夹具 126 项检查通过；渲染批处理 53 项通过、`failures=0`；注册器/联网状态机、发布汇总、故障代理、内存指标、地图资源审计测试通过；Shell/Node 语法检查及 `git diff --check` 通过。
渲染批处理日志：`build/rendering/batch-20260911-211958-82865/`。
这些是离线、回环代理和假签名客户端测试。实网战斗、真实两小时长跑、最终新包与人工画面对照仍需独立验收；本次审查不会将其改成已通过。