fix(rendering): complete character visual regression fixes

2026-09-08 13:26:42 +08:00
parent c3a6fb973e
commit cea79fe17c
15 changed files with 380 additions and 35 deletions
@@ -242,9 +242,9 @@ godot --path project --script char_select_visual_test.gd
 | R1-01 | 主角晚到、重复事件、重连回归与修复 | R0 最小基线 | 晚到/重入/重试回归通过；真实重连待验 |
 | R1-02 | 地图坐标、高度、相机就绪检查 | R1-01 | A1/C1 晚到定位实景通过；坡地/边界待验 |
 | R2-01 | 同战士 GR2/GLB 实验台及对照报告 | R0 | 待执行 |
-| R2-02 | 发型/身体/附件修复及路线决定 | R2-01 | 待执行 |
+| R2-02 | 发型/身体/附件修复及路线决定 | R2-01 | CPU 绕序、GPU 动态取景和选角朝向已修复；8 个种族 GPU 待机基体矩阵已通过，装备/动作/最终包待验 |
 | R3-01 | 深度/材质/环境与地形校准 | R1、R2 几何稳定 | 材质已有改动，待验证 |
-| R4-01 | 选角、技能栏装配与数据恢复 | R1 | 待执行 |
+| R4-01 | 选角、技能栏装配与数据恢复 | R1 | 快捷栏重叠修复及服务器恢复回归通过；真实登录数据待验 |
 | R5-01 | 包资源清单、最终 `.app` 冒烟与画面报告 | R1–R4 | 待执行 |
 | R6-01 | 性能基线与静态资源缓存试验 | R5 | 后续 |

@@ -258,8 +258,31 @@ godot --path project --script char_select_visual_test.gd
 - 发现地图路径原来只在 setup 时按已收到的主角位置选择。新增首次有效主角位置到达后的地图重选，复用已有地图重载和相机/移动同步基点定位函数。
 - 修改 `ui/player_view.gd`：拒绝非法 race、缺失身体文件及解析失败的源文件。模型节点在入树时才实际加载，因此使用源文件预检，不能把入树前为空的 `get_info()` 当成加载失败。
 - 新增 `main_character_sync_test.gd`：测试失败重试、晚到/无信号实体、重入、重复事件、移动不回滚、过期构建等，已执行得到 `failures=0`。注入失败用例的 warning 属预期。
+
+### 2026-09-08 R2/R4 后续记录
+
+以下为历史定位过程，早期 C++ 实验加载了旧 debug 扩展，相关排除结论无效；以文末复核记录为准。
+
+- 确认用户选角用的 `HairIndex 0` 由 `warrior.msm` 精确映射到
+  `hair/hair_1_1.gr2` 与 `warrior_hair_01.dds`；新增解析回归，避免把默认路径或颜色猜测为实际配置。
+- 选角实景中，`warrior_5_1.GR2`（63 骨）与 `hair_1_1.gr2`（74 骨）组合仍无脸部可见。去除发型后脸部完整，故护甲/脸部几何未丢失；分别使用当前身体蒙皮、强制发型绑定姿势、源发型 alpha 和背面剔除渲染均无差异。没有提交这些无效的猜测性改动。下一步校验角色选择协议的 `hair_part` 语义与标准发型编号，而不是继续调整绕序、动画矩阵或透明参数。
+- 修复 `root/msm` 覆盖规格缺少 `PathName` 时的解析回退：原逻辑只查职业根目录，漏掉 `hair/` 子目录，导致 `HairIndex 1001..1012` 找不到模型并静默保留 `PlayerView` 默认的 `hair_1_1`。`race_spec_test.gd` 现覆盖真实 1001 解析和文件定位；选角视觉用例确认 1001 实际替换为 `hair_2_1.gr2`。发型前脸遮挡尚未随该修复消失，继续作为几何组合项跟踪。
+- 移除 `Hud` 中覆盖真实栏位的静态空快捷栏；`Quickbar` 现在有明确的底部锚点尺寸和更高绘制层级。`skill_test.gd` 验证服务端 `type=2` 技能槽恢复后图标可见，且 `race_spec_test.gd`、`skill_test.gd` 已通过。
 - `gamescene_test.gd` 与 `equip_model_test.gd` 已通过；前者故意使用缺失地图，其预期加载错误不能当成真实地图测试通过。
 - 新增 `gamescene_visual_test.gd`：Apple M4 / Metal Forward+ / Godot 4.7.1 上已执行 A1/C1；A1 加载 20 区块/601 物件，C1 加载 20 区块/565 物件，身体加发型共 4 个表面，实体定位断言通过。两者均使用 FakeClient，未连接实际服务器。
 - 截图人工观察：地图和真实人物出现；UI 仍有布局/风格问题，不能标为 R3/R4 完成。选角截图仍复现发型遮脸；单独翻转 winding 的试验未解决，未保留新的绕序修改。
 - 用例命令、输出位置和验证边界见 [test/rendering/README.md](../test/rendering/README.md)。早期失败截图保留在 `build/rendering/`；后续脚本变化应重新执行，不复用旧报告作为新代码证据。
 - 尚未完成：GLB 对照、发型根因修复、完整视觉基线与区域阈值、真实服务器重连、最终 macOS 包验收、R6 优化。下一优先项是发型的身体/附件变换与深度隔离。
+
+### 2026-09-08 R2 根因复核与修复
+
+- 构建复核：`build` 为 Release，编译更新 release dylib，但本地 Godot 加载仍停留在 9 月 7 日的 debug dylib。此前 inverse-bind、alpha 和剔除实验没有加载修改后的扩展，不能用它们排除根因。新增 `bash script/rendering_test.sh`，构建后同步本地加载库、重签名、输出哈希并运行绕序回归。
+- 冻结动画后改用双面材质显示完整后背，证实原选角相机在人物背后；身体背面被剔除，露出远侧正面内壁，后脑头发遂表现为“盖脸”。`cpu_skin()` 重建身体和发型索引时忽略 `flip_winding`，已对齐静态/GPU 网格的索引顺序；`PlayerView` 设置 PC 绕序，选角 pivot 从 -90° 改为 +90°。
+- 真实 Metal 选角复核：`main_part=20009`、`hair_part=0` 的脸、肩甲、护腕及裙甲完整，头发位于头顶；保留头发和原透明贴图。颜色/护甲与用户参考资源的进一步一致性仍待校准，不标为 40250 像素验收。
+- 更正 PathName 结论：MSM 中原有 PathName；`RaceSpec` 的空 SpecialPath 错误覆盖父级路径。已修复继承，并去除引号 token 的词法标记。前轮 hair 子目录回退仅缓解此问题。
+- `character_winding_test.gd` 对比绑定姿势及待机 0/0.5/1 秒的逐三角形反向索引，覆盖身体与发型，结果 `failures=0`。`race_spec_test`、`equip_model_test`、主角恢复回归通过；A1 GameScene 重新加载 20 区块/601 物件，主角定位及真实模型断言通过。
+- 选角输出现在按独立目录保存 `selection.png`、`report.json` 和发型纹理，报告包含实际 debug dylib、身体/头发/贴图哈希、引擎和取样时间。默认发型 CPU 截图：`build/rendering/selection-1788843070-9087/selection.png`；1001 GPU 用例：`build/rendering/selection-1788843071-9069/selection.png`。
+- 未覆盖：全职业、完整动作/换装矩阵、GLB 同资源对照、坡地足底误差、40250 同相机比较、真实联机和最终 macOS 包；R2 整体仍未关闭。
+- GPU 1001 取景根因修复：GPU 顶点着色器变形不会改变 `MeshInstance3D.get_aabb()`，选角此前仍以绑定姿势盒取景，故角色被推到窗口上方。`Metin2Model` 现首帧采样实际蒙皮包围盒用于剔除，并按需提供当前姿势包围盒；`CharSelectScreen` 收到 GPU 就绪通知后用该盒重新取景。`char_select_visual_test.gd` 在冻结 0.5 秒参考姿势后也走同一生产取景路径，并在报告中保留相机与网格包围盒数据。Apple M4 / Metal 的 HairIndex 1001 GPU 截图 [selection-1788844385-11872](../build/rendering/selection-1788844385-11872/selection.png) 人工审阅通过，脸部、发型、盔甲与完整人物均在画面内；对应 debug dylib SHA-256 为 `a268eef3f5cd1fc263652c4e0a9c3693f33f359b3706aa6850525c8e52108b39`。
+- GPU 路径仍保持环境变量启用的实验状态；1001 发型和带装备场景当前只覆盖男战士。完整职业的装备、动作、地图与性能测试仍按 R2/R6 的未完成项推进。
+- 追加 GPU 基体矩阵：使用 `--job=0..7 --main-part=0` 在同一 Apple M4 / Metal 环境生成八种种族的选择截图；全部装配断言通过，人工审阅的 [八种族联系图](../build/rendering/r2-matrix-gpu-contact-sheet.png) 中人物、脸部和默认发型均完整入框。此覆盖仅是无装备的待机选择画面，不替代每职业装备、动作或 40250 参考对比。