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()andloadingStop(), called from the loader'sstartandcompleteevents. - Use
Phaser.Scale.FITso the game stays legible at every required resolution. - Pack textures into atlases and compress audio to meet the initial download limit.