Tutorial: test and measure your game locally

Preview tools Works for Godot, Unity and Bevy About 10 minutes

Before you publish, run your game on your own computer and see how it really performs. One command opens your game with a live speed counter and a performance page next to it. Everything stays on your computer: nothing is uploaded, and none of it ends up in the game you publish.

What you need

Tell the command where vapour-profiler is by putting it next to the vapour program, adding it to your PATH, or passing --profiler /path/to/vapour-profiler.

Run it

cd my-game          # the folder with vapour.toml
vapour test

Testing TPS Demo v0.1.0 at http://127.0.0.1:41873/
FPS overlay on (local test only). Close the game tab for a summary; Ctrl+C to stop.
eBPF profiler attached to the game browser (CPU and memory, browser plus its processes).
Capture started automatically; open the profiler tab to watch it. The profiler session lasts 5 minutes. Close the browser to stop.

A browser window opens with two tabs: your game, and the performance page. Measuring has already started. To stop, close the browser or press Ctrl+C. Everything is cleaned up.

If the performance page cannot start, the command says why and carries on with just the speed counter:

Profiler not started: vapour-profiler not found: pass --profiler /path/to/vapour-profiler, set VAPOUR_PROFILER, put it next to the vapour binary, or put it on PATH
Continuing with the FPS overlay only.

Options

The speed counter

Captured in a browser without a graphics card, so the numbers are low. On a real computer they will be much higher.

The four lines mean:

The 1% low is the number players feel. A game can average 60 FPS and still stutter, and a low 1% low is how you spot it. Here is a real example, the Bevy sample game just after pressing Play:

The average looks fine at 31 FPS, but the 1% low of 4 FPS and the 900 ms worst frame reveal a hitch while the game starts. The average hid it.

Press Ctrl+Shift+F to hide or show the counter. When you close the game tab, the command prints a one-line summary with the frame count, the average FPS, the 1% low and the worst frame.

You can also test at phone size. This is the same game in a phone-sized window:

The performance page

The second tab shows how hard your computer is working while the game runs: processor, memory, and more.

A real live test of the Godot sample game, in a browser without a graphics card.

Understand your game's performance walks through every part of the page, what each number means and what to do about it. A live test shows processor and memory. It does not show frame rate or which part of your code is slow yet; use the speed counter for frame rate.

A test lasts at most five minutes. Run vapour test again for another.

Look at a saved recording

You can open a saved recording (a .vpt file) with Open dump on the performance page. Nothing is measured when you do, it is only read. Try the demo recording (made-up data) to see charts, a flamegraph and a report without needing a game.

If it does not work

What you learned

• vapour test is local only and never changes your game.
• The speed counter tells you whether your game is smooth. The performance page tells you where the computer's time goes.
• Watch the 1% low, not the average, to find stutter.