Runtime perf instrumentationKBVEPerf
A lightweight, runtime-toggleable performance layer for UE5. Scoped timers and counters feed per-name aggregates that drain to three sinks — the log, an on-screen overlay, and a live HTTP /perf JSON readout — so any KBVE plugin can be profiled by flipping a CVar.
Near-zero when disabled
It compiles out of Shipping builds via KBVEPERF_ENABLED=0. When compiled in but disabled at runtime it costs a single atomic load plus a branch per scope, and can be toggled live with the kbve.perf CVar.
- Timers — RAII scoped
KBVEPERF_SCOPE. - Counters — gauge samples via
KBVEPERF_COUNT.
What it gives you
Features
Scoped timers & counters
RAII scoped timers and counter gauges feed per-name aggregates, categorized by the name prefix before the first dot.
Three drain sinks
Aggregates drain to the log, an on-screen overlay, and a live HTTP /perf JSON readout of per-op timings.
Live HTTP readout
Enable with kbve.perf 1 and curl localhost:8099/perf for frame percentiles, hitch counts, and per-op count, last, max, avg and p95 (whole session and a recent window) plus counter gauges.
Lives on the engine
UKBVEPerfSubsystem is an engine subsystem, so the endpoint is up from editor start and survives play sessions; /reset clears the stats so one run can be measured on its own.
Compiles out of Shipping
KBVEPERF_ENABLED=0 removes it from Shipping builds; disabled at runtime it is one atomic load plus a branch per scope.
Instrument
Macros
#include "KBVEPerf.h"
void UMyThing::HotPath(){ KBVEPERF_SCOPE("Grass.AddChunk"); // RAII scoped timer KBVEPERF_COUNT("Grass.Instances", 72627); // counter / gauge sample}The name prefix before the first . is the category (Grass.AddChunk → Grass). Add KBVEPerf to your module’s PrivateDependencyModuleNames and the plugin to your .uplugin Plugins list.
Runtime toggles
CVars & HTTP readout
| CVar | Default | Purpose |
|---|---|---|
kbve.perf | 0 | Master switch — 1 turns collection + /perf on. |
kbve.perf.categories | "" | Comma-separated allow-list, e.g. "Grass,Terrain". Empty = all. |
kbve.perf.port | 8099 | Port for the HTTP /perf endpoint. |
kbve.perf.overlay | 0 | On-screen overlay of the worst ops this frame. |
kbve.perf.threshold | 3.0 | Log-sink threshold (ms). |
kbve.perf.window | 5.0 | Seconds of history the windowed figures are taken over. |
kbve.perf.hitch | 2.0 | A frame this many times the window median counts as a hitch. |
kbve.perf.exec | 1 | Allow /exec to run allow-listed console commands (editor builds only). |
kbve.perf 1curl http://localhost:8099/perfThe readout also carries frame-time percentiles, hitch counts and windowed per-op figures; trimmed here:
{ "frame": 12345, "fps": 58.2, "ops": [ { "name": "Grass.AddChunk", "count": 412, "lastMs": 3.1, "maxMs": 10.9, "avgMs": 3.4, "p95Ms": 7.2 }, { "name": "Terrain.GenerateMeshData", "count": 380, "lastMs": 0.6, "maxMs": 1.1, "avgMs": 0.7, "p95Ms": 0.9 } ], "counts": [ { "name": "Grass.ResidentChunks", "value": 25 }, { "name": "Grass.Instances", "value": 72627 } ]}Besides /perf, the server answers /reset (clear the stats), / (a live page served from the plugin’s Web/index.html) and, in editor builds, /exec?cmd= for console commands starting with kbve., r., stat , showflag., t.MaxFPS, fx. or sg..
First consumer
Integration
KBVEWorld is the first consumer: its chunk actor, grass render subsystem, road network and instance pool time their work with KBVEPERF_SCOPE, and publish KBVEPERF_COUNT gauges such as resident and registered grass chunks, HISM count, total instances, and live road chunks.
Questions
Frequently asked
What is the KBVEPerf plugin?
KBVEPerf is a lightweight, runtime-toggleable performance instrumentation layer for UE5. Scoped timers and counters feed per-name aggregates that drain to three sinks — the log, an on-screen overlay, and a live HTTP /perf JSON readout — so any KBVE plugin can be profiled by flipping a CVar.
What is the runtime cost of KBVEPerf?
It compiles out of Shipping builds via KBVEPERF_ENABLED=0. When compiled in but disabled at runtime it costs a single atomic load plus a branch per scope, and it can be toggled live with the kbve.perf CVar.
How do you read KBVEPerf results externally?
Set kbve.perf 1 to enable collection and the HTTP endpoint, then curl http://localhost:8099/perf for a JSON readout of per-op timings (count, last, max, avg, p95) and counter gauges, instead of relaying stat unit numbers by hand.
Discuss on the forum
Questions, fixes and notes on this page live in the KBVE forum.