Profiling

Profiling Skill

Unreal 5.8's native toolsets have no performance or tracing tools, so this is VibeUE's net-new capability: unreal.PerformanceService answers "are we CPU- or GPU-bound?" and drives Unreal Insights captures from Python with no C++ required. Run everything here through execute_python_code.

The whole API is small — read the live signatures once with discover_python_class(class_name="unreal.PerformanceService"):

All methods return a JSON string. For a representative reading, profile under PIE or a standalone session (start_standalone), not the bare editor viewport.

🚦 STEP 0 — Is it CPU-bound or GPU-bound? (DO THIS FIRST, ALWAYS)

Never optimise before you know which processor is the bottleneck. The frame time is roughly max(GameThread, RenderThread, GPU) — these run in parallel, so only the longest one sets your FPS. Cutting GPU cost (shadows, Lumen, post-process) does nothing if the frame is actually game-thread or render-thread bound, and vice-versa. Getting this wrong wastes the whole session.

Fastest check — one call

pythonCopy code
import unreal, json
result = json.loads(unreal.PerformanceService.frame_timing())
print(result)  # game_thread_ms, render_thread_ms, gpu_ms, rhi_thread_ms, frame_ms, bound, hint

Start PIE first (see the pie-testing skill) and park in a representative/worst spot, then call it. It returns game_thread_ms, render_thread_ms, gpu_ms, rhi_thread_ms, the frame_ms, a bound verdict (GameThread / RenderThread / GPU), and a hint with what to do next. This is the same data the stat unit overlay shows, read straight from engine globals — no screenshots, no trace parsing.

⏱️ Frame-time budgets — what a target FPS actually costs

FPS is just 1000 / frame_ms. Because the threads run in parallel, every thread (GameThread, RenderThread, GPU) must individually finish inside the budget below — the slowest one alone sets your FPS. A 12 ms GPU is wasted if the game thread takes 25 ms: you still get ~40 FPS.

Read frame_timing() against this table: if game_thread_ms = 25, you are hard-capped at ~40 FPS no matter what you do to the GPU. To hit 60 FPS the game thread must drop under 16.66 ms; to hit 120 FPS, under 8.33 ms. Always state the bottleneck thread's ms next to the target budget so the gap is explicit (e.g. "game thread 25 ms vs 16.66 ms for 60 FPS → must cut 8.3 ms on the game thread").

You don't have to do this arithmetic yourself: frame_timing(target_fps=...) returns the gate — the budget block carries each thread's headroom / over_budget against the per-frame budget and a single budget.meets_target PASS/FAIL you can assert on (CI-style perf checks included). To prove the verdict logic works against a known ground truth, use force_hitch (see the API table).

🛠️ CVars tune the renderer — they do NOT fix the game thread

r.* console variables almost exclusively move GPU and RenderThread cost (Lumen, shadows, reflections, resolution, draw setup). There is no CVar that makes your Tick, AI, or animation logic cheaper. When bound == GameThread, the fix lives in code and Blueprints, driven by what the profiler shows:

So the workflow for a game-thread bottleneck is: profile → read the offending scope → edit the code/Blueprint that owns it → rebuild → re-profile to confirm. Reaching for CVars here is a category error; they will not move the number.

Decision tree

Confirm / fallback methods

1. Numeric thread split via log — reliable, works headless:

   pythonCopy code
   import unreal
   w = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_game_world()
   unreal.SystemLibrary.execute_console_command(w, "stat dumpframe -ms=0.5 -root=gamethread")
   unreal.SystemLibrary.execute_console_command(w, "stat dumpframe -ms=0.5 -root=renderthread")
   

   Then read the dump with the engine LogsToolset (tail the main log, ~150 lines) — it prints the full thread hierarchy in ms (e.g. World Tick Time, FTickFunctionTask, individual Blueprint ReceiveTick costs). This is the single most useful CPU drill-down.
2. Resolution-scaling test (decisive GPU-bound proof) — sample frame time at full res via frame_timing(), then r.ScreenPercentage 50, and compare. FPS jumps a lot → GPU-bound. FPS barely moves → CPU-bound.
3. stat unit is the canonical overlay, but its numbers do not go to the log, and PIE often runs in a separate window so screenshots are unreliable. Prefer frame_timing() or methods 1–2 over trying to OCR stat unit.

⚠️ Gotchas — read before writing any code

0. ProfileGPU tells you WHERE GPU time goes, not WHETHER you are GPU-bound. It always produces a GPU breakdown even on a CPU-bound frame — so reading it first will happily send you optimising shadows on a frame whose real cost is the game thread. Run STEP 0 (frame_timing()) first; only reach for ProfileGPU once bound == GPU.

0b. Never run ProfileGPU (or stat dumpframe) during a trace you intend to average. Each ProfileGPU stalls the GPU for a full readback (hundreds of ms to seconds), and those stall frames poison the frame-time stats. Capture clean frame-time traces separately from GPU/CPU drill-downs.

0c. analyse() reports frame-time aggregates (avg/p95/worst frames, hitches, notable log lines), not the live CPU/GPU split. Use frame_timing() for the per-thread split.

1. Profile under PIE or standalone, not the bare editor viewport. The empty editor viewport is not representative. Start PIE (pie-testing skill) or use start_standalone().

2. Trace files are large — a ~10 second trace with default channels is 30–50 MB. Traces land under Saved/Profiling/ (already excluded from source control).

3. A trace must be active before you bookmark / mark regions. bookmark() and region_start()/region_end() only do something while get_trace_status() reports a live trace. Call start_trace() first.

Trace Control

Start / stop a trace

pythonCopy code
import unreal, json

# Default channel set (frame, cpu, gpu, log, ...) — pass channels="" or omit
res = json.loads(unreal.PerformanceService.start_trace("combat_encounter"))
print(res)  # includes the trace file path

# ... reproduce the workload ...

stopped = json.loads(unreal.PerformanceService.stop_trace())
print(stopped)  # trace file path + size

Custom channels

pythonCopy code
# Comma-separated channel list (short names accepted by the service)
unreal.PerformanceService.start_trace("mem_capture", "frame,cpu,memalloc,memtag,object,loadtime")

Check status

pythonCopy code
import unreal, json
print(json.loads(unreal.PerformanceService.get_trace_status()))  # active? which channels?

Annotations — Mark Regions and Bookmarks

Use these while a trace is active to label interesting moments in the Unreal Insights timeline.

pythonCopy code
import unreal

# Single point-in-time bookmark (vertical line in Insights)
unreal.PerformanceService.bookmark("spawn_wave_3")

# Named region (coloured span)
unreal.PerformanceService.region_start("loading_level")
# ... trigger the thing you want to measure ...
unreal.PerformanceService.region_end("loading_level")

Reading a capture back — analyse()

analyse() reads a finished trace and/or the log and returns a perf summary (frame stats, worst frames, hitches, notable log lines) without opening Unreal Insights:

pythonCopy code
import unreal, json

summary = json.loads(unreal.PerformanceService.analyse("both"))   # "trace", "logs", or "both"
print(summary)  # avg/p95/worst frame ms, hitches, notable log lines

# Analyse a specific file instead of the last trace started/stopped
unreal.PerformanceService.analyse("trace", "Saved/Profiling/combat_encounter.utrace")

For source="both", inspect status: complete means both sources succeeded, partial means exactly one did, and failed means neither did. A partial result deliberately has success=false and names available_sources / failed_sources; this prevents a missing trace from masquerading as a successful capture. Log output separates pso_hitch_event_lines, cumulative pso_hitches_reported, and pso_hitch_summary_lines; repeated cumulative summary lines are not summed. The backward-compatible pso_hitches field is the best supported count.

Remember: analyse() is frame-time aggregates only — use frame_timing() for the CPU/GPU split.

Standalone capture — representative readings

The editor viewport (and even PIE) is not always representative of a packaged run. start_standalone() launches the game as a separate standalone process with one unique, direct-to-file trace. It does not use the global Unreal Trace Server store and never substitutes an unrelated "latest" trace:

pythonCopy code
import unreal, json

start = json.loads(unreal.PerformanceService.start_standalone("standalone_capture"))
# start is request_accepted=true, success=false, pending=true until the child and trace exist
status = json.loads(unreal.PerformanceService.get_standalone_status())
# poll on later editor ticks until status["capture_verified"] is true

# ... let it run / drive the workload ...

stopped = json.loads(unreal.PerformanceService.stop_standalone())
# require stopped["success"] and status == "finalized" before trusting the trace

Record the returned session_id, pid, map, trace_file, and log_file with benchmark results. If shutdown is forced or the exact trace stays missing/empty, stop returns failure and may mark the available log/partial trace as partial; do not silently use another store trace. analyse("both") can still return a clearly marked log-only partial summary.

For comparisons, keep map/route, resolution, scalability, difficulty, power mode, and warm-up fixed; disable editor background throttling for unattended runs and restore its prior value afterward. Treat short or sparse samples as observations, not stable averages. Compare median/p95/p99 and frame counts above 33/50/100 ms, and separate cold-start/shader/PSO runs from warm-cache runs. Run ProfileGPU or stat dumpframe separately because their instrumentation stalls contaminate traces.

Recommended flow

pythonCopy code
import unreal, json

# 1. CPU vs GPU verdict FIRST (PIE running, parked in a representative spot)
print(json.loads(unreal.PerformanceService.frame_timing()))

# 2. Capture a clean trace around the workload
unreal.PerformanceService.start_trace("combat_encounter")
unreal.PerformanceService.region_start("wave_spawn")
# (trigger the gameplay here)
unreal.PerformanceService.region_end("wave_spawn")
res = json.loads(unreal.PerformanceService.stop_trace())
print("trace:", res)

# 3. Summarise without leaving Python
print(json.loads(unreal.PerformanceService.analyse("both")))

Channel Reference

start_trace / start_standalone accept a comma-separated channels string; empty uses the default set (frame, cpu, gpu, log, …). Common channels:

Channel naming may vary slightly by build; call get_trace_status() after start_trace() to see the channels actually enabled.

Common channel presets

Opening Traces in Unreal Insights

analyse() covers most needs from Python, but you can open a .utrace for the full timeline UI:

Copy code
Editor menu: Tools → Run Unreal Insights

Or from the command line:

Copy code
"<UE install>/Engine/Binaries/Win64/UnrealInsights.exe" "<path>/combat_encounter.utrace"

Trace files are written under:

Copy code
<project root>/Saved/Profiling/<name>.utrace