NEOLearn

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.

Updated October 20, 2026

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 featureWhat you get
traceThe engine's built-in spans. The backends below turn it on for you.
trace_tracyStreams spans to the Tracy profiler. Also turns on trace and debug.
trace_tracy_memoryThe same, plus every memory allocation. Slower.
trace_chromeWrites a .json trace file when the app exits. Also turns on trace and debug.
debugReadable 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.

  1. Install the Tracy profiler at the version that matches the tracy-client crate in your Cargo.lock (cargo tree --features neo/trace_tracy | grep tracy shows it).

  2. Start the Tracy UI and click Connect, so it waits for the game.

  3. Run the game in release with the feature:

    Shell
    cargo 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#

Shell
cargo run --release --features neo/trace_chrome

When 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:

Rust
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#

ToolWhat it shows
cargo build --timingsHow long each crate took, as an HTML report under target/cargo-timings/.
cargo llvm-linesWhich generic functions generate the most code.
cargo bloatWhich 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.

Next steps#