Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 36 ยท Packaging and Publishing

Scale Manager and Mobile

Make Phaser games fit any screen with the Scale Manager. Compare FIT, ENVELOP and RESIZE modes, handle fullscreen and orientation, and add touch controls.

Your game will not run on one screen. It will run in a narrow phone held upright, a phone turned sideways, a tablet, a laptop and a 4K monitor, and the player may resize the window while playing. If the canvas is a fixed 800 by 600 pixels, it is either cut off, tiny or surrounded by empty space. Phaser's Scale Manager is the system that decides how your game's internal resolution maps onto the space the browser gives it.

This lesson explains the scale modes and when to choose each, how to react when the size changes, and how to prepare a game for touch screens with on-screen controls. These are the details that decide whether players on phones, who may be most of your audience, can actually play.

Two sizes: the game and the display

The key to the Scale Manager is that there are two different sizes:

  • The game size is the logical resolution: the coordinate system your code uses, for example 480 by 270. this.scale.width and this.scale.height give it. A sprite at x = 240 is in the middle no matter what.
  • The display size is how many CSS pixels the canvas takes on the page. The browser stretches the canvas to that size.

When the display size is larger than the game size, the picture is scaled up (and may look soft unless you use pixelArt: true). The scale mode is the rule for choosing the display size.

Scale modes

You set the mode in the game config:

JavaScript
const config = {
  type: Phaser.AUTO,
  scale: {
    mode: Phaser.Scale.FIT,
    autoCenter: Phaser.Scale.CENTER_BOTH,
    parent: 'game-container',
    width: 800,
    height: 450
  },
  scene: [Boot, Game]
};
Mode Behavior Good for
NONE The canvas keeps the game size; no scaling Fixed-size embeds
FIT Scales up or down to fit the parent while keeping the aspect ratio (letterbox bars appear) Most games; the safe default
ENVELOP Scales to cover the parent, keeping the aspect ratio; some of the game is cropped Full-bleed art, if you keep important things near the center
WIDTH_CONTROLS_HEIGHT Parent width decides the width; height follows the aspect ratio Vertical pages that scroll
HEIGHT_CONTROLS_WIDTH The opposite Games that fill a tall area
RESIZE The game size itself changes to match the parent; no scaling Games that lay out UI for any shape, tools, editors

autoCenter centers the canvas in its parent. min and max options limit the size, and zoom multiplies it (use Phaser.Scale.MAX_ZOOM for the biggest whole-number scale, great for pixel art).

flowchart TB
  Q{"Do you need the world<br/>to look the same everywhere?"} -- yes --> F["FIT<br/>letterbox bars"]
  Q -- no, more space is useful --> R["RESIZE<br/>re-layout the scene"]
  F --> Q2{"Cropping edges<br/>acceptable?"}
  Q2 -- yes --> E["ENVELOP"]

FIT is the default choice. RESIZE gives you the most flexibility and the most work.

Trying the modes

In the example below you can switch the mode while the game runs. Watch the two numbers: the game size stays 480 by 270 in FIT, ENVELOP and NONE, but changes in RESIZE, where the scene must move its objects itself. The layout is therefore written as a function that reads this.scale.width and this.scale.height, and runs again on every resize event.

Scale modes live

In FIT the blue frame always has the same proportions. In RESIZE it stretches to the whole preview area, and the objects move because layout() places them from fractions of the current size. That is the discipline of a resizable game: never hard-code positions, compute them from this.scale.

Responding to size and orientation

Several events help you adapt:

  • this.scale.on('resize', (gameSize, baseSize, displaySize, previousWidth, previousHeight) => { ... }) fires whenever the size changes (RESIZE mode, window changes, orientation changes).
  • this.scale.on('enterfullscreen') and 'leavefullscreen' tell you about fullscreen. Start fullscreen only from a user gesture with this.scale.toggleFullscreen() or startFullscreen(), since browsers refuse it otherwise.
  • this.scale.on('orientationchange', (orientation) => ...) gives Phaser.Scale.PORTRAIT or LANDSCAPE. A common pattern is a "please rotate your device" overlay for games designed for landscape.
  • this.scale.lockOrientation('landscape') works in fullscreen on supporting browsers.

Mobile browsers have two other quirks. Their address bars appear and disappear, changing the available height, so rely on the resize event rather than reading the window size once. And the page can scroll or zoom when the player touches the canvas, so add this CSS to your page to give the canvas full control of touch gestures:

CSS
html, body { margin: 0; height: 100%; overflow: hidden; touch-action: none; background: #000; }

High-density screens

Phones have 2 to 3 device pixels per CSS pixel. A 480 by 270 game stretched to a 1000 pixel wide canvas looks soft. You have two choices. For pixel art, keep the low resolution and turn off smoothing with pixelArt: true (or render: { antialias: false }), plus integer zooms for crisp pixels. For smooth art and text, use a larger logical size (for example 1280 by 720) and let FIT scale down, and pass resolution in text styles. Pick one approach per game and test on a real phone: the performance cost of large canvases is real, because the GPU fills more pixels.

Touch input

Phaser unifies mouse and touch: a pointer event fires for either, so a button written with pointerdown works on both. Several details are specific to touch:

  • Multi-touch. By default Phaser tracks the mouse pointer plus one touch pointer. Call this.input.addPointer(2) to track more, then read this.input.pointer1, pointer2, or loop through this.input.manager.pointers. A game with a move pad and a jump button needs at least two.
  • No hover. There is no pointerover before a tap. Do not hide information behind hover.
  • Finger-sized targets. At least 44 by 44 CSS pixels after scaling.
  • No keyboard. Every action needs an on-screen alternative: a virtual direction pad, a jump button, a pause button.
On-screen controls for touch and keyboard

The pad buttons set simple flags, and update() reads the flags together with the keyboard, so the same movement code serves both input types. Using pointerout and pointerupoutside to release the button prevents the stuck-key bug, where a finger slides off the pad and the hero keeps walking forever. The diagonal fix with normalize().scale(speed) stops the hero from moving 41 percent faster when two directions are held.

A checklist for mobile

  • Add <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no"> to the page.
  • Use touch-action: none and overflow: hidden on the container.
  • Show touch controls only on touch devices (or let the player toggle them).
  • Keep important UI away from screen corners that phones cover with notches and rounded edges (env(safe-area-inset-*) in CSS).
  • Test on real hardware with a throttled CPU. Mid-range phones are several times slower than your laptop.
  • Cap the frame rate or particle counts for low-end devices (see the next lessons on performance).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the difference between the game size and the display size?

    The Scale Manager maps the logical coordinate system (game size) to the pixels the browser gives the canvas (display size).
  2. 2. Which scale mode keeps the aspect ratio and shows the whole game, adding bars if needed?

    FIT scales to fit inside the parent. ENVELOP covers the parent and crops, RESIZE changes the game size itself, NONE does not scale.
  3. 3. In RESIZE mode, what must your scenes do?

    The game size changes, so hard-coded positions break. Place objects relative to the current size.
  4. 4. Why call this.input.addPointer(2) in a game with an on-screen D-pad and a jump button?

    By default only one touch pointer is tracked in addition to the mouse. More pointers allow multi-touch controls.
  5. 5. How do you avoid a stuck direction when a finger slides off an on-screen button?

    pointerup does not fire on the button when the finger is released elsewhere. Listening for pointerout and pointerupoutside resets the state.

Summary

  • The Scale Manager maps the logical game size to the display size; the mode (FIT, ENVELOP, RESIZE, NONE, ...) is the rule.
  • FIT plus autoCenter is the safe default; RESIZE demands layouts computed from this.scale.
  • React to resize, fullscreen and orientation events; start fullscreen from a user gesture.
  • Choose pixel-art scaling or a high logical resolution on purpose, and test on real devices.
  • For touch, support multi-touch, large targets and on-screen controls, and release buttons on pointerout and pointerupoutside.

Next: Vite, TypeScript and Project Structure