性能分析¶
性能工作从可复现场景与用户可见 metric 开始。不能凭直觉、一次 debug build 或不同 commit/config 的 profile 优化。
选择证据¶
- 可重复、隔离算法比较使用 Catch2 microbenchmark；
- 端到端场景使用稳定 wall/turn/frame measurement；
- Tracy scope/frame/text/plot 使用
src/profiling.h的CATA_PROFILE_*wrapper； - CPU、allocation、I/O、GPU 或 Android 专属问题使用平台 profiler；
- diagnostic timing 只解释 live failure，不能替代 benchmark。
Tracy build¶
安装 Tracy client library 后，仓库契约为：
关闭 TRACY 时 wrapper 编译为空操作。游戏代码不能直接调用 Tracy macro，这样才能保持
disabled build 与 profiler 选择。
可复现比较¶
记录 commit、compiler、optimization/LTO、sanitizer、frontend、SDL、hardware、power mode、 world/save/Mod、RNG seed、scenario、warmup、sample count、statistic 与 raw result。相同条件 比较 before/after，接受加速前检查 correctness test。
热路径规则¶
缓存前先说明 owner 与 invalidation boundary。检查 complexity、allocation、string/ translation、registry lookup、map/inventory scan、renderer stall 与跨语言调用。不能用 determinism、save compatibility 或有界 Lua handle 换速度。
生成 artifact¶
profiler capture、compiler time trace、flame graph、compile_commands.json、Doxygen、ctags、
clangd index 与大型 symbol database 都是 generated。需要时作为有范围 CI/review artifact
上传，不提交。
验收¶
报告 baseline/new 数值与 uncertainty、correctness check、测试平台，以及任何 memory/ startup/build-size 回归。结果不确定时如实报告，不能声称已优化。