name: game-setup-and-config

description: "Use this skill when creating a new Phaser 4 game instance or configuring GameConfig options. Covers renderer selection, canvas setup, scaling, pixel art, FPS settings, boot sequence, and all config sub-objects. Triggers on: new Phaser.Game, GameConfig, game setup, renderer, pixel art, FPS."

Game Setup and Config

How to create a Phaser.Game instance with the right GameConfig options for renderer, scaling, pixel art, FPS, and canvas placement.

Key source paths: src/core/Game.js, src/core/Config.js, src/core/typedefs/GameConfig.js, src/const.js, src/scale/const/

Related skills: ../scenes/SKILL.md, ../loading-assets/SKILL.md, ../scale-and-responsive/SKILL.md

Quick Start

The simplest possible Phaser 4 game -- a single scene with the default 1024×768 canvas:

class MyScene extends Phaser.Scene {
    preload() {
        this.load.image('logo', 'assets/logo.png');
    }

    create() {
        this.add.image(400, 300, 'logo');
    }
}

const config = {
    type: Phaser.AUTO,
    scene: MyScene
};

const game = new Phaser.Game(config);

new Phaser.Game(config) triggers the entire boot sequence: config parsing (Config), renderer creation, DOM insertion, and the game loop (TimeStep). The game waits for DOMContentLoaded before booting.

Core Concepts

Boot Sequence (src/core/Game.js)

1. new Phaser.Game(config) -- parses config into a Phaser.Core.Config instance.
2. Creates global managers: AnimationManager, TextureManager, CacheManager, InputManager, SceneManager, ScaleManager, SoundManager, TimeStep, PluginManager.
3. Waits for DOMContentLoaded, then calls boot().
4. boot() creates the renderer (CreateRenderer), adds the canvas to the DOM (AddToDOM), prints the debug header, emits BOOT.
5. Once textures are ready (TextureManager emits READY), emits READY then calls start().
6. start() begins the TimeStep loop, sets up the VisibilityHandler, calls config.postBoot.

Config Parsing (src/core/Config.js)

The Config constructor reads a flat GameConfig object and resolves defaults. Some properties can be specified at top level OR nested inside sub-objects (e.g., width can be top-level or under scale.width). The scale sub-object takes priority when both are present.

Render properties can likewise be top-level shortcuts (e.g., pixelArt: true) or nested under render.

Renderer Constants (src/const.js)

Set via config.type. Default is Phaser.AUTO.

Common Patterns

Pixel Art Game

When pixelArt is true, Config automatically sets antialias: false, antialiasGL: false, and roundPixels: true.

const config = {
    type: Phaser.AUTO,
    width: 320,
    height: 240,
    pixelArt: true,
    scale: {
        mode: Phaser.Scale.FIT,
        autoCenter: Phaser.Scale.CENTER_BOTH,
        zoom: Phaser.Scale.ZOOM_2X
    },
    scene: MyScene
};

Smooth Pixel Art (WebGL only)

Preserves blocky pixels but smooths edges between them when scaled up:

const config = {
    type: Phaser.WEBGL,
    width: 320,
    height: 240,
    smoothPixelArt: true,
    scene: MyScene
};

When smoothPixelArt is true, Config sets antialias: true, antialiasGL: true, and pixelArt: false.

Full-Window Responsive Game

const config = {
    type: Phaser.AUTO,
    scale: {
        mode: Phaser.Scale.RESIZE,
        parent: 'game-container',
        width: '100%',
        height: '100%'
    },
    scene: MyScene
};

Fixed Aspect Ratio with FIT

const config = {
    type: Phaser.AUTO,
    scale: {
        mode: Phaser.Scale.FIT,
        parent: 'game-container',
        autoCenter: Phaser.Scale.CENTER_BOTH,
        width: 1280,
        height: 720,
        min: { width: 640, height: 360 },
        max: { width: 1920, height: 1080 }
    },
    backgroundColor: '#2d2d2d',
    scene: MyScene
};

Custom FPS Limit

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    fps: {
        target: 60,
        limit: 30,
        forceSetTimeOut: false,
        smoothStep: true
    },
    scene: MyScene
};

Transparent Canvas Over HTML

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    transparent: true,
    parent: 'game-container',
    scene: MyScene
};

When transparent is true, backgroundColor is forced to 0x000000 with alpha 0.

Pre-existing Canvas Element

const canvas = document.getElementById('my-canvas');

const config = {
    type: Phaser.WEBGL,
    canvas: canvas,
    width: 800,
    height: 600,
    s