Skip to content
ZokoGames

Log in

Phaser

Phaser

Phaser games run in the browser, so you can use the JavaScript SDK directly, or add the small ZokoGames Phaser plugin that pauses the loop and the sound around ads for you. The calls on this page are the same as in the SDK reference. For a complete project to copy, use the phaser starter kit.

<script src="https://sdk.zokogames.com/zokogames-sdk-v1.js"></script>
<script src="game.js"></script>

The plugin#

The plugin is one TypeScript file (ZokoPlugin.ts, with types.ts) that lives in your project: the Phaser starter kit ships both under src/zoko/. It targets Phaser 3.80 and later and has not yet been compiled against every Phaser release.

import Phaser from "phaser";
import { ZokoPlugin } from "./zoko/ZokoPlugin";

new Phaser.Game({
  type: Phaser.AUTO,
  parent: "game",
  scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH, width: 1280, height: 720 },
  plugins: {
    global: [{ key: "ZokoPlugin", plugin: ZokoPlugin, start: true, mapping: "zoko", data: { syncMute: true } }],
  },
  scene: [Boot, Menu, Play],
});

class Play extends Phaser.Scene {
  async create() {
    await this.zoko.ready();                                   // loads the SDK script if missing, then SDK.init()
    await this.zoko.sdk.game.gameplayStart();
    const { finished, error } = await this.zoko.requestAd("rewarded");
    if (finished) this.grantReward();
    this.zoko.events.on("settingsChange", (s) => console.log(s.muteAudio));
  }
}
Member Behaviour
ready() Loads zokogames-sdk-v1.js if window.ZokoGames is missing (unless the loadScript: false option is set), then calls SDK.init(). Rejects with { code: "sdkNotLoaded" } when the script cannot load. Safe to call repeatedly.
sdk The raw SDK, typed. Throws sdkNotInitialized before ready() has resolved. Check sdk.environment !== "disabled" before using it.
requestAd(type) Pauses sound, mutes and puts the main loop to sleep from adStarted until adFinished or adError, then restores both. Resolves { finished: boolean, error? } and never rejects for ad problems.
isAdPlaying true while an ad is on screen.
events Emits adStarted, adFinished, adError(error) and settingsChange(settings).
syncMute option Default true: mirrors the portal's muteAudio onto game.sound.mute.

Every other module (banner, game, user, data, analytics) is the raw SDK through plugin.sdk.

Boot without the plugin#

Initialise before you create the Phaser.Game, so settings are known when the first scene starts.

const SDK = window.ZokoGames.SDK;
async function main() {
  await SDK.init();
  new Phaser.Game({
    type: Phaser.AUTO,
    parent: "game",
    scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH, width: 1280, height: 720 },
    scene: [Boot, Menu, Play],
  });
}
main();

Mapping#

Phaser needs no renaming; the module names are the same. The helpers below show where each call fits in a scene.

Module In a Phaser game
SDK.ad Call from a scene after pausing physics and sound.
SDK.banner Containers are DOM elements outside the canvas (a div next to it), not game objects.
SDK.game gameplayStart when the play scene begins, gameplayStop on pause, game over and shutdown.
SDK.user Read once in Boot and keep in registry.
SDK.data Replaces localStorage for saves.

Examples#

Ads#

function showAd(scene, type) {
  return SDK.ad.requestAd(type, {
    adStarted: () => { scene.scene.pause(); scene.sound.mute = true; },
    adFinished: () => { scene.sound.mute = SDK.game.settings.muteAudio; scene.scene.resume(); },
    adError: () => { scene.sound.mute = SDK.game.settings.muteAudio; scene.scene.resume(); },
  });
}

Calling scene.scene.pause() inside adStarted pauses that scene's update loop and tweens. If other scenes run in parallel, pause them too.

Banners#

<div id="game"></div>
<div id="menu-banner" style="width:728px;height:90px;margin:8px auto"></div>
class Menu extends Phaser.Scene {
  create() {
    SDK.banner.requestBanner({ id: "menu-banner", width: 728, height: 90 }).catch(() => {});
    this.events.once("shutdown", () => SDK.banner.clearAllBanners());
  }
}

Game events#

class Play extends Phaser.Scene {
  create() {
    SDK.game.gameplayStart();
    this.events.once("shutdown", () => SDK.game.gameplayStop());
    this.game.events.on("hidden", () => SDK.game.gameplayStop());
    this.game.events.on("visible", () => SDK.game.gameplayStart());
  }
}

Settings:

const apply = (s) => { game.sound.mute = s.muteAudio; };
apply(SDK.game.settings);
SDK.game.addSettingsChangeListener(apply);

User#

class Boot extends Phaser.Scene {
  async create() {
    const user = await SDK.user.getUser();
    this.registry.set("user", user);
    this.scene.start("Menu");
  }
}

Data#

const best = Number(SDK.data.getItem("best") ?? "0");
function onGameOver(score) {
  if (score > best) SDK.data.setItem("best", String(score));
}

Tips#

  • Keep Phaser's own loader behind SDK.game.loadingStart() and loadingStop(), called from the loader's start and complete events.
  • Use Phaser.Scale.FIT so the game stays legible at every required resolution.
  • Pack textures into atlases and compress audio to meet the initial download limit.

Something unclear, wrong or missing on this page? Tell us through support · Test your game in the preview tool