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.godothadrenderer/rendering_method.mobile="gl_compatibility". I had assumed a.iosoverride would be read on iPhones. It is not: on phones Godot reads the.mobileoverride. 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
- Measure on the device. The game ran perfectly on my Mac. The problem only existed on the phone.
- Switch suspects off one at a time. When none of them moves the number, stop optimising your code.
- 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.
- 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.