Manual

Manual

The Profiler

The Profiler shows where each frame's time goes: in your game's systems, in physics, in the engine, in the editor, and waiting for the display. This page covers recording frames, reading the graph, picking a frame, and the numbers and table that break it down. Open it with Window ▸ Profiler; the first time, it opens as a tab beside the Logs.

Record frames

The Profiler records each frame while it is open and Record, at the left of its bar, is on, whether the game plays or you edit the scene. It keeps the last 300 frames. Record is on to begin with. Closing the panel stops the recording, but a Profiler tab behind another tab still records.

Along the bar:

ControlWhat it does
RecordRecords each frame, red while it does; click to stop
ClearForgets the frames recorded
The arrowsPick the frame before or after the one picked
FollowPicks the newest frame as each one comes, lit while it does

After them, the bar names the frame picked, Frame and its number, and at its right end how long its work took, the whole frame and the frames a second it makes, and what the render thread took to draw it.

Only the editor times anything: a built game records nothing and runs none of this.

The kinds of time

Each frame's time is split into five kinds, stacked in this order:

KindWhat it is
ScriptsYour game's C#: each of its systems by the name it was added with, the commands they recorded applied after them, and the rest of its code each frame and fixed step, its async code among it
PhysicsThe systems of the physics packages: the 2D or 3D physics step and what goes with it
EngineBevy's schedules, the game's C# within them left out, each schedule a line: the fixed steps, Update, PostUpdate and the rest; a schedule of your game's Rust is named so
EditorThe editor's own work: its interface drawn, and the rest
WaitingBetween the frame's schedules and the next frame: the display, the render thread and the platform's events

The render thread draws a frame while the main thread runs the next, so its time is shown apart from the five: what it took to draw each frame, its wait for the display's next image left out.

The graph

The graph has a bar for each frame, the newest at the right, stacked by kind in each kind's color. Dashed lines at 16.7 ms and 33.3 ms mark 60 and 30 frames a second, and the graph is cut off at 40 ms. The render thread is an orange line across the bars. A mark over a bar is a frame in which C# collected garbage.

Click the graph to pick a frame, or drag across it to look along the frames. Picking a frame stops following the newest; the frame stays picked as older ones drop off. Follow, or Clear, follows the newest again.

The picked frame

Down the left of the panel is what each kind took of the picked frame, in milliseconds. Untick a kind to leave it off the graph, so the rest stand out; Render thread has its own tick, for its line. Under the kinds, This frame gives:

LineWhat it is
C# allocatedWhat the game's systems allocated in the frame, in yellow when it is more than nothing
CollectionsC#'s garbage collections in the frame, young, middle and old
Managed heapHow much C#'s heap holds
ProcessThe editor's memory
EntitiesEvery entity in the world, the engine's own included
DrawnHow many entities the renderer drew

The table under the graph breaks the frame down. Each kind is a row, with what it was spent on under it, the most first; click a row with an arrow to open or close it. Scripts is open to begin with, a row for each of your systems.

ColumnWhat it shows
NameThe kind, the system or the schedule
TotalIts time in the frame
SelfA kind's time that none of its lines account for
CallsHow many times a system ran, fixed steps counted
C# allocatedWhat a system allocated, in yellow when it is more than nothing

The table's last row, Render thread, breaks its drawing into Assets and views, Window (waits for the display), Queue, sort and prepare, Draw, submit and present, and Cleanup. Its total counts the wait for the display, which the line on the graph leaves out.

Find what is slow

  • A system that takes a lot of time is near the top of Scripts in the table. Find it by the name you gave it when you added it (see Writing a system).
  • A spike with a garbage mark over it is a collection. Look for the systems with C# allocated in yellow, and allocate less in them.
  • Frames with most of their time in Waiting are waiting for the display or the render thread, not for your code.
  • The editor's own time is shown apart, under Editor, so what you measure in Scripts, Physics and Engine is your game's.

See Performance for writing fast systems.

In the Scripting API

  • Schedule: systems added by name, the names the Profiler shows.