Phaser

Engine guide

Phaser

2D framework with arcade + matter physics

Phaser 3 maps cleanly onto the Pixlland lifecycle: scenes are where you call SDK events. Boot the SDK before new Phaser.Game, then fire gameplay + ad hooks from scene callbacks.

1. Include + boot

<script src="https://pixlland.com/sdk/v1/pixlland.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/phaser@3/dist/phaser.min.js"></script>
<script>
  (async () => {
    await window.PixllandSDK.init();
    new Phaser.Game({
      type: Phaser.AUTO,
      width: 1280,
      height: 720,
      scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
      scene: [BootScene, MenuScene, GameScene],
    });
  })();
</script>

2. Loading progress → BootScene

class BootScene extends Phaser.Scene {
  constructor() { super('Boot'); }
  preload() {
    this.load.on('progress', (v) => {
      window.PixllandSDK.gameLoadingProgress(v);
    });
    this.load.image('hero', 'assets/hero.png');
    // …more assets
  }
  create() {
    window.PixllandSDK.gameLoadingFinished();
    this.scene.start('Menu');
  }
}

3. Gameplay flags → GameScene

class GameScene extends Phaser.Scene {
  constructor() { super('Game'); }
  create() {
    window.PixllandSDK.gameplayStart();
    this.events.once('shutdown', () => {
      window.PixllandSDK.gameplayStop();
    });
  }
  update(time, delta) {
    // delta is ms — SDK wants seconds
    window.PixllandSDK.happyTime(delta / 1000);
  }
}

The shutdown event fires when the scene is replaced, restarted, or stopped — perfect pair for gameplayStop.

4. Ad break between rounds

async onLevelComplete(levelIndex) {
  window.PixllandSDK.gameplayStop();
  if (levelIndex > 0 && levelIndex % 3 === 0) {
    await window.PixllandSDK.commercialBreak();
  }
  this.scene.start('Game', { level: levelIndex + 1 });
}

5. Save progress

Keep a save helper next to your registry so any scene can persist without duplicating the serialisation logic:

function saveRegistry(scene) {
  const data = scene.registry.getAll();
  return window.PixllandSDK.data.set('registry', data);
}
async function loadRegistry(scene) {
  const data = await window.PixllandSDK.data.get('registry');
  if (data) scene.registry.set(data);
}

Common pitfalls

• Calling happyTime during scene preloads. It is meant for active gameplay only. Gate it on a scene-local isPlaying flag.
• Restarting a scene while a commercial break is pending. Await the ad promise before calling scene.restart() so the portal does not see a gameplayStart overlap error.

Also see Vanilla HTML5 for the plain-JS version of every pattern above.