ue5-performance-packaging ยท diff
git:20260302.11fee6c to git:20260303.768e90e
87 added, 8 removed. Audit A to A.
---
name: ue5-performance-packaging
description: UE5.6/UE5.7 performance and packaging readiness workflow. Use when requests involve PIE performance checks, runtime stat review, pre-package validation, build configuration sanity, and release readiness checklists.
---
# Quick Start
- Confirm target platform and build configuration.
- Collect current performance symptoms and packaging goal.
- Output a pre-package checklist plus measurement plan.
+ # UE5.7 API Anchors
+ - Runtime quality and frame-budget anchors:
+ - `UGameUserSettings::SetOverallScalabilityLevel(...)`
+ - `UGameUserSettings::SetFrameRateLimit(...)`
+ - `UGameUserSettings::ApplySettings(...)`
+ - Packaging settings anchors:
+ - `UProjectPackagingSettings`
+ - `BuildConfiguration`, `MapsToCook`, `DirectoriesToAlwaysCook`
+ - `UsePakFile`, `bUseIoStore`, `bGenerateChunks`
+ - Asset dependency validation anchors:
+ - `FAssetRegistryModule`, `IAssetRegistry`
+ - `GetAssetsByPath(...)`
+ - `GetDependencies(...)`, `GetReferencers(...)`
+ - Profiling instrumentation anchors:
+ - `TRACE_CPUPROFILER_EVENT_SCOPE(...)`
+ - `DECLARE_CYCLE_STAT(...)`
+ - Practical runtime stat commands:
+ - `stat unit`, `stat gpu`, `stat scenerendering`, `memreport -full`
+
+ # Performance and Packaging Contract
+ - Every performance/packaging task must define:
+ - target platform + build config + test map
+ - reproducible capture scenario (camera path, duration, net mode)
+ - baseline metrics and acceptance thresholds
+ - packaging configuration set and dependency scan scope
+ - go/no-go output with explicit blockers
+ - If any item is missing, readiness evaluation is incomplete.
+
# Workflow
- - Run runtime performance checks (frame time, game/render/GPU timing).
- - Identify heavyweight actors/assets and suspect systems.
- - Validate asset references and required map/game mode settings.
- - Verify build configuration and packaging options.
- - Produce go/no-go checklist with unresolved blockers.
+ ## 1) Reproducible Baseline Capture
+ - Freeze test map, camera path, scalability, and net mode.
+ - Capture `stat unit` and `stat gpu` under same scenario repeatedly.
+ - Use median or percentile metrics, not single-frame spikes.
+ ## 2) Hotspot Isolation
+ - Identify top-cost gameplay/render systems in the capture window.
+ - Correlate high-cost actors/assets with scene context.
+ - Add scoped CPU markers for custom systems when attribution is unclear.
+
+ ## 3) Asset and Dependency Validation
+ - Scan target paths for missing or broken asset references.
+ - Query dependencies and referencers for problematic assets.
+ - Validate required map/game mode assets are included in package scope.
+
+ ## 4) Packaging Configuration Validation
+ - Check `UProjectPackagingSettings` fields for target release policy.
+ - Validate maps-to-cook, always-cook directories, and build configuration.
+ - Validate Pak/IoStore/chunk strategy against distribution requirements.
+
+ ## 5) Package Readiness Trial
+ - Run pre-package checklist and dry-run style verification.
+ - Isolate first blocking packaging error and dependency chain.
+ - Record unresolved blockers with owner and risk.
+
+ ## 6) Go/No-Go Decision
+ - Approve only when metrics and packaging checks meet thresholds.
+ - Report remaining risks and recommended mitigation actions.
+ - Lock scenario and settings used for sign-off evidence.
+
# Constraints
- Do not claim optimization wins without measurable before/after data.
- Keep profiling scenario reproducible (map, camera path, net mode).
- Distinguish editor overhead from packaged runtime behavior.
- Avoid changing quality scalability settings without reporting it.
+ - Keep packaging checks deterministic; avoid ad-hoc config toggles during sign-off.
+ - Always report metric units (ms, fps, memory) and capture duration.
# Failure Handling
- - If metrics are noisy, run repeated captures and use median.
- - If package fails, isolate first blocking error and dependency chain.
- - If asset references break, list exact missing packages and owning assets.
+ - Symptom: performance data is noisy across runs.
+ - Locate: non-deterministic scenario setup and background variance.
+ - Fix: lock scenario, warm up run, and compare median/percentile values.
+ - Symptom: optimization claims do not reproduce.
+ - Locate: mismatched quality settings, map, or runtime mode.
+ - Fix: publish exact capture config and rerun before/after under same conditions.
+ - Symptom: package build fails with long error cascade.
+ - Locate: first blocking error and its direct dependency chain.
+ - Fix: resolve earliest blocker first; rerun to reveal next blockers.
+ - Symptom: packaged build launches with missing assets.
+ - Locate: cook list coverage and dependency graph gaps.
+ - Fix: include missing maps/directories and resolve broken references.
+ - Symptom: packaged build perf is worse than PIE baseline.
+ - Locate: packaged-only config differences and runtime content path.
+ - Fix: compare packaged config to baseline and align scalability/device settings.
+ - Symptom: memory usage regresses near content-heavy scenes.
+ - Locate: high-memory assets and streaming policy behavior.
+ - Fix: reduce resident asset pressure and adjust streaming/cook strategy.
+
+ # Packaging Ops
+ - Prefer explicit map/cook lists over implicit discovery for release builds.
+ - Use AssetRegistry queries to validate dependencies before packaging.
+ - Keep one source of truth for release packaging settings per target profile.
+ - Re-run readiness checks after any packaging setting change.
+
+ # UE5.6 / UE5.7 Compatibility Notes
+ - `UGameUserSettings`, `UProjectPackagingSettings`, and AssetRegistry APIs above are stable in UE5.6/UE5.7.
+ - `ProjectPackagingSettings.h` lives under `Developer/DeveloperToolSettings` in both versions.
# Escalation
- Escalate when performance bottleneck requires engine-level profiling or renderer changes.
- Escalate when packaging issues stem from third-party plugin build failures.