Plain HTML5, Three.js and PixiJS
Tällä sivulla
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.environmentis"disabled". - Render loop, clock and audio pause on
adStartedand resume on bothadFinishedandadError. - Time deltas are clamped so a long pause does not teleport anything.
-
SDK.game.settings.muteAudiois 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.