Skip to content

Configuration

The Configuration struct passed into the UI constructor. It drives how layout-space pixels map to screen pixels, and holds the aspect-ratio map used by ScaleWithScreenSize. This page documents the public fields and the defaults BaseGameUI provides.

Fields

Field Type Effect
AspectRatioLayouts Dictionary<float, Vector2Int> Maps aspect ratio (width / height) to a reference resolution. Used when ScaleMode is ScaleWithScreenSize; the closest entry is picked per frame size.
ScaleMode ScaleMode How layout-space pixels map to screen pixels: ScaleWithScreenSize, ConstantPixelSize, or ConstantPhysicalSize. The struct's own default is ScaleWithScreenSize; BaseGameUI overrides this to ConstantPixelSize.
ReferenceDpi float The DPI the layout was authored against, used by ConstantPhysicalSize. Treated as 96 when ≤ 0.
FallbackDpi float The DPI assumed when Screen.dpi reports 0, used by ConstantPhysicalSize. Treated as 96 when ≤ 0.
DpiSource IDpiSource Where ConstantPhysicalSize reads DPI from. Defaults to Screen.dpi; tests can substitute a stub.
Scale float Global UI-scale multiplier applied on top of the active ScaleMode (1.0 = native). Values ≤ 0 are treated as 1.0.
Bindings InputBindings Per-feature input bindings the UI reads. Null fields fall back to InputBindings.Default. Can be replaced at runtime via UI.SetBindings.

The struct also caches m_lastScreenResolution and m_layoutSize internally; these are not user-facing.

Default aspect-ratio map

BaseGameUI.CreateConfiguration populates the map with these entries:

Aspect ratio Reference resolution
16:9 1920×1080
16:10 1920×1200
4:3 1600×1200
21:9 2560×1080
32:9 3840×1080

Override CreateConfiguration in your BaseGameUI subclass to add or replace entries.

Methods

Method Returns Effect
GetReferenceResolution() Vector2Int The reference resolution for the current Screen.width / Screen.height and ScaleMode. For ScaleWithScreenSize, cached per resolution change and recomputed lazily.
GetReferenceResolution(int width, int height) Vector2Int As above, but for an explicit frame size — correct for off-screen render targets.
GetReferenceToScreenRatio() Vector2 (Screen.width / refX, Screen.height / refY). The scale factors used to convert layout-space rects to screen-space rects.
GetReferenceToScreenRatio(int width, int height) Vector2 As above, for an explicit frame size.
ResolveScale() float Returns Scale with the "≤ 0 means unset" sentinel resolved to 1.0.

Override pattern

public class MyGameUI : BaseGameUI
{
    protected override Configuration CreateConfiguration()
    {
        var config = base.CreateConfiguration();
        // Add a 1:1 entry for square mobile screens.
        config.AspectRatioLayouts[1.0f] = new Vector2Int(1080, 1080);
        return config;
    }
}

Additional resources