Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

The Phaser Game Configuration Explained

Understand every important Phaser game config option: renderer type, size, parent, background, scale modes, pixel art, FPS, physics and scenes, with live examples.

Every Phaser game starts with a single object: the game configuration. It tells Phaser how big the game is, which renderer to use, where to put the canvas, how to scale on different screens, which physics to run and which scenes exist. Learning the options once saves hours of confusion later, because many "why does my game look blurry / too small / run twice as fast" questions are answered here.

The shape of a config

JavaScript
const config = {
  type: Phaser.AUTO,          // renderer
  width: 800,                 // game size in "game pixels"
  height: 450,
  parent: 'game',             // id of the element that receives the canvas
  backgroundColor: '#0f172a', // canvas clear color
  pixelArt: false,            // true for crisp pixel-art games
  scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
  physics: { default: 'arcade', arcade: { gravity: { y: 0 }, debug: false } },
  fps: { target: 60 },
  scene: [BootScene, MenuScene, PlayScene]
};
const game = new Phaser.Game(config);

Only a few of these are required; Phaser fills in sensible defaults for the rest. The most important question is the size, so let us start there.

Renderer type

type chooses how Phaser draws.

Value Meaning
Phaser.AUTO Use WebGL if the browser supports it, otherwise Canvas. The right default.
Phaser.WEBGL Force WebGL. Fails if it is unavailable.
Phaser.CANVAS Force the 2D Canvas API. Slower for many sprites, but works almost everywhere.
Phaser.HEADLESS No rendering at all, for server-side or automated tests.

WebGL uses the graphics card and is much faster when many objects are on screen. Always use AUTO unless you have a reason; you can read which renderer is active from game.renderer.type (Phaser.WEBGL is 2, Phaser.CANVAS is 1).

Size: game pixels versus screen pixels

width and height define the game resolution, the coordinate system your code sees. A game with width: 800, height: 450 always has x from 0 to 800, no matter how big the browser window is. How those game pixels are stretched onto the real screen is decided by the Scale Manager, covered next. Think of the game size as the size of a painting and the scale mode as the way it is framed on a wall.

A common choice is a 16:9 resolution such as 800 x 450 or 1280 x 720. Pixel-art games choose a tiny resolution such as 320 x 180 and scale it up.

The Scale Manager

The scale object controls resizing:

  • mode: Phaser.Scale.NONE: no scaling; the canvas is exactly width x height CSS pixels.
  • Phaser.Scale.FIT: scale the whole game up or down to fit the parent while keeping the aspect ratio (you may see bars on the sides).
  • Phaser.Scale.ENVELOP: scale to cover the parent, cropping the edges.
  • Phaser.Scale.RESIZE: change the game's own size to match the parent; your code must lay objects out for any size.
  • Phaser.Scale.WIDTH_CONTROLS_HEIGHT and HEIGHT_CONTROLS_WIDTH: scale one dimension and derive the other.
  • autoCenter: Phaser.Scale.CENTER_BOTH centers the canvas in the parent.

For most games FIT with CENTER_BOTH is the best start: the game looks the same everywhere, and your coordinates never change. The example below prints what the Scale Manager knows and reacts when the preview is resized.

Config values at runtime

Resize your browser window or the preview and watch "canvas on screen" change while "game size" stays at 640 x 360. That is the key idea: your logic uses the game size, the browser uses the display size.

If you use Scale.RESIZE, the game size itself changes. Positions set once in create will not move by themselves, so handle the scale resize event to re-layout, as in the code above.

Parent and canvas creation

parent is the id of an element (or the element itself). Phaser appends its canvas there. If you leave it out, the canvas is added to document.body. Use a dedicated container when the game sits inside a larger web page; the container's CSS size is what the Scale Manager fits to.

You can also pass your own <canvas> with the canvas option, but letting Phaser create one is the usual route.

Background and transparency

backgroundColor sets the color the canvas is cleared to each frame. Use a hex string ('#0f172a') or a number (0x0f172a). If you want the web page to show through, set transparent: true. You can also set a scene's camera background with this.cameras.main.setBackgroundColor(...), which is handy for scenes with different colors.

Pixel art settings

For pixel art, you want sharp square pixels, not smoothed blurry ones:

JavaScript
{
  pixelArt: true,       // nearest-neighbor texture filtering, no antialiasing
  roundPixels: true,    // sprites snap to whole pixels, no shimmering
  width: 320, height: 180,
  scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH }
}

pixelArt: true is a shortcut for turning off antialiasing and using nearest filtering. Without it, scaled-up small sprites look blurry. For smooth, high-resolution art keep it off (the default), and keep antialias on.

Frame rate: fps

By default Phaser tries to run at the display's refresh rate with requestAnimationFrame. You can ask for a target:

JavaScript
fps: { target: 60, forceSetTimeOut: false }

You should never rely on frames being exactly 16.7 ms apart; always move things using delta time (The game loop). The fps option mainly caps the rate (for example, 30 on weak devices) and controls how physics steps are scheduled.

Physics

The physics object enables engines. default: 'arcade' selects Arcade Physics, the simple and fast engine most games use, and arcade holds its settings: gravity, debug (draws collision boxes, very useful while building) and fps for the physics step. matter is the other engine, for rotating bodies and complex shapes. Physics is covered in Arcade Physics Basics. If you do not configure physics, this.physics does not exist in your scenes.

Scenes

scene takes one scene class, an array of classes, or scene config objects. The first scene in the array starts automatically; the others wait until you start them. A plain object works too, which is handy for a quick test:

JavaScript
scene: {
  preload() { /* load files */ },
  create() { /* build the world */ },
  update(time, delta) { /* every frame */ }
}

Other useful options

Option What it does
banner: false Hides the console banner that Phaser prints at startup.
title, url, version Shown in that banner.
input { keyboard: true, mouse: true, touch: true, gamepad: false } turns input devices on or off.
audio { noAudio: true } disables sound; { disableWebAudio: true } forces HTML5 audio.
seed Array of strings that seeds the random generator, so runs repeat.
render { antialias, pixelArt, roundPixels, powerPreference } renderer details.
dom { createContainer: true } lets you place real HTML elements on top of the game.
plugins Add global or scene plugins.
callbacks { preBoot(game), postBoot(game) } hook into startup.

The next example uses a plain-object scene, an input config and the seed, and logs a few values.

A minimal config with a plain scene object

With debug: true you see the green outline of the physics body: very handy while building. Remember to turn it off for the published game.

Reading the config later

Everything you pass is stored on game.config, and the scene gets quick handles: this.game (the game), this.scale (Scale Manager), this.sys (scene systems), this.cameras.main (the default camera). Use them instead of keeping your own copies of the width and height: this.scale.width always tells you the truth.

Common mistakes

  • Blurry pixel art. Add pixelArt: true.
  • Game too small on a big screen, or cut off on a phone. Use the Scale Manager with FIT.
  • this.physics is undefined. You forgot the physics config.
  • Only the first scene runs. That is by design; start others with this.scene.start('key').
  • A physics debug outline left on in the final build. Gate it with a flag such as debug: location.hash === '#debug'.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which renderer setting is the best default for most games?

    AUTO uses WebGL when available and falls back to Canvas, giving the best speed with the widest support.
  2. 2. A game has width 800 and height 450 and uses Scale.FIT. The browser window is much larger. What happens?

    FIT scales the display size and keeps the aspect ratio; the logical game size you code against does not change.
  3. 3. Which config option makes scaled-up pixel art look sharp instead of blurry?

    pixelArt: true turns off smoothing and uses nearest-neighbor filtering so each source pixel stays crisp.
  4. 4. You pass scene: [Boot, Menu, Play]. Which scene starts automatically?

    The first scene in the array starts automatically; you start the others with this.scene.start(key).
  5. 5. What does arcade: { debug: true } do?

    Debug draws body boxes and velocities. It is a development aid and should be off in the released game.

Summary

  • The game config is one object: renderer type, width/height, parent, backgroundColor, scale, physics, fps and scene.
  • Game size is your coordinate system; the Scale Manager (FIT, ENVELOP, RESIZE) decides how it maps to the screen.
  • Use Phaser.AUTO, pixelArt: true for pixel games, and debug: true only while developing.
  • The first scene in the scene array starts automatically.
  • banner, seed, input, audio and dom are small options that solve real problems.

Next: Phaser with Vite and npm