Scale and Responsive Design

How to use the ScaleManager for scaling, centering, fullscreen, orientation handling, and responsive resize in Phaser 4.

Key source paths: src/scale/ScaleManager.js, src/scale/const/, src/scale/events/, src/core/typedefs/ScaleConfig.js Related skills: ../game-setup-and-config/SKILL.md

Quick Start

Scale-to-fit with centering -- the most common setup for responsive games:

const config = {
    type: Phaser.AUTO,
    scale: {
        parent: 'game-container',
        mode: Phaser.Scale.FIT,
        autoCenter: Phaser.Scale.CENTER_BOTH,
        width: 800,
        height: 600
    },
    scene: MyScene
};

const game = new Phaser.Game(config);

The scale config object is parsed into a Phaser.Core.Config instance which the ScaleManager reads during boot. The ScaleManager sets the canvas element size and applies CSS scaling to fit it within its parent.

Core Concepts

ScaleManager (src/scale/ScaleManager.js)

The ScaleManager is created during the Game boot sequence and is accessible at game.scale or this.scale from within a Scene. It extends EventEmitter.

Three internal Size components drive all calculations:

Scaling works by keeping the canvas element dimensions fixed (baseSize) and stretching it via CSS properties (displaySize). This is equivalent to CSS transform-scale but without browser prefix issues.

The displayScale property (Phaser.Math.Vector2) holds the ratio baseSize / canvasBounds and is used internally for input coordinate transformation.

Scale Modes (src/scale/const/SCALE_MODE_CONST.js)

All modes are on Phaser.Scale.ScaleModes and are set via scale.mode in config:

Shorthand constants are also available directly on Phaser.Scale: Phaser.Scale.FIT, Phaser.Scale.RESIZE, etc.

Center Modes (src/scale/const/CENTER_CONST.js)

Set via scale.autoCenter in config. Centering is achieved by setting CSS marginLeft and marginTop on the canvas:

The parent element must have calculable bounds. If the parent has no defined width/height, centering will not work correctly.

Zoom (src/scale/const/ZOOM_CONST.js)

Set via scale.zoom in config. Multiplies the display size:

You can also pass any numeric value. The zoom affects CSS display size but not the canvas resolution.

Orientation (src/scale/const/ORIENTATION_CONST.js)

Read via game.scale.orientation. Values are strings:

• Phaser.Scale.Orientation.LANDSCAPE = 'landscape-primary'
• Phaser.Scale.Orientation.LANDSCAPE_SECONDARY = 'landscape-secondary'
• Phaser.Scale.Orientation.PORTRAIT = 'portrait-primary'
• Phaser.Scale.Orientation.PORTRAIT_SECONDARY = 'portrait-secondary'

Convenience booleans: game.scale.isPortrait, game.scale.isLandscape (device orientation), game.scale.isGamePortrait, game.scale.isGameLandscape (game dimensions).

Common Patterns

FIT Mode with Centering (Most Common)

scale: {
    parent: 'game-container',
    mode: Phaser.Scale.FIT,
    autoCenter: Phaser.Scale.CENTER_BOTH,
    width: 1280,
    height: 720
}

The game maintains its 16:9 aspect ratio and centers within the parent. Empty space appears as letterbox/pillarbox bars. Style the parent's background color to control bar appearance.

Responsive Resize (Dynamic Canvas Size)

scale: {
    parent: 'game-container',
    mode: Phaser.Scale.RESIZE,
    width: '100%',
    height: '100%'
}

// In your scene -- respond to size changes:
create() {
    this.scale.on('resize', this.handleResize, this);
}

handleResize(gameSize, baseSize, displaySize) {
    this.cameras.resize(gameSize.width, gameSize.height);
    // Reposition UI elements based on new dimensions
}

Width/height accept percentage strings (e.g., '100%') which resolve against the parent size. If the parent has no size, they fall back to window.innerWidth / window.innerHeight.

Fullscreen Toggle

// Must be called from a pointerup gesture (not pointerdown)
this.input.on('pointerup', () => {
    if (this.scale.isFullscreen) {
        this.scale.stopFullscreen();
    } else {
        this.scale.startFullscreen();
    }
});

// Or use the convenience method:
this.input.on('pointerup', () => {
    this.scale.toggleFullscreen();
});

• startFullscreen(fullscreenOptions) -- requests browser fullscreen. Default options: { navigationUI: 'hide' }.
• stopFullscreen() -- exits fullscreen mode.
• toggleFullscreen(fullscreenOptions) -- toggles between the two.
• isFullscreen -- read-only boolean for current state.

If no fullscreenTarget is configured, Phaser creates a temporary <div>, moves the canvas into it, and sends that div fullscreen. The div is removed when leaving fullscreen.

For iframes, the allowfullscreen attribute is required.

Mobile Orientation Handling

create() {
    this.scale.on('orientationchange', (orientation) => {
        if (orientation === Phaser.Scale.LANDSCAPE) {
            // Show game UI
        } else {
            // Show "rotate device" message
        }
    });

    // Lock orientation (mobile browsers only, limited support):
    this.scale.lockOrientation('landscape');
}

Fixed Size (No Scaling)

scale: {
    mode: Phaser.Scale.NONE,
    width: 800,
    height: 600
}

In NONE mode, if you change the canvas size externally you must call game.scale.resize(newWidth, newHeight) to update all internal components including input coordinates.

Pixel Art with Max Zoom

scale: {
    mode: Phaser.Scale.FIT,
    autoCenter: Phaser.Scale.CENTER_BOTH,
    width: 320,
    height: 240,
    zoom: Phaser.Scale.MAX_ZOOM
},
pixelArt: true

MAX_ZOOM calculates the largest integer multiplier that fits in the parent. Combined with pixelArt: true (which disables anti-aliasing), this gives crisp pixel rendering.

Snap Values for Grid Alignment

scale: {
    mode: Phaser.Scale.FIT,
    width: 800,
    height: 600,
    snap: { width: 16, height: 16 }
}

When the browser resizes, dimensions snap down to the nearest grid multiple (using floor). Best used with FIT mode. Can also be set at runtime: game.scale.setSnap(16, 16) or reset with game.scale.setSnap().

Min/Max Size Constraints

scale: {
    mode: Phaser.Scale.FIT,
    width: 800,
    height: 600,
    min: { width: 400, height: 300 },
    max: { width: 1600, height: 1200 }
}

The display size is clamped to these bounds during scaling calculations.

Configuration Reference

ScaleConfig (src/core/typedefs/ScaleConfig.js)

All properties go inside the scale object in your game config:

Events (src/scale/events/)

All events are on Phaser.Scale.Events and are emitted by the ScaleManager instance (game.scale):

API Quick Reference

Key Properties (read-only unless noted)

Key Methods

Gotchas

1. Parent element must have dimensions. The ScaleManager relies on the parent's computed CSS size. An unstyled <div> has zero height, which breaks centering and scaling. Either give it explicit CSS dimensions or let expandParent: true (the default) set body/parent to 100% height.

2. No padding on the parent. The ScaleManager does not account for parent padding. Apply padding to a wrapper element instead, or use margins on the parent's parent.

3. Do not style the canvas directly. The ScaleManager controls canvas.style.width, canvas.style.height, marginLeft, and marginTop. External CSS on the canvas will conflict.

4. Fullscreen requires pointerup, not pointerdown. On touch devices, pointerdown fullscreen requests are blocked unless the document already received touch input. Always use pointerup for reliable behavior.

5. Fullscreen in iframes needs allowfullscreen. Without this attribute on the iframe element, fullscreen requests will silently fail.

6. RESIZE mode and GPU fill-rate. RESIZE creates a 1:1 pixel canvas matching the parent. On high-resolution displays this can be very large. Monitor performance on low-end devices.

7. resize() vs setGameSize(). Use resize() only in NONE mode (it sets everything directly). Use setGameSize() when using FIT/ENVELOP/etc. (it preserves the scale mode calculations).

8. iOS height quirks. When the parent is the window on iOS, the ScaleManager uses GetInnerHeight to work around Safari's dynamic toolbar affecting getBoundingClientRect.

9. Percentage strings require a sized parent. Setting width: '100%' or height: '100%' resolves against parentSize. If the parent has no size, it falls back to window.innerWidth/innerHeight.

10. resizeInterval is a fallback poll. Modern browsers dispatch resize events, but the ScaleManager also polls every resizeInterval ms (default 500) to catch edge cases on older browsers.

Source File Map