Scale And Responsive

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