The profiler

The profiler records what every frame did: the scopes each thread ran, the passes the GPU ran, and the device’s counts (draws, render passes, binds, GPU memory). You read it in three places: the editor’s Profiler tab, an overlay in a running game, and capture files you can open later or in Perfetto.

The profiler is in every build except Shipping. In a Shipping build none of this shows and nothing is recorded.

The Profiler tab

The Profiler tab sits beside the Console. Closing it stops any recording, and View > Profiler brings it back.

It records the editor process as a whole: every open page, every viewport preview and every Play-in-editor game share one frame. Its numbers are the editor’s, not one game’s. To measure a game on its own, profile its player (below).

• Record starts recording, and pressing it again stops. View > Profiler Record does the same. Recording keeps the last 3,600 frames, about a minute at 60 frames a second.
• Clear drops the recorded frames.
• Save writes the recording as a capture to the profiles folder in the editor’s user data folder (see Capture files).
• Open… shows a capture from that folder, such as one copied from a Steam Deck or a phone. Live goes back to the editor’s own recording.

Under the toolbar, the frame strip shows each recorded frame’s time: the CPU in blue, the GPU in amber, with faint lines at 16.7 ms (60 frames a second) and 33.3 ms (30). While recording, the views show the newest frame. Click a frame to show that one instead, or drag across the strip to show a range.

The timeline shows the selected frames on one time axis. Each thread has a lane, its scopes stacked by how deeply they nest, and the GPU has a lane for its passes. The lines mark where each frame starts.

• Scroll the wheel to zoom about the pointer, and drag to move along.
• Hold Shift and scroll to move through the lanes.
• Double-click to fit the selection again.
• Hover a bar to see its name and how long it took.

Beside it, the table lists every scope and GPU pass in the selection by name: its total time, its self time (its time without the scopes inside it) and how many times it ran. Click a heading to sort by that column, and click it again to reverse the order. Click a row to highlight that name’s bars in the timeline. Under the table, the counters show their averages over the selection, and memory shows its newest value.

If the pane is too small, the tab scrolls. Drag the split to give it more room.

The overlay in a game

A running game can show the profiler over itself: the frame times as a graph, the newest frame’s CPU and GPU time with the minimum, median and maximum, the scopes and GPU passes that took longest, and the counters. It sits in the top right corner and never takes the mouse from the game.

• Press F3 to show or hide it.
• Start a player with --profile-overlay to show it from the start.
• In a browser, add ?profile-overlay to the page’s address.

Play in editor runs the game inside the editor, so F3 works there too, but the overlay then shows the whole editor, like the Profiler tab.

A game can show it from a script, from its own debug menu for example. run.profilerAvailable() is false in Shipping builds, so use it to hide the menu entry there. Both calls work in every build; in Shipping they do nothing.

Luau

if run.profilerAvailable() then
  run.setProfilerOverlay(true)
end

AngelScript

if (run::profilerAvailable())
{
    run::setProfilerOverlay(true);
}

Capture files

A capture is a few seconds of frames saved to a file, so a game can be profiled where it runs and read somewhere else.

• In a running game, press F9 to capture the next five seconds.
• Start a player with --profile-capture <seconds> to capture from the start.
• In the editor, Save on the Profiler tab writes the recording.

Each capture is two files in the profiles folder of the user data folder (~/.local/share/gameengine/profiles on Linux, under %LOCALAPPDATA% on Windows and ~/Library/Application Support on macOS), named after the game (or Editor) and the time:

• .aeprofile opens in the editor’s Profiler tab with Open…. To read a capture from another machine, copy it into that folder.
• .json beside it is the same frames as a Chrome trace. Open it in Perfetto or chrome://tracing.

A game in a browser keeps its captures in the browser’s memory for now, so they cannot be saved out yet.

An agent connected to the editor can take a capture with the profiler_capture tool, which answers with the frame times and the scopes and passes that took longest. See What agents can do.