Forem: Ankit

t.MaxFPS vs r.SetFramePace - The Two Knobs Every UE5 Android Dev Must Understand

Ankit — Tue, 24 Mar 2026 16:59:34 +0000

I'd been wrestling with the nitty-gritties of what should be a straightforward problem — setting a specific frame rate on Android in Unreal Engine 5. Two console variables, t.MaxFPS and r.SetFramePace, kept tripping me up until I cracked open the engine and traced what they actually do under the hood.

If you've ever stared at Unreal Insights wondering why your frames aren't hitting the target you set, or if the term "SwappyGL" sounds like a rejected Pokémon name to you — this one's for you.

Prerequisites: A basic understanding of the 3 threads involved in UE gameplay (Game, Render, RHI) and familiarity with Unreal Insights.

t.MaxFPS

In simple terms, this is the console variable that caps your FPS. Set it to anything greater than 0, and it enforces that cap. Set it to 0 (or below), and the cap is off — the engine runs as fast as it can.

What it really does is put the game thread to sleep. The sleep duration is calculated from how long the game thread was busy in the previous frame. The event to look for in a utrace is STAT_FEngineLoop_UpdateTimeAndHandleMaxTickRate.

Let's say we set t.MaxFPS 60. In the frame above (frame 11477), the game thread worked for 6.9 ms, so the next wait time shakes out like this:

Wait time = Expected frame time − Previous frame's work time
         = 16.6 ms − 6.9 ms
         = ~9.7 ms
         ≈ ~9.5 ms (after accounting for scheduling overhead)

And that's exactly the ~9.5 ms sleep you see in the trace. Simple arithmetic, big impact.

r.SetFramePace

Sometimes, t.MaxFPS alone isn't enough. Consider this: you want 90 FPS gameplay. You set t.MaxFPS 90, the game thread happily ticks along at 90 Hz — but the display is still refreshing at 60 Hz. Each frame sits on screen for 16.66 ms regardless. Your RHI thread is presenting frames at 60 FPS no matter what the game thread thinks it's doing.

This is where r.SetFramePace comes to the rescue. Setting it to 90 tells the Android frame pacer to request a 90 Hz refresh rate from the display (if the device supports it). Put differently, r.SetFramePace controls the wait on the RHI thread — the presentation side of the pipeline.

In the trace above, the RHI thread waits on SwappyGL_swap, which only returns after 16.6 ms from the previous screen presentation — locked to the 60 Hz vsync interval.

Once r.SetFramePace 90 is also set, the vsync interval drops from ~16.6 ms to ~11.1 ms (since 1000 ms ÷ 90 = 11.1 ms). Now both the game thread and the display are speaking the same language.

What's SwappyGL?

Every frame on Android, the RHI thread eventually calls eglSwapBuffers to present the back buffer. In UE5, this goes through FAndroidOpenGLFramePacer, which wraps the actual swap call. SwappyGL_swap is one of the presentation strategies — and it's the smart one.

When frame pacing is active, UE doesn't call eglSwapBuffers directly. Instead, the call chain looks like this:

RHI Thread
│
└─ FAndroidOpenGLFramePacer::SwapBuffers()
   │
   └─ SwappyGL_swap(display, surface)
      │
      ├─ Reads Android Choreographer's vsync timestamps
      │   (the hardware vsync pulse from the display panel)
      │
      ├─ Computes TARGET presentation timestamp
      │   Target = LastPresentTime + DesiredFrameInterval
      │   e.g., 90 FPS on 90 Hz → interval = 11.1 ms
      │
      ├─ GPU finished EARLY (frame ready before target vsync):
      │   ├─ Sets EGL_ANDROID_presentation_time on the buffer
      │   │   ("don't show this until vsync T+N")
      │   ├─ Calls real eglSwapBuffers
      │   └─ BLOCKS the RHI thread until target vsync arrives
      │
      ├─ GPU finished ON TIME:
      │   ├─ Sets presentation timestamp for next vsync
      │   ├─ Calls real eglSwapBuffers
      │   └─ Returns almost immediately
      │
      └─ GPU finished LATE (missed target vsync):
          ├─ Detects the miss via Choreographer callback
          ├─ Adjusts pipeline mode (may add a frame of latency)
          ├─ Targets the NEXT valid vsync instead
          └─ Logs the miss for auto-swap-interval adjustment

The key thing SwappyGL provides is vsync phase-locking. It doesn't just throttle — it actively aligns frame presentation to specific vsync boundaries using EGL_ANDROID_presentation_time. This means:

Every frame displays for exactly the same duration (11.1 ms at 90 Hz).
Frame N is guaranteed to replace Frame N−1 at a precise vsync tick.
SurfaceFlinger (the compositor) knows in advance when each frame should appear.
Input latency becomes predictable because the pipeline depth is fixed.

In short, SwappyGL turns your frame timing from "best effort" into "contract with the display."

What Happens When Frame Pace Is Set to 0

When frame pacing is disabled, the path is much simpler — and much less coordinated:

RHI Thread
│
└─ FAndroidOpenGLFramePacer::SwapBuffers()
   │
   ├─ eglSwapInterval(display, 0)       // Set once at init: no vsync wait
   │
   └─ eglSwapBuffers(display, surface)   // Direct call, no Swappy
      │
      ├─ Queues the buffer to SurfaceFlinger
      ├─ Returns IMMEDIATELY (no vsync wait)
      └─ No presentation timestamp set
          (compositor shows it at the next available vsync, whenever that is)

In this mode, the only throttle is the game thread via t.MaxFPS. The RHI thread fires and forgets.

With SwappyGL — frames are vsync-phase-locked. Capture a utrace and you'll see frame present times at nearly exact 11.1 ms intervals (on 90 Hz), with sub-millisecond jitter. The RHI thread shows periodic blocks inside SwappyGL_swap as it holds frames until the right vsync. This is optimal for perceived smoothness.

Without SwappyGL — frames arrive at SurfaceFlinger whenever the RHI finishes them. The compositor displays each at the next available vsync, which might be 8.3 ms or 16.6 ms after the previous present, depending on exactly when the frame landed. On a 90 Hz panel, this is usually fine (the frame almost always catches the next vsync). But on a 120 Hz panel, you'd see an alternating 8.3 ms / 16.6 ms pattern — technically correct frame rate, but visually inconsistent.

When to Disable Frame Pacing

Here's where it gets interesting. Suppose you want 45 FPS gameplay, but the device only supports a 60 Hz refresh rate. The vsync interval is fixed at 16.6 ms, and your game thread needs 22.2 ms per frame to hit that 45 FPS target.

The problem: 22.2 ms doesn't fit neatly into 16.6 ms vsync slots. The RHI thread starts missing vsync deadlines, and frames get presented in an ugly pattern — 33.3 ms, 16.6 ms, 16.6 ms, 33.3 ms, and so on. The user perceives this as micro-stutter, and no amount of raw FPS fixes that feeling.

And that's the ideal case — assuming the render thread and game thread stay within budget. If gameplay is already lagging, the RHI thread misses vsync events even further. For example, Frame 2 might never be ready at V4 because the frame took just 1–2 ms extra to finish.

In such cases, it's better to disable frame pacing entirely, so that every vsync interval becomes a valid presentation opportunity. The frames won't be phase-locked, but they also won't be forced into a pattern that guarantees stutter.

Wrapping Up

If you're building anything on UE5 for Android — whether it's a casual puzzler or a AAA battle royale — these two CVars are quietly some of the most important knobs in your performance toolkit.

Think of it this way:

t.MaxFPS controls how fast your simulation ticks — the game thread budget.
r.SetFramePace controls how your frames reach the display — the presentation contract.

Getting them right means you're not leaving performance on the table. Getting them wrong means your game could be running at a perfectly good frame rate internally, while the user sees jank and stutter on screen — all because the display side wasn't in sync.

And the decision of when to disable frame pacing — that's the nuance that separates "it works on my test device" from "it's smooth across 500 different Android SKUs." Not every device supports the refresh rate you want. When the math doesn't fit the vsync grid, sometimes the smartest move is to let go of phase-locking and let frames land where they can.

The performance budget in mobile games is razor-thin. Every millisecond you save on frame pacing overhead or vsync misalignment is a millisecond you can spend on gameplay, physics, or that one particle effect your art director insists is "absolutely essential." Master these CVars, profile with Unreal Insights and Perfetto, and you'll squeeze every last drop from the hardware.

Now go set those frame rates — and may your vsyncs never stutter. 🎮

Unreal Shadows: The Hidden Cascade Trap

Ankit — Fri, 20 Mar 2026 18:10:53 +0000

For someone who has been working with Unreal Engine for just about a year, the learning curve can feel pretty steep. The engine exposes a huge number of properties and console variables, and when you first encounter them, it can feel like opening a control panel with way too many buttons and absolutely no labels.

In this blog, I'll talk about a fairly simple concept (although it felt quite complex to me when I first ran into it) and try to explain it in simpler terms. Think of this as me documenting the things I painfully figured out so that future-me doesn't have to go down the same rabbit hole again. And if this ends up helping someone else who is also staring at the same mysterious settings panel… well, that's a nice bonus.

The Problem

We have a Directional Light set up in a large level that is responsible for casting shadows on a few selected actors. Interestingly, when these shadows were cast on a vehicle, they appeared sharp at close range but started getting noticeably blurrier just around 2–3 meters away from the camera.

Naturally, the expectation was for the shadow to remain crisp and seamless, without this abrupt drop in quality.

Is the Quick Fix the Best Fix?

After a quick look into the famous BaseScalability.ini (which sits in the Config folder of the Engine), I found a scalability group setting for shadows. Scalability Groups are divided into Low, Medium, High, Epic, and Cinematic — corresponding to identifiers 0, 1, 2, 3, and Cine in the ini file.

Since I was debugging this on a high-end device, I looked at the CVars under [ShadowQuality@2] and tweaked r.Shadow.DistanceScale to get a seamless, crisp shadow across the vehicle.

But I wasn't in the mood to just make a quick change and walk away from the problem — especially since I'm usually the one breaking my head trying to squeeze out a few extra milliseconds of frame time so our devices don't start doubling as hand warmers while running the game.

So instead, I decided to dig a little deeper and try to understand what these shadow-related settings actually mean. I'm definitely not going to cover all of them here (mostly because I don't know all of them), but I'll walk through the ones I managed to study and experiment with.

Shadow Settings

`r.Shadow.CSM.MaxCascades`

Cascades are essentially distance ranges — the camera view is split into these ranges. Each cascade gets its own shadow map.

More cascades generally improve shadow quality at farther distances, but they also increase GPU cost.

`r.Shadow.MaxResolution`

Sets the maximum resolution allowed for dynamic shadow maps generated by lights. This directly affects how sharp the shadows appear.

Higher resolution = sharper shadows, but also higher GPU memory usage and rendering cost.

`r.Shadow.MaxCSMResolution`

Sets the maximum resolution specifically for Cascaded Shadow Maps generated by Directional Lights (for example, the Sun).

This is separate from r.Shadow.MaxResolution and applies only to cascaded shadows.

`r.Shadow.RadiusThreshold`

Controls when objects stop casting dynamic shadows based on their screen size. If an object appears smaller than this threshold on screen, it will not cast a shadow.

This helps reduce shadow rendering cost for tiny distant objects. Increasing this value can yield some performance gains, at the cost of small objects no longer casting shadows.

Example: If the value is 0.04, any object occupying less than 4% of the screen height will not cast a shadow.

`r.Shadow.DistanceScale`

Scales the maximum distance from the camera where dynamic shadows are rendered.

A lower value reduces the shadow rendering distance, while a higher value extends shadows further into the scene.

This directly impacts how far the shadowed region extends and proportionally affects GPU cost as well.

So yes — the quick "just increase the quality" fix wasn't really the best solution after all, was it?

Stop Looking at the Shadow — Maybe Check the Light?

Now, let's look at a few properties of the Directional Light in our level.

The Cascaded Shadow Maps section of the Directional Light has the following:

`DynamicShadowDistanceStationaryLight`

How far from the camera dynamic shadows from the directional light are rendered. Within this distance, shadows are calculated in real time using CSMs. Beyond this distance, shadows switch to baked/static shadows (or disappear if none exist).

`DynamicShadowCascades`

How many cascades are used for the directional light's CSM shadows. Instead of one large shadow map, the camera view is divided into multiple distance slices, and each cascade gets its own shadow map.

`CascadeDistributionExponent`

Controls how the cascades are distributed across the shadow distance. The range is from 1.0 to 4.0.

This is the interesting one — it took me a while to wrap my head around the concept:

Low Exponent (1.0): Cascades are spread more evenly across the distance.

High Exponent (4.0): More cascades are concentrated close to the camera, with lower detail farther away.

Wrapping Up

Consider the following Directional Light setup:

Dynamic Shadow Distance = 20,000 units
Num Cascades = 4
Distribution Exponent = 3.0

The cascade boundaries are computed using this formula:

Boundary(i) = DynamicShadowDistance × (i / NumCascades) ^ DistributionExponent

With Exponent = 3.0, the cascade boundaries work out to:

Cascade	Formula	Boundary (Unreal Units)	Boundary (Meters)
1	20000 × (1/4)³ = 20000 × 0.0156	312.5	3.12 m
2	20000 × (2/4)³ = 20000 × 0.125	2,500.0	25.00 m
3	20000 × (3/4)³ = 20000 × 0.4219	8,437.5	84.38 m
4	20000 × (4/4)³ = 20000 × 1.0	20,000.0	200.00 m

And this would explain why at a distance of roughly 3 meters (312.5 Unreal units) from the camera, we saw a drop in shadow quality — that's exactly where the first cascade ends and the next one begins.

If we change the Distribution Exponent to 2.0, the cascades shift like this:

Cascade	Formula	Boundary (Unreal Units)	Boundary (Meters)
1	20000 × (1/4)² = 20000 × 0.0625	1,250.0	12.50 m
2	20000 × (2/4)² = 20000 × 0.25	5,000.0	50.00 m
3	20000 × (3/4)² = 20000 × 0.5625	11,250.0	112.50 m
4	20000 × (4/4)² = 20000 × 1.0	20,000.0	200.00 m

This means the quality drop is pushed out to 12.5 meters instead of 3.12 meters — roughly 4× farther from the camera.

Trade-off?

Of course there is a trade-off!

The max CSM resolution of 2048 was originally being used for a relatively small coverage distance of 3.12 meters. After changing the cascade distribution, the same resolution now covers a much larger range of 12.5 meters.

What this means in practice is that the shadow texel density (texels per world unit) decreases. In simpler terms, the same number of texels now has to cover a larger area of the world, which naturally makes the shadow appear softer.

Important Insight

This does not mean the entire scene suddenly becomes 4× blurrier.

In reality, only Cascade 1 changes dramatically because its coverage area increases significantly. Meanwhile, Cascades 2–4 actually get sharper when using a distribution exponent of 2, since more shadow resolution is now distributed across a wider near-field range, and the far cascades cover proportionally less area than before.

That's pretty much the rabbit hole I went down while trying to understand why a shadow decided to become blurry a few meters away from the camera.

The takeaway for me was simple: many of these Unreal settings don't exist in isolation. Changing one value often shifts the balance somewhere else — sometimes improving one cascade while quietly hurting another. Understanding that trade-off is far more useful than blindly pushing everything to higher values.

More importantly, the next time I see a shadow doing something strange, at least I'll know where to start looking.

And hopefully, future-me will thank present-me for writing this down.