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

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:

   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.