Scenario Unreal Performance

Performance engineering in Unreal Engine 5.8

Expert level here means milliseconds per stage, not frames per second: classify the bound with one honest capture, explain the worst frame by the thread that works rather than the one that waits, fix in the order of measured size, and prove the result with repeated runs on the same route and build, hitches judged apart from the average. The performance engineer owns measurement, diagnosis and proof; most fixes go back to the teammate who owns the content. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-unreal-expert (channels, review loop, 5.8 traps).

Status (2026-09-24): scripts/ue_perf.py is not yet run in Unreal; its pure layers pass tests/code/unreal-performance/run_all.sh (50 offline tests on synthetic captures). Every UE name is [verify]; first run: job_probe_perf.py (procedures P0).

Stance (the expert delta)

• Milliseconds per stage, then the right tool. At 60 fps the game thread, render thread and GPU each get 16.6 ms, pipelined game N, render N-1, GPU N-2 (W4R [00:05:17] [00:08:26]). Report ms, never fps (ARI22 [00:14:44]). stat unit classifies, Insights says where on the CPU, a GPU capture explains the GPU, and a sampling profiler says why when instrumentation runs out (KEN [00:04:04]; NORSE [00:17:30]).
• An honest capture before any fix. Cooked Test or Development build on target hardware, fixed route; lock dynamic resolution (75%) and force async compute off only to attribute passes, never for the proof (NORSE [00:44:40] [00:45:12]). Lean capture for "are we on budget", rich (-statnamedevents, about 20% overhead) for "why" (NORSE [00:11:27]); -NoVerifyGC and -handleensurepercent=0 remove fake Development hitches (NORSE [00:13:35] [00:16:23]).
• The longest bar is often a wait, and waits are budget. Exclude idle, wait and frame-sync markers and follow the dependency to the working thread; a slow render frame N appears as game-thread waiting in frame N+1 (KEN [00:09:54] [00:16:30]). Waits on animation and movement finalization (about 2 ms at 300 NPCs) are reclaimable (W4R [00:16:20]).
• Epic scalability is the 30 fps mode. High (2) is the 60 fps level, and nothing selects the 60 fps device profile unless you build that (OZ26 [00:11:00] [00:16:50]; LVP). The resolution chain (dynres 800p to 1080p, TSR to 1440p, spatial upscale to 4K) is the biggest single rendering lever (OZ26 [00:14:41]; W4R [00:43:08]).
• Budget each feature, measure by delta, follow its tree. Lumen GI plus reflections is about 4 ms at 60 fps, read as the frame delta with Lumen off (OZ24 [00:37:55]). Nanite: budget, then Evaluate WPO and Pixel Programmable views, Overdraw last; a view locates, it does not prove (OZ24 [00:29:18] [00:32:13]). VSM: chase the larger of static and dynamic invalidations (OZ24 [00:48:59]). Async compute is an A/B per feature: about 1.5 ms overall in the Witcher demo, yet Lumen reflections back on graphics saved more (W4R [00:20:42] [00:21:48]).
• Defaults favor ease; the big wins are content settings. Complex collision everywhere, overlaps on load, translucency After DOF at full output resolution, DF shadows next to VSM, PDO or WPO foliage paying three times (VisBuffer, VSM, custom depth), overlapping shadowed local lights, props left Movable (NORSE [00:38:53] [00:49:03] [00:53:48] [00:49:35]; FFW [00:52:59]; ARG [00:11:54]).
• Hitches are their own pass. Hundreds of ms is almost certainly a blocking load, stopped at authoring by a validator; GC cost follows the UObject count; spawns are not incremental; camera cuts lose occlusion history; consoles have no runtime PSO hitches, PC and Mac are tested cold (HITCH [00:43:07] [00:45:16] [00:38:31] [00:25:08] [00:35:50]; W4R [00:44:44]; PSO blog). Dynamic resolution cannot fix a hitch (W4R [00:43:38]).
• Fix content before band-aids. Async physics init, incremental GC and dynres hide growth (HITCH [00:22:56] [00:41:56]); throttle the one feature that spikes instead of letting dynres soften the whole frame (W4R [00:38:55]).

Establish first

Workflow

import ue_perf as P (agent side). Commands go through scenario-unreal-expert's channels; packaged builds take only launch flags and a Level Sequence event track.

0. Probe the tools. job_probe_perf.py for API names and cvars; P.schema_probe(jsonl) on the first TraceQuery output. GATE: every planned cvar printed a value; TraceQuery keys mapped.
1. Frame the gap, write budgets. 38 fps is 26.3 ms, 9.6 ms over 16.67. P.budget_table(platform, fps, pass_budgets) (OZ26 [00:45:55]). GATE: sources on every row, passes sum under the stage.
2. Route and honest capture. P.route_from_bugit(log) (or P.route_event_track when packaged), P.capture_plan("budget", ...), three runs. GATE: three lean runs, spread known, identical hygiene.
3. Classify. P.diagnose_bound(frames, 16.67, context=...) gives bound, gap, caveats and the next capture; read back scalability (P.stat_sequence("scalability_readback")). GATE: bound named, gap in ms, caveats answered.
4. Config first, one change per measurement. Scalability 2 plus a selector that activates it; resolution chain (P.day_one_60fps_cvars, P.device_profile_block, P.write_ini_section, backups first); P.day_one_engine_ini() through P.apply_ini_keys (Use Simple as Complex, NeverUpdate overlaps while streaming); Lumen foliage threshold 0 and a roughness threshold below 0.4 read from Performance Overview (OZ26 [00:41:56]); r.GTSyncType 2 on Gen9; streaming under the 5 ms default. Log each in P.ChangeLog. GATE: read-back LastSetBy DeviceProfile; each change measured; quality trades A/B'd.
5. Deep pass on the bound (procedures P6 to P7b). GPU: attributed ProfileGPU into P.gpu_pass_table, P.lumen_delta, then the numbers through P.feature_budget_check (RT scene), P.nanite_triage and P.vsm_triage; async compute through P.ab_plan(P.ASYNC_AB_VARIANTS) and P.ab_verdict. Game thread: TraceQuery into P.analyze_trace (non-wait timers, counts against the screen, game_wait, advice), P.spawn_bursts, dumpticks grouped, obj list -countsort. Streaming: per-cell cost in World Partition Insights, request-to-visible latency on a top-speed traversal, P.STREAMING_AB_VARIANTS as A/B only. GATE: every over-budget bucket has a named cause, asset and owner.
6. Audit and route fixes. P.perf_audit_level(), P.perf_audit_assets() (mobility, collision source, WPO bounds, Displacement Fade), P.change_requests(rows) to owners; apply only after agreement. Parity from the same BugItGo views (P.parity_pair). GATE: every needs_eyes pair judged by eye.
7. Hitch pass. capture_plan("hitch") cold then warm (cold only off-console); P.hitch_snapshots(dir), each through P.analyze_trace; P.camera_cut_spikes on the route's cuts; unclassified frames go to a sampling profiler. GATE: zero snapshots on the cold route, no blocking load in gameplay, GC events under 2 ms, UObjects under 500k.
8. Prove and guard. Same route, build, device; three runs each; async compute as chosen; DRS locked and as shipped. P.compare_runs then P.write_proof_report. Guard with a nightly automated performance test trended in Horde (OZ26 [00:47:43]). GATE: verdict stable_at_target, "not tested" filled in.