02 Mobile optimization
Optimize your Phaser game for phones
Phones differ from desktops in screen shape, pixel density, touch input and background
behaviour. These eight areas cover most of the work. The examples use Phaser 4.2, the latest 4.x
release.
01
Viewport and safe areas
Without viewport-fit=cover, iPhones and notched Android phones keep the page inside the
safe area, so the canvas never reaches the edges. With it, the canvas can use the full screen. Keep
on-screen controls inside env(safe-area-inset-*) so they clear the notch and the rounded
corners.
Use 100dvh instead of 100vh. Dynamic viewport units follow the address bar
as it shows and hides, so the game does not jump.
index.html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
style.css
html, body {
margin: 0;
height: 100%;
overflow: hidden;
overscroll-behavior: none;
}
#game {
height: 100dvh;
}
canvas {
display: block;
touch-action: none; /* no browser panning or pinch-zoom over the game */
}
02
Choose a scale mode
The Scale Manager sizes the canvas to its parent. FIT keeps the whole game visible and
adds bars where the aspect ratio differs. ENVELOP fills the screen and crops the
edges. RESIZE gives you the full screen size, and you lay out the HUD yourself.
Use FIT for fixed-layout games. Use RESIZE when the HUD has to adapt to each screen.
game.js
const game = new Phaser.Game({
type: Phaser.AUTO,
parent: 'game',
width: 390,
height: 844,
scale: {
mode: Phaser.Scale.FIT,
autoCenter: Phaser.Scale.CENTER_BOTH,
},
});
03
Handle resize and rotation
A phone fires a resize when it rotates or when the address bar changes. Listen to the Scale Manager's
RESIZE event instead of window's resize event. Phaser updates the canvas first, so the
gameSize you receive is already the new size.
Remove the listener on SHUTDOWN, so a restarted scene does not keep the old callback. If your own code
moves or hides the canvas, call this.scale.refresh() so Phaser recalculates its
bounds.
Level.js
class Level extends Phaser.Scene {
create() {
this.scoreText = this.add.text(16, 16, 'Score 0', { fontSize: '28px' });
// Touch target; the pause icon is drawn on the same spot
this.pauseButton = this.add.zone(0, 0, 48, 48).setInteractive();
this.pauseButton.on('pointerdown', () => this.scene.pause());
this.layoutHud(this.scale.gameSize);
this.scale.on(Phaser.Scale.Events.RESIZE, this.layoutHud, this);
this.events.once(Phaser.Scenes.Events.SHUTDOWN, () => {
this.scale.off(Phaser.Scale.Events.RESIZE, this.layoutHud, this);
});
}
layoutHud(gameSize) {
this.pauseButton.setPosition(gameSize.width - 36, 36);
}
}
04
Match the pixel density
Phaser sizes the canvas from width and height. It does not read
devicePixelRatio for you. On a 3x phone, a 390 px canvas is stretched three times, and
text looks soft.
Set the base size to the CSS size multiplied by the device pixel ratio, capped at 2. FIT still shows the
canvas at CSS size. On a 3x phone this draws about 44% of the physical pixels, which keeps the frame
rate reasonable. We tested scale.zoom in FIT mode, and it did not change the canvas size,
so use a scaled base size instead.
Game units are now DPR times larger. Place HUD with this.scale.gameSize, and multiply
hand-set sizes by DPR. Pixel art games should set pixelArt: true, so scaled sprites stay
sharp.
game.js
const DPR = Math.min(window.devicePixelRatio || 1, 2);
const game = new Phaser.Game({
type: Phaser.AUTO,
parent: 'game',
width: 390 * DPR,
height: 844 * DPR,
scale: {
mode: Phaser.Scale.FIT,
autoCenter: Phaser.Scale.CENTER_BOTH,
},
pixelArt: false, // true for pixel art
});
05
Make touch input reliable
Phaser merges mouse and touch into one pointer API, so pointerdown fires on a tap just as it
does on a click. For multi-touch, raise input.activePointers. Its default is 1, so set it
to the number of fingers your controls need.
Use pointerdown for buttons that should react at once. Use pointerup when the
action should count only if the finger lifts over the button. Keep touch targets at least 44 CSS px
square, and multiply them by DPR when you use a scaled base size.
game.js
const game = new Phaser.Game({
input: { activePointers: 3 }, // track up to three fingers
disableContextMenu: true, // no long-press menu on Android
});
// Inside a scene: a 48 x 48 touch target for the pause button
const pause = this.add.zone(x, y, 48, 48).setInteractive();
pause.on('pointerdown', () => this.scene.pause());
06
Unlock audio and handle the background
Phones block audio until the player touches the screen. Check this.sound.locked, and wait
for the UNLOCKED event before you start the music.
When the app goes to the background, Phaser fires HIDDEN. Pause the game state there, so a player who
returns is not left inside a running match.
Menu.js
class Menu extends Phaser.Scene {
create() {
const playTheme = () => {
this.sound.play('theme', { loop: true });
};
if (this.sound.locked) {
this.sound.once(Phaser.Sound.Events.UNLOCKED, playTheme);
} else {
playTheme();
}
const onHidden = () => this.scene.pause();
this.game.events.on(Phaser.Core.Events.HIDDEN, onHidden);
this.events.once(Phaser.Scenes.Events.SHUTDOWN, () => {
this.game.events.off(Phaser.Core.Events.HIDDEN, onHidden);
});
}
}
07
Keep the frame rate steady
Phones have less GPU memory and fill rate than laptops. Pack sprites into texture atlases, so one draw
call covers many objects. autoMobileTextures limits WebGL to one texture per batch on iOS
and Android. skipUnreadyShaders stops the frame from stalling while shaders compile, but
objects whose shader is not ready are skipped. Warm them up during loading.
Measure on a mid-range phone, not on a flagship or a desktop browser.
game.js
const game = new Phaser.Game({
autoMobileTextures: true, // one texture per batch on iOS and Android
skipUnreadyShaders: true, // skip objects whose shader is still compiling
});
08
Test on a real phone
Browser device emulation does not show real GPU, touch or audio behaviour. Five-server, the dev server
by Yannick (@yandeu),
can serve your build over your Wi-Fi. With --host=0.0.0.0, it prints a Network URL. Open
that URL on your phone.
Use 0.0.0.0 only on a network you trust. It makes your files reachable from every device on
that network.
terminal
npm install -g five-server
five-server --root=dist --host=0.0.0.0 --no-browser
fiveserver.config.js
module.exports = {
remoteLogs: 'magenta', // show the phone's console in this terminal
};