game-setup-and-config

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) new Phaser.Game(config) -- parses config into a Phaser.Core.Config instance. Creates global managers: AnimationManager , TextureManager , CacheManager , InputManager , SceneManager , ScaleManager , SoundManager , TimeStep , PluginManager . Waits for DOMContentLoaded , then calls boot() . boot() creates the renderer ( CreateRenderer ), adds the canvas to the DOM ( AddToDOM ), prints the debug header, emits BOOT . Once textures are ready ( TextureManager emits READY ), emits READY then calls start() . 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 . 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 , scene : MyScene }; Multiple Scenes 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 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 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 |