game-setup-and-config

What this skill does

# 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:

```js
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)

| Constant | Value | Behavior |
|---|---|---|
| `Phaser.AUTO` | `0` | WebGL if supported, else falls back to Canvas |
| `Phaser.CANVAS` | `1` | Force Canvas renderer |
| `Phaser.WEBGL` | `2` | Force WebGL -- no fallback if unsupported |
| `Phaser.HEADLESS` | `3` | No renderer -- DOM still required. For unit testing only |

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`.

```js
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:

```js
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

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

### Fixed Aspect Ratio with FIT

```js
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

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

### Transparent Canvas Over HTML

```js
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

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

const config = {
    type: Phaser.WEBGL,
    canvas: canvas,
    width: 800,
    height: 600,
    scene: MyScene
};
```

### Multiple Scenes

```js
const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    scene: [BootScene, PreloadScene, MenuScene, GameScene],
    physics: {
        default: 'arcade',
        arcade: { gravity: { y: 300 } }
    }
};
```

Only the first scene starts automatically. Others start only if they have `{ active: true }` in their scene config. See ../scenes/SKILL.md.

### Boot Callbacks

```js
const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    callbacks: {
        preBoot: function (game) {
            // Runs before Phaser boots. Game systems not yet available.
        },
        postBoot: function (game) {
            // Runs after boot. All systems ready, game loop starting.
        }
    },
    scene: MyScene
};
```

### Disabling Input Subsystems

```js
const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    input: {
        keyboard: true,
        mouse: true,
        touch: false,
        gamepad: false,
        activePointers: 1,
        windowEvents: true
    },
    disableContextMenu: true,
    scene: MyScene
};
```

## Configuration Reference

### Top-Level GameConfig Properties

| Property | Type | Default | Description |
|---|---|---|---|
| `type` | `number` | `Phaser.AUTO` (0) | Renderer: `AUTO`, `CANVAS`, `WEBGL`, or `HEADLESS` |
| `width` | `number\|string` | `1024` | Game width in pixels (or `'100%'`). Overridden by `scale.width` |
| `height` | `number\|string` | `768` | Game height in pixels (or `'100%'`). Overridden by `scale.height` |
| `zoom` | `number` | `1` | Canvas zoom multiplier. Overridden by `scale.zoom` |
| `parent` | `HTMLElement\|string\|null` | `undefined` | DOM element or `id` for canvas. `undefined` = document body. `null` = no parent |
| `canvas` | `HTMLCanvasElement` | `null` | Provide your own canvas element |
| `context` | `CanvasRenderingContext2D\|WebGLRenderingContext` | `null` | Provide your own rendering context |
| `canvasStyle` | `string` | `null` | CSS styles applied to the canvas element |
| `customEnvironment` | `boolean` | `false` | Skip feature detection for non-browser environments. `renderType` cannot be `AUTO` if `true` |
| `scene` | `SceneType\|SceneType[]` | `null` | Scene class (extends Phaser.Scene) or array of scene classes |
| `seed` | `string[]` | `[random]` | Seed for `Phaser.Math.RND` |
| `title` | `string` | `''` | Game title shown in console banner |
| `url` | `string` | `'https://phaser.io/...'` | Game URL shown in console banner |
| `version` | `string` | `''` | Game version shown in console banner |
| `autoFocus` | `boolean` | `true` | Auto-focus window on boot and mousedown |
| `stableSort` | `number\|boolean` | `-1` | `-1` = auto-detect, `0`/`false` = built-in stable sort, `1`/`true` = rely on native ES2019 sort |
| `disableContextMenu` | `boolean` | `false` | Disable right-click context menu |
| `backgroundColor` | `string\|number` | `0x000000` | Canvas background color. Accepts hex number, CSS string, or color object |
| `banner` | `boolean\|BannerConfig` | (shown) | `false` to hide console banner entirely |

### scale (Phaser.Types.Core.ScaleConfig)

| Property | Type | Default | Description |
|---|---|---|---|
| `width` | `number\|string` | `1024` | Base game width |
| `height` | `number\|string` | `768` | Base game