游戏兼容性测试方法论¶
目标：与 Z 闭源版（吉里吉里Z）的兼容性持平。 本页给 AI Agent 与测试者提供统一的测试/报告/修复流程，避免重复踩坑。
1. 测试闭环¶
-
收集：优先用常见商业作品（PSB 动画、Live2D、多语种、特殊插件）。 记录：游戏名、发行商、使用的引擎特性（KAG3? 吉里吉里? 特殊插件?）。
-
运行：真机（iOS）/ 开发机（macOS）。固定复现步骤。
-
记录：见第 3 节报告格式。
-
回归：修复后重跑同用例；保留一份"回归清单"避免改坏旧功能。
2. 兼容问题常见分类（定位路径）¶
| 类别 | 症状 | 排查入口 |
|---|---|---|
| TJS2 脚本语法/行为差异 | 脚本报错、行为不同 | cpp/core/tjs2/；先看 tjsGetMessageMap 错误信息 |
| 归档解包失败 | 资源读不出来 | cpp/core/base/（XP3/7z/zip/tar）；检查加密/文件名编码 |
| 图片解码差异 | 花屏/色偏 | cpp/core/visual/（TLG/PNG/JPEG/BPG/PSB）；检查 TLG5/6 变体 |
| PSB 动画/资源 | 动画错乱、缺帧 | cpp/plugins/psbfile/；比对 Z 的 PSB 解析行为 |
| 混合/滤镜效果差异 | 画面和 Z 不一样 | cpp/core/visual/tvpgl.cpp + simd/（注意 SIMD 审计记录中的已知缺陷） |
| 字体渲染 | 缺字、错位 | cpp/core/visual/（FreeType、TVPSysFont） |
| 音频/视频 | 无声音/卡顿 | cpp/core/sound/、movie/ffmpeg/ |
| 插件 API 缺失 | 脚本找不到函数 | cpp/plugins/；ncbind 注册列表 |
| 系统 API 差异 | 存档/路径/弹窗异常 | cpp/core/environ/apple/ios/platform.mm |
3. 报告格式（发给 AI Agent / 记录用）¶
游戏：<名称>（<发行商>，<年份>）
设备/系统：iPhone <型号> / iOS <版本>
复现步骤：1) ... 2) ...
现象：<截图/录像描述，或贴错误信息>
日志：<engineDrainStartupLogs 输出 / Xcode 控制台 / spdlog>
期望：<Z 闭源版或原版引擎的正确表现>
给 AI Agent 时，日志比截图更重要；两者都有最好。 涉及 SIMD 混合差异的，先临时关闭
TVPGL_SIMD_Init()确认是否由 SIMD 引起。
4. 与 Z 闭源版比对的注意事项¶
-
Z 闭源版本身是闭源二进制，无法直接读源码；用"同一游戏在 Z 上跑的行为"作为黑盒参考。
-
渲染结果不需要逐位一致（舍入差异可接受），但行为语义（alpha 处理、越界、默认值）必须一致。
-
存档/读档兼容性：存档格式与 Z 的兼容是长期目标，改动
base/存档相关代码前先确认。