Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Export and Optimization

Profiling and Performance

Measure before you optimize in Godot 4: frame time budgets, the Debugger Profiler, Monitors, Visual Profiler, Performance singleton, custom timing code and fixed-step physics, with Python stand-ins.

"My game is slow" is not a diagnosis. Is the CPU or the GPU the bottleneck? Is it script code, physics, too many draw calls, memory? Godot ships tools that answer these questions, and the golden rule is simple: measure first, change one thing, measure again.

Godot cannot run on this site, so editor tools and scripts are read-only. The runnable blocks are Python stand-ins that model frame budgets and timing. Before this lesson, see exporting your game.

Frame time, not FPS

FPS (frames per second) is easy to say but misleading, because it is not linear. Use frame time in milliseconds:

  • 60 FPS = 16.67 ms per frame budget.
  • 30 FPS = 33.3 ms.
  • 120 FPS = 8.33 ms; 144 FPS = 6.94 ms.

Going from 60 to 55 FPS costs 1.5 ms; going from 30 to 25 FPS costs 6.7 ms. All your game logic, physics, rendering and audio must fit into the budget on the slowest device you support, not on your development machine.

Python Stand-in (Python, not Godot): frame budget and dropped frames

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

An average of 22 ms hides the real problem: the occasional 34 and 48 ms spikes, which the player feels as stutter. Always look at the worst frames, not only the average.

The built-in tools

Run the game from the editor and open the Debugger panel at the bottom:

  • Profiler: press Start. It lists functions with their time per frame, self time versus total time, and call counts. This finds slow GDScript.
  • Visual Profiler: a timeline of CPU and GPU time per rendering stage (shadows, opaque, transparent, post-processing). It tells you whether you are CPU-bound or GPU-bound.
  • Monitors: live graphs of FPS, process and physics time, object count, node count, orphan nodes, memory, draw calls, vertices drawn and more.
  • Network Profiler and Video RAM: bandwidth in multiplayer, and a list of textures and meshes taking GPU memory.
  • Misc > Debug > Visible Collision Shapes / Visible Navigation and Remote scene tree: inspect the running game.

Also enable Debug > Visible Collision Shapes while testing physics, and Debug > Force Single Window if the game shows odd focus problems.

Reading the symptoms

flowchart TD
    A["Low FPS"] --> B{"Visual Profiler:<br/>CPU or GPU time higher?"}
    B -->|"CPU"| C{"Profiler: script,<br/>physics or rendering setup?"}
    B -->|"GPU"| D["Lower resolution, shadows,<br/>SSAO, glow, overdraw"]
    C -->|"script"| E["Optimize loops, cache nodes,<br/>avoid _process work"]
    C -->|"physics"| F["Fewer bodies, simpler shapes"]
    C -->|"draw calls"| G["Batch, MultiMesh, atlas, culling"]

Decide which resource is limiting before touching any code.

A quick test: lower the window resolution. If FPS rises a lot, you are GPU fill-rate bound; if it does not change, the CPU is the limit.

Timing your own code

Use Time.get_ticks_usec() to time a block. Measure many repetitions, because a single run is noisy:

GDSCRIPT
func benchmark(label: String, callable: Callable, repeats := 1000) -> void:
	var start := Time.get_ticks_usec()
	for i in repeats:
		callable.call()
	var elapsed := Time.get_ticks_usec() - start
	print("%s: %.3f ms per call" % [label, elapsed / 1000.0 / repeats])

func _ready() -> void:
	benchmark("distance_to", func(): Vector2.ZERO.distance_to(Vector2(3, 4)))
	benchmark("distance_squared_to", func(): Vector2.ZERO.distance_squared_to(Vector2(3, 4)))

To show numbers on screen, read the Performance singleton: Performance.get_monitor(Performance.TIME_FPS), Performance.OBJECT_NODE_COUNT, Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME. Register your own monitor with Performance.add_custom_monitor("game/enemies", get_enemy_count) and it appears in the Monitors tab.

Python Stand-in (Python, not Godot): a benchmark helper and why repeats matter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Comparing squared distances (distance_squared_to) avoids a square root and gives the same answer for "is it closer than r": compare with r * r.

Fixed timestep: why physics can spiral

Godot runs physics at a fixed rate (physics/common/physics_ticks_per_second, default 60) and renders at a variable rate. If a frame takes longer than the step, the engine runs several physics steps to catch up, which costs more time, which makes the next frame longer: the spiral of death. Godot caps catch-up with max_physics_steps_per_frame (default 8) and slows the game instead.

Python Stand-in (Python, not Godot): how many physics steps run per rendered frame

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The 200 ms frame hits the cap of 8 steps; the game runs in slow motion rather than freezing.

A profiling checklist

  1. Test a release-like build on the target device (debug builds and the editor are slower).
  2. Record a baseline: average and worst frame time, draw calls, memory.
  3. Change one thing at a time.
  4. Fix the biggest cost first (Amdahl's law: speeding up 5 percent of the frame cannot give more than 5 percent).
  5. Re-measure and keep the results.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the frame-time budget for 60 FPS?

    1000 ms divided by 60 is 16.67 ms for everything in one frame.
  2. 2. Which tool shows whether the CPU or the GPU limits a frame?

    The Visual Profiler shows CPU and GPU time per render stage.
  3. 3. Why look at worst-case frames instead of only the average FPS?

    A few 40 ms spikes feel bad even if the average looks fine.
  4. 4. What does lowering the window resolution tell you if FPS jumps up?

    Fewer pixels reduce GPU work; if that helps a lot, the GPU was the bottleneck.

Summary

  • Think in milliseconds per frame; stay under the budget on the slowest target.
  • Use the Profiler, Visual Profiler and Monitors; determine CPU vs GPU first.
  • Time code with Time.get_ticks_usec() over many repeats; read counters from Performance.
  • Physics runs at a fixed step with a catch-up cap; measure on release-like builds, one change at a time.

Next: Optimizing 2D and 3D Scenes