Use this skill when making a Phaser 4 game responsive or handling display scaling. Covers ScaleManager, scale modes (FIT, RESIZE, EXPAND, ENVELOP), auto-center, fullscreen, and browser resize handling. Triggers on: ScaleManager, responsive, resize, fullscreen, FIT, scale mode.

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: 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. Scale Modes (src/scale/const/SCALE MODE CONST.js) All modes are on Phaser.Scale.ScaleModes and are set via scale.mode in config: Constant Value Behavior NONE 0 No automatic scaling. Canvas uses config width/height. You manage sizing yourself. If you resize the canvas externally, call game.scale.resize(w, h) to update internals. WIDTH CONTROLS HEIGHT 1 Height adjusts automatically to maintain aspect ratio based on width. HEIGHT CONTROLS WIDTH 2 Width adjusts automatically to maintain aspect ratio based on height. FIT 3 Scales to fit inside parent while preserving aspect ratio. May leave empty space (letterbox/pillarbox). Most commonly used mode. ENVELOP 4 Scales to cover the entire parent while preserving aspect ratio. May extend beyond parent bounds (content gets cropped). RESIZE 5 Canvas element itself is resized to fill parent. No CSS scaling 1:1 pixel mapping. The gameSize , baseSize , and displaySize all change to match parent. Beware of GPU fill rate on large displays. EXPAND 6 Hybrid of RESIZE and FIT. The visible area resizes to fill the parent, and the canvas scales to fit inside that area. Added in v3.80. 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: Constant Value Behavior NO CENTER 0 No auto centering (default). CENTER BOTH 1 Center horizontally and vertically within parent. CENTER HORIZONTALLY 2 Center horizontally only. CENTER VERTICALLY 3 Center vertically only. 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: Constant Value Behavior NO ZOOM 1 No zoom (default). ZOOM 2X 2 2x zoom good for pixel art at low base resolution. ZOOM 4X 4 4x zoom. MAX ZOOM 1 Automatically calculates the largest integer zoom that fits in the parent. 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) 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) 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 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 Fixed Size (No Scaling) 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 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 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 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: Property Type Default Description width number\ string 1024 Base game width. Strings like '100%' resolve against parent size. height number\ string 768 Base game height. Strings like '100%' resolve against parent size. zoom number\ ZoomType 1 Canvas zoom factor. Use Phaser.Scale.MAX ZOOM for auto. parent HTMLElement\ string\ null undefined Parent DOM element or its ID. undefined = document.body . null = no parent (you manage canvas placement). expandParent boolean true Allow ScaleManager to set parent/body CSS height to 100%. mode ScaleModeType NONE Scale mode constant (see table above). min {width, height} Minimum canvas dimensions. max {width, height} Maximum canvas dimensions. snap {width, height} Snap values for resize rounding. autoRound boolean false Floor display/style sizes for low powered device performance. autoCenter CenterType NO CENTER Auto centering mode (see table above). resizeInterval number 500 Milliseconds between parent size checks (fallback polling). fullscreenTarget HTMLElement\ string undefined Element to send fullscreen. If not set, Phaser creates a wrapper div. Events (src/scale/events/) All events are on Phaser.Scale.Events and are emitted by the ScaleManager instance ( game.scale ): Event String Value Callback Signature When RESIZE 'resize' (gameSize, baseSize, displaySize, previousWidth, previousHeight) Any resize, refresh, or scale change. The three Size parameters have .width , .height , .aspectRatio . ORIENTATION CHANGE 'orientationchange' (orientation) Device orientation changes. orientation is a string constant from Phaser.Scale.Orientation . ENTER FULLSCREEN 'enterfullscreen' () Browser successfully enters fullscreen. LEAVE FULLSCREEN 'leavefullscreen' () Browser leaves fullscreen (via code or user ESC). FULLSCREEN FAILED 'fullscreenfailed' (error) Fullscreen request was denied by the browser. FULLSCREEN UNSUPPORTED 'fullscreenunsupported' () Browser does not support the Fullscreen API. API Quick Reference Key Properties (read only unless noted) Property Type Description width number Game width (from gameSize.width ). height number Game height (from gameSize.height ). isFullscreen boolean Currently in fullscreen mode. isPortrait boolean Device is in portrait orientation. isLandscape boolean Device is in landscape orientation. isGamePortrait boolean Game dimensions are taller than wide. isGameLandscape boolean Game dimensions are wider than tall. scaleMode number Current scale mode constant. orientation string Current orientation string. zoom number Current zoom factor. autoRound boolean Whether sizes are auto floored. autoCenter number Current center mode constant. parentSize Size Computed parent dimensions. gameSize Size Unmodified game dimensions. baseSize Size Canvas element dimensions. displaySize Size CSS scaled display dimensions. displayScale Vector2 Ratio of baseSize to canvasBounds (used for input mapping). canvas HTMLCanvasElement The game canvas element. canvasBounds Rectangle DOM bounding rect of the canvas. parent HTMLElement The parent DOM element. parentIsWindow boolean True if parent is document.body . resizeInterval number Polling interval in ms (writable). Key Methods Method Returns Description resize(width, height) this For NONE mode: sets game, base, and display sizes directly. Updates canvas element and CSS. setGameSize(width, height) this For scaled modes (FIT, etc.): changes the base game size and re applies scaling. setParentSize(width, height) this Manually set parent dimensions (useful when parent: null ). setZoom(value) this Change zoom factor at runtime. setMaxZoom() this Set zoom to maximum integer that fits parent. setSnap(snapWidth, snapHeight) this Set or reset snap grid values. getMaxZoom() number Calculate (but don't apply) the max zoom. getViewPort(camera?, out?) Rectangle Get the visible area rectangle, optionally for a specific camera. refresh(prevW?, prevH?) this Force recalculation of scale, bounds, orientation. Emits RESIZE. startFullscreen(options?) void Enter fullscreen. Must be called from pointerup . stopFullscreen() void Exit fullscreen. toggleFullscreen(options?) void Toggle fullscreen state. lockOrientation(orientation) boolean Attempt to lock screen orientation (mobile only). transformX(pageX) number Convert DOM pageX to game coordinate. transformY(pageY) number Convert DOM pageY to game coordinate. getParentBounds() boolean Recalculate parent size. Returns true if changed. updateC

scale-and-responsive