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
gameplayStartat 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): voidThe 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): voidisInstantMultiplayeris true when the player arrived from a "play together" entry and should go straight into a lobby instead of a menu.inviteParamsholds the query parameters the game page was opened with (for an invite link, the parameters you passed toinviteLinkorupdateRoom), ornullwhen there were none. UsegetInviteParam("room")for a single value.updateRoomannounces the room you are in. Call it when the player creates or joins a room and again when it changes (full, started).isJoinable: falsestops the portal offering the invite.inviteParamsis what a friend's join listener will receive. All values must be strings. If you omitroomIdthe portal generates one; ids are limited to letters, digits,_,.and-(other characters become_, 64 characters at most), and the id is always added toinviteParamsasroomId. Rooms and presence need a signed-in player: for guests the call succeeds but nothing is announced.leftRoomclears the room.inviteLinkreturns the game page's URL with your parameters added as query parameters. Show it in a "copy invite link" button.addJoinRoomListenerfires 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.