game-setup-and-config

# 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 height | | `zoom` | `number` | `1` | Zoom multiplier. Use constants: `NO_ZOOM` (1), `ZOOM_2X` (2), `ZOOM_4X` (4), `MAX_ZOOM` (-1) | | `parent` | `HTMLElement\|string` | `undefined` | DOM parent for the canvas | | `mode` | `number` | `Phaser.Scale.NONE` (0) | Scale mode (see table below) | | `expandParent` | `boolean` | `true` | Allow adjusting parent CSS height to 100% | | `autoRound` | `boolean` | `false` | Round display/style sizes for performance | | `autoCenter` | `number` | `NO_CENTER` (0) | Canvas centering mode (see table below) | | `resizeInterval` | `number` | `500` | Milliseconds between browser size checks | | `fullscreenTarget` | `HTMLElement\|string` | `null` | Element for fullscreen mode | | `min` | `{width, height}` | `{0, 0}` | Minimum canvas dimensions | | `max` | `{width, height}` | `{0, 0}` | Maximum canvas dimensions (0 = no limit) | | `snap` | `{width, height}` | `{0, 0}` | Snap canvas size to multiples | ### Scale Modes (src/scale/const/SCALE_MODE_CONST.js) | Constant | Value | Behavior | |---|---|---| | `Phaser.Scale.NONE` | `0` | No scaling. Canvas stays at config size | | `Phaser.Scale.WIDTH_CONTROLS_HEIGHT` | `1` | Height adjusts based on width | | `Phaser.Scale.HEIGHT_CONTROLS_WIDTH` | `2` | Width adjusts based on height | | `Phaser.Scale.FIT` | `3` | Fit inside parent keeping aspect ratio (letterboxing) | | `Phaser.Scale.ENVELOP` | `4` | Cover parent keeping aspect ratio (may overflow) | | `Phaser.Scale.RESIZE` | `5` | Canvas resizes to fill parent, ignoring aspect ratio | | `Phaser.Scale.EXPAND` | `6` | Like RESIZE for visible area + FIT for canvas scale | ### Center Modes (src/scale/const/CENTER_CONST.js) | Constant | Value | |---|---| | `Phaser.Scale.NO_CENTER` | `0` | | `Phaser.Scale.CENTER_BOTH` | `1` | | `Phaser.Scale.CENTER_HORIZONTALLY` | `2` | | `Phaser.Scale.CENTER_VERTICALLY` | `3` | ### Zoom Constants (src/scale/const/ZOOM_CONST.js) | Constant | Value | Behavior | |---|---|---| | `Phaser.Scale.NO_ZOOM` | `1` | No zoom | | `Phaser.Scale.ZOOM_2X` | `2` | 2x zoom | | `Phaser.Scale.ZOOM_4X` | `4` | 4x zoom | | `Phaser.Scale.MAX_ZOOM` | `-1` | Max integer zoom that fits in parent | ### render (Phaser.Types.Core.RenderConfig) These can be set at the top level OR nested under `render`. The `render` sub-object takes priority. | Property | Type | Default | Description |