Build 2D games with Phaser 3 framework. Covers scene lifecycle, sprites, physics (Arcade/Matter), tilemaps, animations, input handling, and game architecture. Trigger: "create phaser game", "add phaser scene", "phaser sprite", "phaser physics", "game development with phaser".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Build 2D games with Phaser 3 framework. Covers scene lifecycle, sprites, physics (Arcade/Matter), tilemaps, animations, input handling, and game architecture. Trigger: "create phaser game", "add phaser scene", "phaser sprite", "phaser physics", "game development with phaser".
Phaser Game Development
Build 2D browser games using Phaser 3's scene-based architecture and physics systems.
Spritesheet loading is fragile—a few pixels off causes silent corruption that compounds into broken visuals. The reference file contains the mandatory inspection protocol.
Quick rules (details in reference):
Measure the asset before writing loader code—never guess frame dimensions
Character sprites use SQUARE frames: If you calculate frameWidth=56, try 56 for height first
Different animations have different frame sizes: A run cycle needs wider frames than idle; an attack needs extra width for weapon swing. Measure EACH spritesheet independently
Check for spacing: Gaps between frames require spacing: N in loader config
classGameSceneextendsPhaser.Scene {
init(data) { } // Receive data from previous scenepreload() { } // Load assets (runs before create)create() { } // Set up game objects, physics, inputupdate(time, delta) { } // Game loop, use delta for frame-rate independence
}
Frame-Rate Independent Movement
// CORRECT: scales with frame ratethis.player.x += this.speed * (delta / 1000);
// WRONG: varies with frame ratethis.player.x += this.speed;
Viewport Scaling
CRITICAL: Use Phaser's Scale Manager for ALL viewport scaling. This is the PRIMARY and ONLY correct approach.
Why Phaser Scale Manager?
Phaser's Scale Manager handles:
Responsive viewport sizing
Aspect ratio preservation
Device pixel ratio (DPR) handling
Window resize events
Canvas scaling and centering
Input coordinate transformation
Manual JavaScript/CSS scaling is an anti-pattern that breaks Phaser's coordinate system, input handling, and physics calculations.
Scale Manager Configuration
The Scale Manager is configured in your game config's scale property:
constconfig: Phaser.Types.Core.GameConfig = {
type: Phaser.AUTO,
width: 800, // Base game widthheight: 600, // Base game heightscale: {
mode: Phaser.Scale.FIT, // Primary scaling modeautoCenter: Phaser.Scale.CENTER_BOTH, // Center the game canvasparent: 'game-container', // Optional: parent DOM elementwidth: 800, // Base width (can differ from top-level)height: 600, // Base height (can differ from top-level)min: { width: 400, height: 300 }, // Optional: minimum sizemax: { width: 1920, height: 1080 }, // Optional: maximum size
},
// ... rest of config
};
Common Scaling Modes
Mode
Description
Use When
Phaser.Scale.FIT
Scales to fit viewport, maintains aspect ratio, may show letterboxing
Most common - Games that need to work on all screen sizes
Phaser.Scale.RESIZE
Game resizes to match viewport exactly, may distort aspect ratio
Responsive layouts that adapt to any size
Phaser.Scale.WIDTH_CONTROLS_HEIGHT
Width matches viewport, height calculated to maintain aspect ratio
Fixed-width responsive games
Phaser.Scale.HEIGHT_CONTROLS_WIDTH
Height matches viewport, width calculated to maintain aspect ratio
Fixed-height responsive games
Phaser.Scale.NONE
No scaling, canvas stays at base size
Desktop-only games, fixed-size games
Scaling for 70-80% Viewport Usage
To make the game fill 70-80% of the viewport while maintaining aspect ratio:
constconfig: Phaser.Types.Core.GameConfig = {
type: Phaser.AUTO,
width: 800,
height: 600,
scale: {
mode: Phaser.Scale.FIT,
autoCenter: Phaser.Scale.CENTER_BOTH,
// Calculate target size as percentage of viewport// Phaser will automatically scale to fit while maintaining aspect ratio
},
// ... rest of config
};
// In your scene, you can also adjust dynamically:this.scale.setGameSize(
Math.floor(window.innerWidth * 0.75), // 75% of viewport widthMath.floor(window.innerHeight * 0.75) // 75% of viewport height
);
Dynamic Resize Handling
Phaser automatically handles window resize events when using Scale Manager. To respond to resize:
this.scale.on('resize', (gameSize: Phaser.Structs.Size) => {
// Game has been resized// gameSize.width and gameSize.height are the new dimensions// Adjust camera, UI, or game elements as needed
});
Accessing Scale Information
// In any scene:const scaleManager = this.scale;
// Get current game size (after scaling)const gameWidth = this.scale.gameSize.width;
const gameHeight = this.scale.gameSize.height;
// Get display size (actual canvas size)const displayWidth = this.scale.displaySize.width;
const displayHeight = this.scale.displaySize.height;
// Get scale factorconst scaleX = this.scale.displaySize.width / this.scale.gameSize.width;
const scaleY = this.scale.displaySize.height / this.scale.gameSize.height;
