Hoppa till innehållet
ZokoGames

Logga in

Den här sidan är inte översatt ännu och visas på engelska.

Plain HTML5, Three.js and PixiJS

På den här sidan

Plain HTML5, Three.js and PixiJS

Rendering libraries need no wrapper. The browser SDK is already the integration; what you add is a few lines that connect it to your render loop and audio. The same pattern works for Three.js, PixiJS, Babylon.js, p5.js, Kaboom and a bare <canvas>.

1. Load the SDK first#

Put the script before your bundle so window.ZokoGames exists when your code runs.

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

With a bundler set the public base to a relative path (base: "./" in Vite) so every asset URL is relative. See technical requirements. For TypeScript, copy src/zoko-sdk.d.ts from the html5-vite-ts starter kit.

2. A small adapter#

Wrap the SDK once so the game also runs when it is disabled, and so one failing call never breaks a frame.

const SDK = window.ZokoGames?.SDK;
let online = false;

export async function startPlatform() {
  if (!SDK) return;
  await SDK.init();
  online = SDK.environment !== "disabled";
}

export function call(fn) {
  if (!online) return Promise.resolve(null);
  return Promise.resolve().then(fn).catch((e) => { console.warn("sdk", e.code); return null; });
}

3. Pause, mute and resume around ads#

Pause what you own: the render loop, your clock, physics and audio. The loop must keep running only if it is a cheap "paused" screen.

import * as THREE from "three";

const renderer = new THREE.WebGLRenderer({ canvas });
const clock = new THREE.Clock();
let paused = false;

renderer.setAnimationLoop(() => {
  if (paused) return;
  const dt = Math.min(clock.getDelta(), 0.1);
  world.update(dt);
  renderer.render(scene, camera);
});

function setPaused(p) {
  paused = p;
  if (!p) clock.getDelta(); // drop the time spent paused
  listener.setMasterVolume(p ? 0 : 1);
}

export function showMidgame() {
  return call(() => SDK.ad.requestAd("midgame", {
    adStarted: () => { setPaused(true); call(() => SDK.game.gameplayStop()); },
    adFinished: () => { setPaused(false); call(() => SDK.game.gameplayStart()); },
    adError: () => { setPaused(false); },
  }));
}
import { Application, Ticker } from "pixi.js";

const app = new Application();
await app.init({ resizeTo: window, resolution: Math.min(devicePixelRatio, 2), autoDensity: true });
document.body.append(app.canvas);

function setPaused(p) {
  app.ticker[p ? "stop" : "start"]();
  sound.muted = p;            // your audio library
}

export function showMidgame() {
  return call(() => SDK.ad.requestAd("midgame", {
    adStarted: () => { setPaused(true); call(() => SDK.game.gameplayStop()); },
    adFinished: () => { setPaused(false); call(() => SDK.game.gameplayStart()); },
    adError: () => { setPaused(false); },
  }));
}
let last = 0, running = true;
function frame(t) {
  if (running) {
    update(Math.min((t - last) / 1000, 0.1));
    draw();
  }
  last = t;
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);

export function showMidgame() {
  return call(() => SDK.ad.requestAd("midgame", {
    adStarted: () => { running = false; audio.suspend(); },
    adFinished: () => { running = true; audio.resume(); canvas.focus(); },
    adError: () => { running = true; audio.resume(); },
  }));
}

4. Settings, visibility and gameplay events#

await startPlatform();
call(() => SDK.game.loadingStart());
await loadAssets();
call(() => SDK.game.loadingStop());

const apply = (s) => audio.setMuted(s.muteAudio);
if (online) {
  apply(SDK.game.settings);
  SDK.game.addSettingsChangeListener(apply);
}

document.addEventListener("visibilitychange", () => {
  if (document.hidden) { setPaused(true); call(() => SDK.game.gameplayStop()); }
});

Call gameplayStart() when the player first controls the game, not at page load.

5. Sizing#

The game lives in a frame of unknown size that changes with fullscreen and rotation. Size the canvas from the window, not from constants:

function resize() {
  const dpr = Math.min(window.devicePixelRatio, SDK?.user?.systemInfo?.device?.type === "mobile" ? 1 : 2);
  renderer.setPixelRatio(dpr);              // Three.js; PixiJS uses the `resolution` option
  renderer.setSize(innerWidth, innerHeight, false);
  camera.aspect = innerWidth / innerHeight;
  camera.updateProjectionMatrix();
}
addEventListener("resize", resize);
resize();

Read SDK.user.systemInfo only after init() and only when the SDK is not disabled. Details on size caps are in optimisation tips and mobile guide.

Checklist for library games#

  • SDK script loaded before the game script and every path relative.
  • Game runs when SDK.environment is "disabled".
  • Render loop, clock and audio pause on adStarted and resume on both adFinished and adError.
  • Time deltas are clamped so a long pause does not teleport anything.
  • SDK.game.settings.muteAudio is applied at start and on change.
  • Canvas resizes with the window and caps devicePixelRatio.
  • Textures and geometry are disposed when a level unloads (texture.dispose() in Three.js, destroy() in PixiJS).
  • Tested in the Preview tool.

Är något oklart, fel eller saknas på den här sidan? Hör av dig via support · Testa ditt spel i förhandsvisningsverktyget

Cookieinställningar

Välj vilka cookies ZokoGames får använda. Nödvändiga cookies är alltid på, eftersom webbplatsen inte fungerar utan dem.

  • Inloggning, språk och de här valen. Alltid på.

  • Kommer ihåg saker som dina senast spelade spel på den här enheten.

  • Räknar spelomgångar och sidbesök med ett slumpmässigt besökar-id så att vi kan förbättra sidan.

  • Tillåter personanpassade annonser, som betalar för de gratis spelen.