Scale Manager
The Scale Manager is a global system found on the game's scale property and on each scene's scale property (this.scale). Its width and height (this.scale.width and this.scale.height, in a scene) are the current game dimensions, in game pixels.
Configure it in the scale property of the game config. Some config values (e.g., width, height, parent) can also be put directly in the game config.
Use scale mode FIT or NONE and the default parent.
Debugging Scale Manager issues is a bit of a hassle, and requires some CSS/HTML knowledge.
The parent is the HTML element where the game canvas is inserted. The default parent is the document body, representing the browser window.
You can give an HTML Element or its id as a parent config value. Generally, the parent needs an effective height that isn't auto for scaling or resizing to work correctly.
<div id="parent"></div>
<script>new Phaser.Game({ parent: 'parent' });</script>If you're using scale mode NONE, you will probably set the viewport width to the actual width of the game, e.g.,
<meta name="viewport" content="width=1024">If you're using one of the scaling modes, you will probably set the viewport width to the initial width.
<meta name="viewport" content="initial-scale=1">With the default parent, generally all you need is
body { margin: 0; }If you've turned off expandParent, you would use
html { height: 100%; }
body { margin: 0; height: 100%; }Sometimes
html { overflow: hidden; }is also needed.
When expandParent is on (the default), Phaser will try to fix a zero-height parent and ancestors by giving them height: 100%.
The Scale Manager does whole-canvas scaling or resizing, depending on the scale mode you choose.
Scaling means canvas pixels are mapped onto CSS pixels. The game dimensions (width, height, gameSize) stay the same; only the display dimensions (displaySize) change. The scaling modes are FIT, ENVELOP, HEIGHT_CONTROLS_WIDTH, and WIDTH_CONTROLS_HEIGHT.
With scale mode NONE, you can also scale the canvas by a fixed multiple with zoom.
Resizing means pixels are added or removed from the canvas context itself. The game and display dimensions are identical. This happens with scale mode RESIZE.
No scaling or resizing, but the Scale Manager is still running and emits events.
You can use resize() in this mode. You can even call resize() within a RESIZE event callback, if you compare the prevWidth and prevHeight arguments to the current game dimensions (otherwise you'll get stuck in a loop).
Scale the canvas to fit the parent on both axes. If the aspect ratios don't match, there will be gaps ("bars") one one axis.
You can use setGameSize() in this mode, but that's unusual.
This is the easiest mode and the best choice for most games.
Scale the canvas to fit the parent on the controlling axis. If the aspect ratios don't match, there will be either gaps or overflow on the non-controlling axis.
You can use setGameSize() in these modes, but that's unusual.
Scale the canvas to fill the parent on both axes. If the aspect ratios don't match, the canvas will be clipped on one axis. You should ensure that only nonessential game content gets hidden.
You can use setGameSize() in this mode, but that's unusual.
The canvas is resized to match the parent exactly, without scaling. Scene cameras with a default viewport (i.e., the game dimensions) are also resized automatically.
Don't use resize() or setGameSize() in this mode — the Scale Manager is already doing that! If you want to resize the game canvas by your own criteria, use scale mode NONE and call resize() from a resize event callback instead.
RESIZE only adds or removes pixels to the canvas context. It can't magically make your game look right at any size. You have to decide what to do with the new game area.
Truly responsive games could use scale mode NONE or RESIZE and then scale and reposition game objects from the resize event callback, but that's quite complex.
A simpler method is zooming and scrolling cameras to fit the new game size.