Skip to main content

Variable: uiScaleModes

const uiScaleModes: object

Defined in: ui/types/ui-scale-mode.ts:6

Controls how a CanvasEcsComponent's root rect (and, in turn, its UI camera's verticalWorldUnits) responds to the render destination's current size, resolved fresh every frame by createUiLayoutEcsSystem.

Type Declaration​

constantPixelSize​

readonly constantPixelSize: "constantPixelSize" = 'constantPixelSize'

The root rect matches the render destination's actual pixel dimensions one-to-one, ignoring referenceResolution entirely - 1 UI world unit is always exactly 1 screen pixel. UI elements keep a constant on-screen size regardless of resolution, at the cost of taking up a different fraction of the screen on different displays.

fitReferenceResolution​

readonly fitReferenceResolution: "fitReferenceResolution" = 'fitReferenceResolution'

The root rect is always at least referenceResolution on both axes - whichever of scaleWithScreenSize's or matchWidth's height it would produce is larger, letterboxing or pillarboxing the destination's excess space on whichever axis isn't the limiting one. Unlike either of those two modes alone, a UI built to fill the full reference resolution (e.g. content anchored out to all four edges) never gets cropped or squashed below its authored size, at any destination aspect ratio - the tradeoff is that a destination whose aspect ratio doesn't match referenceResolution's always shows some letterbox/pillarbox space scaleWithScreenSize/matchWidth wouldn't have.

matchWidth​

readonly matchWidth: "matchWidth" = 'matchWidth'

The root rect's width stays pinned to referenceResolution.x; its height is recomputed every frame from the destination's live aspect ratio. Prefer this over scaleWithScreenSize when a UI's horizontal layout (e.g. a fixed-width side panel) matters more than its vertical one.

scaleWithScreenSize​

readonly scaleWithScreenSize: "scaleWithScreenSize" = 'scaleWithScreenSize'

The root rect's height stays pinned to referenceResolution.y regardless of the destination's size; its width follows the destination's live aspect ratio. The default - a UI authored at the reference resolution reads at the same relative size on any screen height.