Aller au contenu
ZokoGames

Se connecter

Cette page n'est pas encore traduite et s'affiche en anglais.

Plain HTML5, Three.js and PixiJS

Sur cette page

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.

Quelque chose d'obscur, d'erroné ou de manquant sur cette page ? Dites-le-nous via le support · Testez votre jeu dans l'outil d'aperçu

Paramètres des cookies

Choisissez les cookies que ZokoGames peut utiliser. Les cookies nécessaires sont toujours actifs, car le site ne peut pas fonctionner sans eux.

  • Connexion, langue et ces choix. Toujours actifs.

  • Mémorise des éléments comme vos jeux récemment joués sur cet appareil.

  • Compte les parties et les visites de pages avec un identifiant de visiteur aléatoire pour nous aider à nous améliorer.

  • Autorise les publicités personnalisées, qui financent les jeux gratuits.