Understand your game's performance

Preview Runs on your computer About 15 minutes

Before you publish, you want to know three things: Is my game smooth? Where is it slow? Does it use too much memory? The performance page answers all three, on your own computer, without uploading anything. This guide walks through every part of that page, what each number means, and what to do about it.

You do not need to know how it works inside. If you can read a chart, you can use it.

Your game is never touched. The page measures your game while you test it. It adds nothing to the build you publish, and nothing is sent to Vapour.

Open it

From your game's folder, run one command:

vapour test

A browser window opens with your game in one tab and this page in the other. Play your game for a minute, then switch to the page. Close the browser when you are done and everything is cleaned up.

Two things to know before you start:

• The command is in preview. See what is available today.
• Measuring a running game needs Linux. On other systems vapour test still shows the FPS counter on the game itself. Profile your game locally covers the options.

You can also open a saved recording (a .vpt file) to look at a past session. Everything below applies to both. To try it without a game, download the demo recording, which is made-up data for practice, and open it with the Open dump button.

The page at a glance

The left menu jumps to each section: Overview, Assets, Flamegraph, Optimization and Capture log. At the bottom of the menu it reminds you: On your machine. No telemetry uploads. No cloud dashboard dependency.

The sections, top to bottom:

1. The session bar and the four tiles

A saved practice recording (made-up data).

The session bar

Below the bar, one line of text tells you what just happened, for example Dump validated … No probes started, or what a live measurement covers.

The four tiles

A tile shows — when that measurement does not exist for this kind of session. Nothing is invented to fill the gap.

The same tiles for a live measurement

A real live measurement of the Godot TPS demo, captured in a browser without a graphics card, so the numbers are high.

A live measurement has different tiles:

2. The timeline

The same practice recording.

Three charts share one time axis, so you can read straight down from a spike to what the memory and the processor were doing.

Hover over a chart to read exact values. Window start and Window end are sliders that zoom all three charts to the part you care about, and Full capture puts them back. The flamegraph and the report always use the whole recording, even when you have zoomed.

For a live measurement the first chart is empty (no frames are counted) and the other two show processor and memory:

3. Asset load cost

Made-up data for ten files, one of which failed to load (shown in red).

This section ranks your textures, models, sounds and other files by how hard they were to load.

• The coloured bars show when each file loaded and for how long. Overlapping loads are stacked. Colours are by kind: textures green, models orange, sounds purple, shaders teal, code red, data yellow. Hover a bar for its name, time and size.
• The step line is the running total size. A big step is a big file arriving.
• The table lists every file, hardest first. Click a column heading to sort. Click a row (or a bar) to zoom the timeline onto that load and see what the game was doing then.
• Hardness combines how long a file took, how big it is, and its memory and processor cost into one number from 0 to 4. Use it to decide what to shrink first. It only compares files within this recording.
• A file that failed to load has its name in red.

The columns that end in ≈ (memory and processor) are rough estimates. The page says so itself.

Today this section stays empty during a live vapour test. Nothing records file loads from a running game yet, so it fills only from a recording that already contains them, like the practice recording here. See Find expensive assets.

4. Flamegraph

Made-up data.

The flamegraph shows where your code spends its time, as stacked boxes. The bottom box is the whole program; each box above it is something it calls.

• A box's width is how often that function was caught running, not how long it ran. Wide boxes are where the time goes.
• Click a box to zoom into it. Reset zoom zooms back out.
• The table underneath ranks every function by how often it was caught (Self samples) and its Share of the total. Here pathfind has 22.9%, so it is the first thing to look at.
• A recording with no function information shows a message instead of boxes. The page never makes up callers it did not see.

Type a name in the search box and matching boxes light up, so you can find a function at a glance:

A live vapour test does not fill the flamegraph yet. It records processor and memory only. Open a recording that has function information to use it.

5. Spike windows and memory observations

Matching a spike to a memory step is the quickest way to find a stutter caused by loading.

6. Your next optimization

An offline report on the practice recording. It is cut off here; the real list continues.

This is the "what do I fix first" part. Click Offline report and the page ranks its suspects, with a confidence (low, medium) and a suggested next step for each.

Every finding quotes the evidence it is based on, such as pathfind: 230 samples. The page only suggests; it never changes your game.

How to use it well: fix the top suspect, run again, and compare. Read a performance report goes through one in detail.

7. Capture and dump log

A short diary of the last 20 things you did in this tab: opened a recording, made a report, started a session. It is there so you can remember what you were looking at. It lasts only as long as the tab does.

At the very bottom of the page you will see the limits: measurements are taken once a second, a session lasts at most five minutes, and a recording can be up to 50 MiB.

What it cannot tell you yet

Being clear about this saves you time:

• No frame rate from a live measurement. Use the FPS counter on the game, or open a recording that has frames.
• No per-function view from a live measurement. It shows processor and memory only.
• No graphics-card timing. Frame rate is what the browser actually shows, not how long the graphics card worked.
• The file-loading section needs a recording that contains file loads.
• Unity. Unity builds have not been tested with it.

A five-minute routine

1. vapour test, then play the part of your game you worry about for a minute.
2. Check the tiles. Is the 1% low much worse than the average?
3. Look at the timeline. Where are the tall spikes? Is memory stepping up?
4. Click a spike window to zoom in, then look at the asset table for something heavy loading at that moment.
5. Make one change, run again, and use the comparison baseline.
6. When you are happy, publish.