Skip to content
ZokoGames

Log in

Game module

Game module

SDK.game tells the portal what your game is doing and lets the portal tell your game about player preferences. Every method is async except where noted.

Gameplay events#

gameplayStart(): Promise<void>
gameplayStop(): Promise<void>

Call gameplayStart() when the player is actively playing and gameplayStop() whenever that stops: pause menu, death or results screen, level select, a shop, or before an ad. The portal uses the pair to measure real playtime, which feeds your basic launch metrics.

function resume() { game.running = true; SDK.game.gameplayStart(); }
function pause() { game.running = false; SDK.game.gameplayStop(); }
document.addEventListener("visibilitychange", () => { if (document.hidden) pause(); });

Rules of thumb:

  • Do not call gameplayStart at page load. Call it when the first level is live.
  • Do not call either one every frame. Repeated calls in the same state are harmless but noisy.
  • Basic launch needs only gameplayStart. Full launch needs both, in the right places.

Loading#

loadingStart(): Promise<void>
loadingStop(): Promise<void>

Optional. Call loadingStart() as the game begins loading assets and loadingStop() when it is ready to play. The portal records loadingStop so it can separate load time from play time, and the Preview tool ticks it off. See first frame fast.

Happy moments#

happytime(): Promise<void>

Call it at moments of celebration: a boss defeated, a record broken, a level three-starred. The portal answers with a short confetti celebration over the game. Use it sparingly, a handful of times per session at most.

Completion#

reportGameCompletedPercentage(percentage: number): Promise<void>

Reports how far through the game the player is, from 0 to 100. A value outside that range, or NaN, rejects with invalidArgument. Send it when it changes meaningfully (after a level), not on every frame. The portal accepts the value; it does not change anything you can see yet.

Game context#

setGameContext(context: Record<string, string | number | boolean>): Promise<void>
clearGameContext(): Promise<void>

A flat bag of values describing what the player is doing (current mode, level, difficulty). Values must be strings, numbers or booleans; nesting is rejected with invalidArgument. Use clearGameContext() when the player returns to a menu. Like the completion percentage, the context is accepted by the portal but not yet surfaced anywhere.

await SDK.game.setGameContext({ mode: "time-trial", level: 7, hard: false });

Portal settings#

readonly settings: { disableChat: boolean; muteAudio: boolean }
addSettingsChangeListener(fn: (settings: GameSettings) => void): void
removeSettingsChangeListener(fn: (settings: GameSettings) => void): void

The portal owns these player preferences. settings returns a copy of the current values (synchronous). Apply them at start and listen for changes.

function applySettings(s) {
  audio.setMuted(s.muteAudio);
  chatPanel.hidden = s.disableChat;
}
applySettings(SDK.game.settings);
SDK.game.addSettingsChangeListener(applySettings);

If your game has chat or user-generated text, honour disableChat fully. That is a multiplayer requirement.

Rooms and invites#

For games that play together. Read the multiplayer requirements first.

readonly isInstantMultiplayer: boolean
readonly inviteParams: Record<string, string> | null
getInviteParam(key: string): string | null
updateRoom(update: { roomId?: string; isJoinable?: boolean; inviteParams?: Record<string, string> }): Promise<void>
leftRoom(): Promise<void>
inviteLink(params: Record<string, string>): Promise<string>
addJoinRoomListener(fn: (params: InviteParams) => void): void
removeJoinRoomListener(fn: (params: InviteParams) => void): void
  • isInstantMultiplayer is true when the player arrived from a "play together" entry and should go straight into a lobby instead of a menu.
  • inviteParams holds the query parameters the game page was opened with (for an invite link, the parameters you passed to inviteLink or updateRoom), or null when there were none. Use getInviteParam("room") for a single value.
  • updateRoom announces the room you are in. Call it when the player creates or joins a room and again when it changes (full, started). isJoinable: false stops the portal offering the invite. inviteParams is what a friend's join listener will receive. All values must be strings. If you omit roomId the portal generates one; ids are limited to letters, digits, _, . and - (other characters become _, 64 characters at most), and the id is always added to inviteParams as roomId. Rooms and presence need a signed-in player: for guests the call succeeds but nothing is announced.
  • leftRoom clears the room.
  • inviteLink returns the game page's URL with your parameters added as query parameters. Show it in a "copy invite link" button.
  • addJoinRoomListener fires when the player is already in your game and accepts an invite. Parse the params and move them into the room.
SDK.game.addJoinRoomListener((params) => joinRoom(params.room));

async function createRoom() {
  const room = await network.create();
  await SDK.game.updateRoom({ roomId: room.id, isJoinable: true, inviteParams: { room: room.id } });
  copyButton.onclick = async () => navigator.clipboard.writeText(await SDK.game.inviteLink({ room: room.id }));
}

if (SDK.game.inviteParams?.room) joinRoom(SDK.game.inviteParams.room);

In local mode inviteLink returns your own page URL with the parameters added as query strings, which is enough to test the join path in a second tab.

Something unclear, wrong or missing on this page? Tell us through support · Test your game in the preview tool