본문으로 건너뛰기
ZokoGames

로그인

이 페이지는 아직 번역되지 않아 영어로 표시됩니다.

Plain HTML5, Three.js and PixiJS

이 페이지의 내용

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.

이 페이지에 불분명하거나, 틀리거나, 빠진 내용이 있나요? 지원팀에 알려 주세요 · 미리보기 도구에서 게임 테스트하기

쿠키 설정

ZokoGames가 사용할 수 있는 쿠키를 선택하세요. 필수 쿠키는 사이트가 작동하는 데 꼭 필요해서 항상 켜져 있어요.

  • 로그인, 언어, 그리고 이 선택 사항에 사용돼요. 항상 켜져 있어요.

  • 최근 플레이한 게임 같은 정보를 이 기기에 기억해요.

  • 무작위 방문자 ID로 플레이 횟수와 페이지 방문을 집계해 서비스 개선에 활용해요.

  • 맞춤 광고를 허용해요. 광고는 무료 게임 운영에 쓰여요.