Profiling
Find where frame time goes - the engine's tracing spans with Tracy or the Chrome trace format, your own spans, GPU tools, NEO's render audit, and compile-time profiling.
On this page
The engine wraps every system, and much of its own work, in tracing spans. With a tracing backend turned on, you can see each frame as a timeline: which systems ran, on which thread, for how long. Tracing isn't in NEO's default builds, because collecting spans has a cost; turn it on for a profiling run, and always profile a release build.
Turning it on#
| Cargo feature | What you get |
|---|---|
trace | The engine's built-in spans. The backends below turn it on for you. |
trace_tracy | Streams spans to the Tracy profiler. Also turns on trace and debug. |
trace_tracy_memory | The same, plus every memory allocation. Slower. |
trace_chrome | Writes a .json trace file when the app exits. Also turns on trace and debug. |
debug | Readable names for systems and components in traces and errors. |
Spans need the log level to allow info: don't filter them out with LogPlugin::filter. wgpu spans are filtered out by default; set RUST_LOG=info to include them.
Tracy#
Tracy shows a live timeline with statistics per span.
Install the Tracy profiler at the version that matches the
tracy-clientcrate in yourCargo.lock(cargo tree --features neo/trace_tracy | grep tracyshows it).Start the Tracy UI and click Connect, so it waits for the game.
Run the game in release with the feature:
Shellcargo run --release --features neo/trace_tracy
The statistics view gives each system's mean time per call (MTPC), which is the number to compare between changes. Tracy's command-line capture tool (tracy-capture -o run.tracy) records with less overhead than the live UI; open the file in the UI afterwards.
GPU work also appears in Tracy, in a RenderQueue row. GPU timings vary a lot from frame to frame because of clock changes, so compare medians, not single frames.
Chrome trace format#
cargo run --release --features neo/trace_chromeWhen the app exits, it writes a .json trace file. Open it in a trace viewer such as Perfetto, or chrome://tracing in a Chromium browser.
Your own spans#
Add spans around your own work; the macros are in neo::prelude:
fn generate_level(/* ... */) {
let _span = info_span!("generate_level").entered();
// everything until _span is dropped is timed
}CPU sampling#
To find a hot function inside a system, a sampling profiler shows the call tree without any spans: cargo flamegraph on Linux and macOS, Instruments on macOS, or your platform's profiler. Build with debug symbols in release ([profile.release] debug = true) so the names show.
GPU profiling#
If the CPU timeline shows the frame waiting on the GPU, profile the GPU with your GPU vendor's tool: Xcode's Metal debugger on macOS, Nsight Graphics for NVIDIA, Radeon GPU Profiler for AMD, or Intel's Graphics Frame Analyzer. RenderDoc is for debugging frames, not for timing them.
RenderDiagnosticsPlugin reports per-pass CPU and GPU times as diagnostics, without an external tool.
NEO's render audit#
Games built on the gameplay kit can report what they ask of the GPU. Run one with NEO_RENDER_AUDIT=<file>, and when it exits it writes a JSON report with:
- render passes and draw calls per frame, counted exactly;
- pipelines, and how many were created after the first frames (shader compiles mid-game);
- each camera's effects (HDR, MSAA, bloom, SSAO, TAA, the atmosphere, tonemapping);
- lights and shadow maps, materials and meshes, and every texture's size and format.
NEO_RENDER_AUDIT_FRAMES=<n> stops the game after n frames, for a repeatable measurement.
Compile time#
| Tool | What it shows |
|---|---|
cargo build --timings | How long each crate took, as an HTML report under target/cargo-timings/. |
cargo llvm-lines | Which generic functions generate the most code. |
cargo bloat | Which functions take the most space in the binary. |
Run cargo clean before timing a build, and time it more than once. See Setting up for settings that make day-to-day builds faster.