Files
AVA2/docs/GAME-RENDER-INVESTIGATION.md
T
shenandshen 281418f351 Fix cross-platform rendering and optimize frame performance
Correct selection orientation, game-entry lifecycle, mounted NPCs, labels and skill panels. Add the native GPU scene path, resident geometry, bounded texture and Python caches, and collision broad phase.

Pin the independently maintained Metin2 SDK through a submodule and document reproducible setup. Include rendering regressions and macOS packaging improvements.

Validation: client Debug build and 12 targeted client tests passed; SDK build and all 14 SDK tests passed.
2026-10-11 17:55:53 -07:00

124 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 进入游戏后只剩深色背景和残缺面板
调查日期:2026-10-10。对应用户 22:59:30 跨平台截图和 22:58:05 Windows 截图。
## 已复现的初始化阻塞
在当前 `dist/AVA2.app/Contents/MacOS` 工作目录运行发布包的同一个可执行文件,使用原版游戏阶段和模拟角色数据,游戏界面创建过程中报错:
```text
InventoryWindow.LoadWindow.LoadObject
RuntimeError: Failed to load image (filename: rework_inv/new_equipment_bg.tga)
```
调用链为 `networkModule.SetGamePhase` → `game.GameWindow.__init__` → `interfaceModule.Interface.MakeInterface` → `__MakeWindows` → `uiInventory.InventoryWindow.__LoadWindow` → `InventoryWindowEx.py` → 图片加载。
此纹理确实存在:
- AVA2 原资源:`../AVA2/1. Client DEV/pack_maker/patch_design_wa/rework_inv/new_equipment_bg.tga`。
- `patch_design_wa_create.xml` 中的虚拟路径是 `rework_inv/new_equipment_bg.tga`。
- 跨平台项目根目录的 `rework_inv/new_equipment_bg.tga` 也存在,大小 79522 字节。
- 发布包的 Resources、MacOS 相对目录和 `asset_manifest.json` 均没有 `rework_inv`。
`tools/pack_assets.py` 按固定目录列表打包,遗漏 `rework_inv`。`tools/package_macos.sh` 的相对资源链接同样是固定列表。打包清单的完整性校验只确认“列出的文件是否完整”,没有确认“原版游戏所需文件是否全部列出”。
`GameWindow(self)` 必须构造成功,才会传入 `SetPhaseWindow` 并成为当前游戏窗口。背包加载失败会调用原版 `exception.Abort`(记录异常、调用 `app.Abort`、`sys.exit`),使这一过程提前中止。此前创建的部分 UI 可以留下残缺面板。主循环根据实际 Python 窗口判断是否进入 game;地形和角色的主绘制分支依赖这个阶段,故界面构造失败也可能阻止世界显示。用户截图的精确实时阶段没有从进程中读取,不能仅凭图片确定其最后停留在哪个回调。
## 资源目录对照运行
同一个发布包可执行文件,参数为 `--phase game --preview-data --frames 20`,改在完整 `build/dev/test-rundir` 资源目录下启动后,原版游戏 UI 能完成创建,并输出包含地形、角色、背包和底部任务栏的截图。这排除了“完全没有游戏世界渲染实现”的解释,也验证了资源可见性是当前发布包的明确阻塞因素。
该实验是本地预览,未连接服务器;模拟位置、装备、镜头和场景与用户 Windows 截图不同,不能视为真实账号端到端通过。
## 其他已发现的问题和验证边界
- 发布包没有 `map/` 目录。`CPythonBackground::LoadMap` 查找相对的 `map/<name>`、`Maps/<name>`、`<name>` 和开发测试路径,没有完整的发布资源目录支持。补齐 UI 后仍需用真实地图坐标验证加载。
- 完整资源运行仍报告部分树木纹理找不到,例如 `CompositeMapN2.dds`、`TreeWillowOakLeaves01SU.dds`、`CompositeMap.dds`。这些日志证明还存在场景纹理解析问题,尚未确定各文件的最终解析规则。
- 上一份选角调查确认的图片池状态泄漏也会影响游戏 UI 的图片复用;其修复尚未应用。
- `ava2.python_view` 的 game 测试使用 `runtime/login_view.py` 的简化 `SetGamePhase`,只是设置字符串状态,不会构造原版 `game.GameWindow`;因此不能发现本次背包资源异常。
修复方向:按原版 pack manifest 的虚拟路径构建完整运行资源根目录,并让脚本、图片、地图和纹理使用同一根目录;增加发布包原版 GameWindow 创建与加载→游戏阶段回归验证;随后处理图片池重置和世界纹理差异。
本次只调查并保留证据,没有修改生产代码或重新打包。日志和完整资源对照截图保存在忽略目录 `build/verification/game-investigation/`:`packaged.log`、`full-assets.log`、`full-assets.png`。
## 2026-10-10 后续修复与真实账号验证
已实施以上调查中的资源打包和图片池修复,并用用户指定账号连接现有服务器测试,未改动服务器或 AVA2 参考目录。凭据仅通过测试进程环境提供。
真实加载流程还确认并修复了以下问题:
- `chr.Destroy()` 删除选角实例时清空了网络主角色 VID,导致镜头无法找到服务器上的角色;销毁后恢复网络流保存的主角色标识。
- 131×131 的高度原始数据包含边界样本,地形块此前没有放到地图区块的位置。区块原点现在按 `block * 25600 - cellScale` 设置;地图物件的负 Y 转换到游戏的正地图 Y,同时把原生 Z 轴旋转转换为引擎 Y 轴旋转。
- 新增角色包中的高度可能为 0,而地形高度约 17771;第一帧镜头避障把角色误当成地下物件,距离从 1550 收缩到 194。绘制和镜头检查前先按地形放置实际主角色。
- SDL 的二维几何接口没有深度缓冲,之前却按近到远绘制不透明场景,远处地形覆盖角色。改为远到近,并保持地形混合层次。
- 盔甲 DDS 的透明度通道包含高光信息。上传纹理时把低透明度像素的 RGB 清零、随后强制透明混合,造成角色身体消失或变黑。现在保留 RGB,并按材质是否透明决定混合模式。
- 地表使用原始 tile.raw 的纹理分布和邻域混合,替代每个区块只选择一种主要纹理;小地图恢复采样实际 minimap.dds 地形,并在其上绘制原有角色标记。
- 桌面使用原版任务栏,触控 HUD 仅在 Android 启用;实际服务器游戏不再运行预览角色的模拟移动/战斗更新。
- 完整包由 pack 虚拟路径与 Windows 客户端散装界面图片共同生成。脚本根目录纳入清单,包内链接保持在包内,避免掩盖缺失文件的开发目录链接。
开发运行目录中的真实登录、选角、loading、game 流程已通过,主角色坐标 `(43303, 17771, 70856)`,镜头距离保持 1550。9 项相关回归测试通过;Android 核心编译通过。
精确 Windows 高光/光照、SDL 几何接口在复杂相交场景中的完整深度处理、相邻地形块流式加载,以及少数原始引用缺失的特效/植被纹理仍有差异。生成的验证截图和日志位于 `build/verification/game-fixed/`。
最终独立 macOS 包已用同一账号完成真实 loading → game;原版 GameWindow 的包内资源构造测试通过。包内外部符号链接为 0,真实登录退出后的严格签名验证通过。运行配置改为包外用户数据目录,最终截图为 `build/verification/game-fixed/packaged-game.png`。
## 2026-10-11 技能、操作和头顶显示修复
- 技能面板空白来自 `playerLoad.RegisterSkill` 空实现。按 AVA2 自己的 `PythonPlayerSettingsModule.h` 恢复职业/分支、第九技能、坐骑、辅助、语言和公会槽位,并在主角色加载时提前注册,保留加载阶段已收到的技能等级。
- 属性派生值更新按 AVA2 原版触发条件重新计算,避免全量初始点数覆盖客户端计算结果。此项有回归覆盖;本次真实账号主要验证技能页,不代表所有属性数值已逐项与 Windows 核对。
- 名字为黑色像素字:原生启动流程漏掉 `introLoading.__main__()` 的颜色/称号初始化,并使用 SDL 调试字体。恢复原版初始化,头顶文字改用界面的 FreeType 字体和真实文字宽度,保持 Retina 渲染比例。
- 等级落在脚下:网络角色的 TextTail 默认高度仅 10,且停留在包中的 Z=0。登记时加入角色高度,每帧跟随实际渲染角色,并保持名字居中、等级和称号在左侧。
- GM 标识的黄色线条和偏移来自矩形顶点、半尺寸/缩放、循环粒子上限、重力额外乘 9.8、发射向量强制归一化,以及附着粒子没有跟随角色。按 AVA2 `EffectLib` 行为修正;最终真实截图显示标识在头顶。
- 键盘移动接口原为无操作,鼠标状态没有驱动真实角色。接通原版 Python 输入到服务器拥有的角色,支持相对镜头的方向键/WASD、地面点击/按住移动、右键镜头和镜头按键,发送移动和停止包。界面消费的滚轮优先留给界面,原生 F9 不再意外切换调试渲染器。
- 游戏更新不再固定 33 毫秒;按实际帧间隔更新(上限 250 毫秒),失去窗口焦点释放按键。地图加载回调可能在帧内替换地形,使用前重新获取指针,避免访问已销毁地图。
验证:`ava2.player_panel`、`ava2.game_scene`、`ava2.game_entry` 3/3 通过,覆盖技能等级保留、派生属性、方向/对向/斜向输入、镜头按键释放、原版颜色初始化、粒子几何/上浮/附着。指定账号真实登录到 game,技能图标和等级有效;按键移动测试距离 1020,松开后位移 0。最终独立包再次登录并截图成功,证据在 `build/verification/input-label-fixed/`。没有保存账号密码或修改 AVA2/服务器。复杂场景帧率、完整战斗交互和精确 Windows 光照一致性没有在本次验证中完成。
## 2026-10-11 二次登录黑屏与倒退行走回归
- 根因一:`net.SetPhaseWindow` 的两处 C++ 强引用延迟了旧 `LoadingWindow` 的销毁。安装新加载窗口时,旧窗口析构中的 `SetPhaseWindow(LOAD,0)` 清除了新窗口,主角色的 `LoadData` 无法触发。现在先释放两处旧引用,再安装新窗口;测试用带析构回调的旧窗口和真实主角色包确认新回调仍然有效。
- 同类问题还出现在 `player.SetGameWindow`:旧 GameWindow 析构调用 `SetGameWindow(0)`,可能覆盖新回调;数字 0 原来还被当作 Python 回调对象持有。现在归一化 0/None,并在新回调安装前完成旧对象销毁。连续 GameWindow 重建与快捷栏刷新通过。
- 倒退行走:模型与骨骼世界矩阵额外加了 180 度,而位移方向未加。移除额外旋转;从真实战士 GR2 脚部/脚趾骨骼计算正面方向,验证绘制方向与运动方向一致。
- 移动包时间:原生游戏时钟没有承接由 LoginSession 处理的初始服务器握手,可能发送本机 uptime。现在每个连接在加载交接时同步握手时间及已过间隔;原生收到没有对应握手的 HANDSHAKE_OK 时保留已同步时间。此处是已确认的时钟缺陷;没有读取服务器日志,因此不把用户报告的每一次退出都归因于服务器时间检查。
- 原版 Python 可能 `exit(0)` 提前结束测试,game_entry 现在也要求最终完成标记,避免将未完成的构造流程误判为成功。
验证:5/5 相关 CTests 通过。指定账号在同一个客户端进程完成 game → login → selection → loading → game;第二次技能页、场景和角色正常显示,按键移动后继续运行 100 次游戏更新,连接仍有效,测试进程正常退出。没有改动原 AVA2 或服务器。日志与截图:`build/verification/relogin-facing-fixed/`。发布包与压缩包更新;这些实测覆盖一次连续重登和有限时长在线,不等同于长时间稳定性验证。
## 2026-10-11: selection facing, NPC outfits, and measured frame cost
The selection regression came from removing the universal 180-degree model rotation to correct locomotion. The original Windows `chr.SetRotation` adds 180 degrees at the script API boundary; restoring that conversion fixes selection without changing network locomotion. Script position getters now also invert the reflected showcase Y coordinate consistently. The live selection screenshot shows the warrior's face again, and the GR2 toe-direction regression still confirms that gameplay mesh forward agrees with movement.
The eight teacher NPCs (61000–61007) share `old_master_M` as their base entry in `npclist.txt`. Windows replaces this through `locale/common/npc_wear.txt`, including races 0–7 and outfits 34100/34101. The bundled Python pack mount previously searched only `Resources/root`; the configuration exists in sibling `Resources/locale/common`. Pack reads now search the script mount first, then the bundle asset mount identified by its manifest, preserving case-insensitive lookup and traversal rejection. The NPC query also uses the background's current warp map, matching the Windows query instead of an unassigned string. Live logs confirm eight distinct requested race/model combinations, and `scene-final.png` shows the configured outfits.
`app.SetCamera` previously updated the Python-side camera without updating the host orbit camera, while `app.GetCamera` returned stale values after input. A consumed setting request now updates the host camera and host feedback updates the Python values. The live scene probe verifies a requested 180-degree view and an active connection.
The delivered binary had been built as Debug (`-g`, no optimization). A macOS `sample` also found per-frame rebuilding of static map-object geometry. Static object draw commands are now cached for their lifetime and released with the map; this trades some retained geometry memory for reduced construction work. Packaging now explicitly configures RelWithDebInfo (`-O2`) in `build/release`, retaining symbols for crash diagnosis.
Measured on this machine, the authorized test account at approximately (441,716), 2048x1536 output, same 1550-distance/15-degree/180-degree NPC camera:
| Build | Representative stable total frame cost | Approximate rate |
| --- | --- | --- |
| Debug, corrected NPC assets and static cache | 239–241 ms | 4.2 FPS |
| RelWithDebInfo, corrected NPC assets and static cache | 25.0–25.2 ms | 40 FPS |
The optimized default camera measured 21–22 ms (45–47 FPS). These are short live samples, not a guaranteed rate across maps; initial asset loading and screenshot capture frames are excluded. Windows screenshot parity still has gaps in mounted NPCs, foliage, sky/environment, and depth handling; SDL geometry currently uses painter ordering rather than a hardware depth buffer. The old screenshot's camera, location, and aspect ratio also differ from the reference, so it cannot establish pixel parity by itself.
Evidence: `build/verification/npc-performance/{baseline.sample,debug-comparison.log,scene-final.log,select-final.png,scene-final.png,targeted-final-tests.log}`. Regression checks cover bundle pack mounting and NPC map precedence, presentation versus movement orientation, camera setter/feedback, select rendering, and entering the game twice.
Final targeted verification: eight relevant tests passed (pack mount, player panel/camera, select render, game scene, game entry, GR2 render, chr API, background). The broader `ava2.python` suite still fails a pre-existing missing-icon fixture assumption against the populated asset root; isolating that fixture reveals an older formula-status expectation (100.5 versus 90.5 after derived-status recalculation). Those unrelated fixture/status expectations were not changed for this rendering patch. The final facing implementation restores the Windows script boundary conversion rather than introducing an actor-wide rendering offset.
### 2026-10-11 Hardware depth, frame pacing and mounted NPCs
- Added a native SDL_GPU scene pass with persistent vertex/index buffers, depth testing/writes, alpha testing, D3D-style culling and perspective-correct texture interpolation. Metal is verified on this host; the Vulkan SPIR-V shaders compile but Vulkan runtime is not verified. CPU model transforms, lighting and fog remain CPU work.
- Upload decoded textures on the scene GPU queue before sampling. Borrowing SDL_Renderer textures produced a blank first frame because their queued uploads were not submitted until Present. Composite the scene with premultiplied alpha so the original selection background survives.
- Cache tinted text masks (512 entries / 16 MiB) instead of creating/destroying textures for every label. Cull static objects by conservative world bounds before copying mesh commands. Keep collision geometry intact. Disable GPU validation in normal release builds; AVA2_GPU_DEBUG enables it for diagnostics.
- Move the 60 Hz deadline wait immediately before presentation and use SDL_DelayPrecise. The frame CSV distinguishes active CPU work, geometry assembly, raster encoding and presentation intervals; loading and screenshots are excluded from steady-state statistics.
- Port the reference sky's vertical cube gradients, environment cloud scale/height/alpha and lens-flare enable conditions. This removes the invented cloud/flare appearance in C1.
- Render mount actors and attach riders through the animated saddle bone. Convert native Z-up bone matrices before world attachment. Register the reference horse wait/walk/run/dead motions for all eight PC races, and resolve the active motion mode at playback time: riders no longer stand on mounts, and an armor rebuild preserves the riding pose. A real GR2 leg-pose regression checks riding, armor rebuild and dismount restoration.
- Validation: 10 targeted Debug CTests pass, including native Metal depth/alpha/culling/perspective/first-texture/background pixels, font renderer lifetime, conservative frustum rejection, sky configuration and mounted animation. Live selection, NPC/mount scene, movement/orbit and same-process re-login were exercised with the authorized account. No credentials are stored in source or documentation.
- Remaining Windows parity gaps: SpeedTree still generates approximate foliage rather than decoding the original SPT geometry; outdoor rendering still lacks full adjacent-tile streaming; original specular/sphere-map shading is not complete. Performance evidence covers the measured local Metal scene, not every map or long-running session. Existing unrelated broad-Python-suite fixture/formula failures remain unchanged.
- Final signed-bundle measurement: 2,400 game updates (~40 s), 2,359 steady-state samples after the first 40 updates; average 60.000 FPS, presentation interval P95 16.723 ms / P99 16.765 ms, active CPU work P95 10.424 ms / P99 11.313 ms. Two intervals exceeded 20 ms (maximum 23.478 ms); this is not a claim of zero dropped frames. Full camera orbit, short W movement and connection checks at updates 1,190 and 2,390 passed. Evidence: `build/verification/gpu-depth/final-stress.csv`, `final-stress-summary.json`, `final-stress.png`, `riding-tests.log`. Signed app: `dist/AVA2.app`; release archive updated from that bundle.
- Final packaged re-login probe also passed after the riding fix: second GameWindow and skill page rendered, movement completed, and the connection remained live for the following 100 updates (`build/verification/gpu-depth/final-relogin.log`).