Başar BallıözProduct Engineer
← All posts

Godot on iOS: from an uneven 60 fps to 120 Hz with Metal

Tibblo felt slightly sticky on my iPhone 14 Pro. Not slow, just never smooth. The main thread was idle most of every frame, so the code was not the problem. The renderer was, and the fix was one line in project.godot.

By Başar Ballıöz · · 3 min read

The symptom: a stutter you can feel but not point at

Scrolling the Settings screen, dragging the map, opening a sheet: everything worked, but on a 120 Hz ProMotion iPhone it felt like it was skipping. The kind of thing a player never reports and still notices. Before touching any code I wanted a number instead of a feeling.

Step one: a bench that runs on the phone

I added a small debug bench to the game. It opens a screen, scrolls it on its own for three seconds per variant, stands still, then drags it with made-up touches the way a finger would (with the screen's signals cut off so a fake touch can change nothing). For each run it prints:

  • frames per second and the 95th percentile frame time,
  • how many frames ran over 1.5 screen refreshes (a dropped frame),
  • how many ran over 2.5 refreshes (a hitch you can see).

Each variant switches one suspect off: the pet portrait, clipping and shadows, drawing at the 720×1280 design size instead of native resolution, the battery saver's 60 fps cap, and asking for Engine.max_fps = 120 instead of 0 (no cap).

The result: every variant ran at about 66 fps

With or without the portrait, at full or low resolution, capped or uncapped: about 66 fps, frames mostly 16.6 ms with some at 8 and some at 25. That uneven mix is exactly the stutter: the display gets a new frame on some refreshes and not others.

When removing the expensive parts changes nothing, the expensive parts are not the problem. Settings' own drawing was not what held the phone under 120.

Step two: Instruments

Xcode's Time Profiler on the device told the rest. The main thread did about 4 ms of work a frame, then sat idle until the display link fired again, mostly 16 to 18 ms later. The game was ready for the next frame long before it was allowed to draw it.

That pointed at the layer between the game and the screen. Tibblo used Godot's Compatibility renderer, which runs on OpenGL ES. On iOS, OpenGL has been deprecated for years and runs through a translation layer; on this phone it was held near 60 Hz, and unevenly.

The fix: let iOS draw with Metal

Godot 4's Mobile renderer uses Metal on iOS. Switching to it took one line, but it was not the line I expected:

  • My project.godot had renderer/rendering_method.mobile="gl_compatibility". I had assumed a .ios override would be read on iPhones. It is not: on phones Godot reads the .mobile override. Mobile is Godot's default for that override, so the fix was to delete the line.
  • Android stays on Compatibility. The game is tuned for mid-range Android phones, where Vulkan is often slower than GL, so the Android export passes --rendering-method gl_compatibility.

The same Settings bench on Metal: 118.9 fps, p95 8.8 ms, no hitches. Same code, same phone, double the frame rate, and the frames are even.

What I checked before shipping it

A renderer switch can change how things look, not just how fast they are. Tibblo's art is drawn from code (shapes, gradients, shadows), so I took look shots of Settings, the HUD, the town map and a mini-game on both renderers and compared them. They matched, apart from animations caught at different moments. The bench now prints which renderer is running, so a future result can never be read against the wrong one.

One thing is still open: the Android side has not been measured on a real Android phone since this change. The setting there did not change, but until it is measured, it is a belief, not a result.

What I would take from this

  1. Measure on the device. The game ran perfectly on my Mac. The problem only existed on the phone.
  2. Switch suspects off one at a time. When none of them moves the number, stop optimising your code.
  3. Look at what the main thread does between frames. 4 ms of work and 12 ms of waiting is not a performance problem in your game.
  4. Read which override your platform actually uses. A setting that is never read is worse than no setting: it looks like a decision.

For the bigger picture of how the game is built, see Godot 4 for web developers.

More posts

Quest pacing: measuring where a 150-level game goes flatHow I measured the story pacing of Tibblo's 763-day road from level 1 to 150, found where it went flat after level 40, and fixed it with three-step arcs, a daily limit and a 'Last time…' card. Smooth scrolling in Godot when every card's art is drawn from codeA Godot 4 tray of 230 cards with art drawn from code stuttered on every scroll. How a picture cache, a limit of two new pictures a frame and drawing only cards near the view made it smooth.