Gå til indhold
ZokoGames

Log ind

Denne side er ikke oversat endnu og vises på engelsk.

Plain HTML5, Three.js and PixiJS

På denne side

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.

Er noget uklart, forkert eller mangler på denne side? Skriv til os via support · Test dit spil i preview-værktøjet

Cookieindstillinger

Vælg, hvilke cookies ZokoGames må bruge. Nødvendige cookies er altid slået til, fordi sitet ikke kan fungere uden dem.

  • Login, sprog og disse valg. Altid slået til.

  • Husker ting som dine senest spillede spil på denne enhed.

  • Tæller spil og sidebesøg med et tilfældigt besøgs-id, så vi kan forbedre sitet.

  • Tillader personlige annoncer, som betaler for de gratis spil.