Skip to content

Handle resize

Tick UI handles full-screen resolution changes automatically through the BaseGameUI lifecycle and the per-frame scale-cache refresh. This page documents what is automatic, what needs explicit handling, and the edge cases (custom render targets, viewport-rect cameras, dynamic resolution, mid-frame changes).

What is automatic

The default BaseGameUI flow does nothing per resize beyond the per-frame work it already does:

  • BeginFrame(new Vector2Int(Screen.width, Screen.height)) recomputes the layout-to-screen scale cache from the current screen size and the configuration's aspect-ratio map.

As long as your DoUI calls BeginFrame with the current Screen.width and Screen.height, the per-frame scale follows the screen. No manual resize handler is required for full-screen display targets at URP render scale 1.0.

For the model behind the scale cache, refer to Coordinate spaces.

To handle resize correctly

For the typical case, no action is needed. Confirm the basics:

  1. Confirm DoUI calls ui.BeginFrame(new Vector2Int(Screen.width, Screen.height)) each frame.
  2. Test under your target aspect ratios. Add new entries to Configuration.AspectRatioLayouts if your project supports ratios outside the default map.

Add an aspect ratio

Override CreateConfiguration in your BaseGameUI subclass to extend the aspect-ratio map:

protected override Configuration CreateConfiguration()
{
    var config = base.CreateConfiguration();
    // 1:1 (square mobile screens, for example)
    config.AspectRatioLayouts[1.0f / 1.0f] = new Vector2Int(1080, 1080);
    return config;
}

BeginFrame picks the closest entry in the map each frame, so changing the map at runtime affects the next frame's reference resolution.

For the field reference, refer to Configuration.

Edge cases

Mid-frame resolution change. : Calling Screen.SetResolution from inside DoUI produces undefined ordering. Screen.width and Screen.height are stable within a frame on Unity's API contract; trigger resolution changes from event handlers instead.

Aspect-ratio change at runtime. : The aspect-ratio map picks the closest entry. To support a new ratio, add it to CreateConfiguration (above). To swap the entire map at runtime, hold a reference to the Configuration and update its AspectRatioLayouts directly.

URP render scale, custom render targets, viewport-rect cameras, or dynamic resolution. : Handled. The shipped injectors forward the active target's pixel dimensions to the drawer each frame via SetRenderTarget(target, size, isOffscreen), so render scale ≠ 1, off-screen RenderTexture targets, viewport-rect cameras, and dynamic resolution position the UI correctly. Custom integrations need to do the same. Refer to Build a custom integration.

Pitfalls

UI scales wrong on a resolution change. : BeginFrame is being called with stale dimensions. Always pass the current Screen.width and Screen.height, not a cached value.

The aspect-ratio map skips the active aspect. : The new aspect was added to AspectRatioLayouts after the BaseGameUI's Start ran. Edit CreateConfiguration so the new entries are present at construction.

Additional resources