Phaser 2 to Phaser 3 Migration Guide

Phaser 3 introduces a new structure that requires refactoring key elements of Phaser 2 games. Phaser 3 introduces a more modular structure, a new event system, and an improved rendering pipeline. There isn’t much online anymore for Phaser 2 but there are developers out there who haven’t been able to take the time to port their games to Phaser 3.

---

1. Game Configuration

Phaser 2 CE:

var game = new Phaser.Game(800, 600, Phaser.AUTO, '', { preload: preload, create: create, update: update });

Phaser 3:

var config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    scene: {
        preload: preload,
        create: create,
        update: update
    }
};
var game = new Phaser.Game(config);

Key Changes:

• Phaser 3 uses a configuration object.
• Scene logic is encapsulated within the scene property.

2. Scenes

Phaser 2 used states (game.state.add), while Phaser 3 introduced scenes.

Phaser 2 CE:

game.state.add('MainState', MainState);
game.state.start('MainState');

Phaser 3:

class MainScene extends Phaser.Scene {
    constructor() {
        super({ key: 'MainScene' });
    }
    preload() {}
    create() {}
    update() {}
}
var game = new Phaser.Game({
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    scene: [MainScene]
});

Key Changes:

• Phaser.Scene replaces Phaser.State.
• Scene keys are required.

3. Loading Assets

Phaser 2 CE:

game.load.image('player', 'assets/player.png');
game.load.tilemap('level', null, mapData, Phaser.Tilemap.TILED_JSON);

Phaser 3:

this.load.image('player', 'assets/player.png'); //sprite
this.load.tilemapTiledJSON('level', 'assets/level1.json'); //tile map

//bitmap fonts:
this.cache.bitmapFont.add('retro', RetroFont.Parse(this, config)); 
this.add.bitmapText(100, 100, 'retro', 'PLAY NOW');

Key Changes:

• Loading is done within the preload function of a scene.
• this now refers to the scene instance.

4. Adding Sprites

Phaser 2 CE:

var player = game.add.sprite(100, 100, 'player');

Phaser 3:

var player = this.add.sprite(100, 100, 'player');

Key Changes:

• Use this.add.sprite instead of game.add.sprite.
• Scene context (this) must be used within scene methods.

5. Physics System

Phaser 3 introduces a revamped physics system.

Phaser 2 CE (Arcade Physics):

game.physics.startSystem(Phaser.Physics.ARCADE);
player = game.add.sprite(100, 100, 'player');
game.physics.arcade.enable(player);

Phaser 3:

this.physics.world.setBounds(0, 0, 800, 600);
var player = this.physics.add.sprite(100, 100, 'player');

Key Changes:

• Arcade Physics is now initialized automatically.
• Use this.physics.add.sprite instead of enabling physics separately.

6. Input Handling

Phaser 2 CE:

game.input.onDown.add(myFunction, this);

Phaser 3:

this.input.on('pointerdown', myFunction, this);

Key Changes:

• Input is handled using the event emitter (this.input.on).
• pointerdown replaces onDown.

7. Tweens

Phaser 2 CE:

game.add.tween(player).to({ x: 500 }, 1000, Phaser.Easing.Linear.None, true);

Phaser 3:

this.tweens.add({
    targets: player,
    x: 500,
    duration: 1000,
    ease: 'Linear'
});

Key Changes:

• this.tweens.add replaces game.add.tween.
• Tweens target objects instead of modifying them directly.

8. Camera

Phaser 2 CE:

game.camera.follow(player);

Phaser 3:

this.cameras.main.startFollow(player);

Key Changes:

• Camera operations are now handled by this.cameras.main.

9. Groups

Phaser 2 CE:

var enemies = game.add.group();
enemies.add(game.add.sprite(200, 200, 'enemy'));

Phaser 3:

var enemies = this.add.group();
enemies.add(this.add.sprite(200, 200, 'enemy'));

Key Changes:

• this.add.group replaces game.add.group.

10. Timers

Phaser 2 CE:

game.time.events.add(Phaser.Timer.SECOND * 2, myFunction, this);

Phaser 3:

this.time.delayedCall(2000, myFunction, [], this);

Key Changes:

• this.time.delayedCall replaces game.time.events.add.
• Time is specified in milliseconds.

Conclusion

Migrating from Phaser 2 CE to Phaser 3 involves transitioning to the new scene-based structure, updated physics engine, event input handling, and revamped rendering system. Understanding these key changes will make the migration smoother and take advantage of Phaser 3’s improvements.