ue5-performance-packaging

快速开始

• 确认目标平台和构建配置。
• 收集当前性能症状和打包目标。
• 输出打包前检查清单和测量计划。

API 参考点（UE5.6-UE5.8）

• 运行时质量和帧预算参考点：
  • UGameUserSettings::SetOverallScalabilityLevel(...)
  • UGameUserSettings::SetFrameRateLimit(...)
  • UGameUserSettings::ApplySettings(...)
• 打包设置参考点：
  • UProjectPackagingSettings
  • BuildConfiguration、MapsToCook、DirectoriesToAlwaysCook
  • UsePakFile、bUseIoStore、bGenerateChunks
• 资产依赖验证参考点：
  • FAssetRegistryModule、IAssetRegistry
  • GetAssetsByPath(...)
  • GetDependencies(...)、GetReferencers(...)
• 性能分析插桩参考点：
  • TRACE_CPUPROFILER_EVENT_SCOPE(...)
  • DECLARE_CYCLE_STAT(...)
• 实用运行时统计命令：
  • stat unit、stat gpu、stat scenerendering、memreport -full

性能和打包要求

• 每项性能/打包任务都必须定义：
  • 目标平台 + 构建配置 + 测试地图
  • 可复现的采集场景（摄像机路径、时长、网络模式）
  • 基线指标和验收阈值
  • 打包配置集和依赖扫描范围
  • 包含明确阻塞项的通过/不通过结果
• 如果缺少任何一项，准备情况评估就不完整。

工作流

1）采集可复现的基线

• 固定测试地图、摄像机路径、可扩展性设置和网络模式。
• 在相同场景下重复采集 stat unit 和 stat gpu。
• 使用中位数或百分位数指标，而非单帧峰值。

2）隔离热点

• 找出采集时间段内开销最高的游戏玩法/渲染系统。
• 将高开销 Actor/资产与场景上下文关联起来。
• 如果无法确定归因，为自定义系统添加范围明确的 CPU 标记。

3）验证资产和依赖

• 扫描目标路径，查找缺失或损坏的资产引用。
• 查询问题资产的依赖项和引用者。
• 验证所需的地图/游戏模式资产已纳入打包范围。

4）验证打包配置

• 检查 UProjectPackagingSettings 字段是否符合目标发布策略。
• 验证待烘焙地图、始终烘焙目录和构建配置。
• 根据分发要求验证 Pak/IoStore/分块策略。

5）打包就绪试运行

• 执行打包前检查清单和类似试运行的验证。
• 隔离首个阻塞性打包错误及其依赖链。
• 记录尚未解决的阻塞项、负责人和风险。

6）通过/不通过决策

• 只有在指标和打包检查达到阈值时才予以批准。
• 报告剩余风险和建议的缓解措施。
• 锁定用于签署验收证据的场景和设置。

限制

• 没有可测量的前后数据时，不得声称取得了优化成效。
• 保持性能分析场景可复现（地图、摄像机路径、网络模式）。
• 区分编辑器开销与打包后的运行时表现。
• 更改质量可扩展性设置时，必须报告。
• 保持打包检查具有确定性；签署验收期间避免临时切换配置。
• 始终报告指标单位（ms、fps、内存）和采集时长。

故障处理

• 症状：多次运行的性能数据波动较大。
  • 定位：场景设置不确定，以及后台环境存在波动。
  • 修复：锁定场景，先进行预热运行，并比较中位数和百分位数。
• 症状：优化效果无法复现。
  • 定位：质量设置、地图或运行时模式不一致。
  • 修复：公布准确的采集配置，并在相同条件下重新运行优化前后测试。
• 症状：打包构建失败，并出现大量连锁错误。
  • 定位：最早出现的阻塞错误及其直接依赖链。
  • 修复：先解决最早的阻塞问题；重新运行以找出后续阻塞问题。
• 症状：打包后的构建启动时缺少资源。
  • 定位：Cook 列表覆盖范围及依赖图中的缺漏。
  • 修复：加入缺失的地图/目录，并修复无效引用。
• 症状：打包后的构建性能不如 PIE 基准。
  • 定位：仅打包配置存在的差异，以及运行时内容路径。
  • 修复：将打包配置与基准进行比较，并统一可伸缩性和设备设置。
• 症状：在内容密集型场景附近，内存使用量出现回退。
  • 定位：占用内存较高的资源，以及流送策略的行为。
  • 修复：降低常驻资源压力，并调整流送/Cook 策略。

打包运维

• 发布构建优先使用显式地图/Cook 列表，而非隐式发现。
• 打包前使用 AssetRegistry 查询验证依赖项。
• 为每个目标配置文件维护一份唯一的发布打包设置来源。
• 在 UE5.8 中，将 Zenserver Cook 输出视为迭代存储；可分发构建仍需验证 Pak/IoStore 暂存。
• 将 UE5.8 增量 Cook 视为 Beta 迭代路径，并保留干净/完整 Cook 发布检查。
• 更改任何打包设置后，重新运行就绪检查。

UE5.6-UE5.8 兼容性说明

• 上述 UGameUserSettings、UProjectPackagingSettings 和 AssetRegistry API 在 UE5.6-UE5.8 中稳定。
• 在 UE5.6-UE5.8 中，ProjectPackagingSettings.h 均位于 Developer/DeveloperToolSettings 下。
• 对于受支持的迭代工作流，UE5.8 默认启用 Zenserver 作为 Cook 输出存储；这不能取代发布容器验证。

升级处理

• 当性能瓶颈需要引擎级性能分析或渲染器改动时，进行升级处理。
• 当打包问题源自第三方插件构建失败时，进行升级处理。