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:

Component	Property	Purpose
gameSize	game.scale.gameSize	The unmodified game dimensions from config. Used for world bounds, cameras. Read via game.scale.width / game.scale.height.
baseSize	game.scale.baseSize	The auto-rounded gameSize. Sets the actual canvas.width and canvas.height attributes.
displaySize	game.scale.displaySize	The CSS-scaled canvas size after applying scale mode, parent bounds, and zoom. Sets canvas.style.width / canvas.style.height.

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.