SDK reference
SDK v1.0 · complete public method reference.
On this page
ZUQ.leaderboard.submit(score, options = {})
Returns Promise<{id,status,reason,authoritative:false,me?}>. options.board defaults to default. score must be a finite nonnegative number. Requires verified sign-in and a live gameplayStart session. One result per session/board; replay, expiry, board ban, unavailable game and rate-limit errors reject. Bound violations resolve with status flagged and enter review.
ZUQ.leaderboard.top(options = {})
Returns Promise<{game,board,boards,sort,period,timezone,authoritative:false,note,players,total,me}>. options: board, period (daily, weekly, all-time), friends (boolean). Up to fifty players with rank, score, handle, name, avatar and you. Best accepted score per player; ties share rank. me is the current player in the same filter or null. Guests can read public boards; friends requires sign-in and includes the current player and accepted unblocked friends.
ZUQ.leaderboard.me(options = {})
Same options and rank filter as top. Returns Promise<{me}>, where me is the current rank entry or null. Requires verified sign-in.
ZUQ.init(options = {})
- Parameters
- options.parentOrigin?: string; exact HTTPS origin. Local development also accepts HTTP localhost or 127.0.0.1. Defaults to https://zuqplay.com.
- Returns
Promise<{ready:true, version:"1.0", ads:false, saves:string, gameId:string, room:string|null}> on first call. Later calls return {ready:true, version:"1.0"}.- Errors and behavior
- An invalid parent origin rejects. Outside an allowed first-party origin or the wrapper, initialization rejects. Initialize before all other methods.
const context = await ZUQ.init();
console.log(context.room);ZUQ.loadingProgress(value)
- Parameters
- value: finite number from 0 to 100.
- Returns
Promise<{progress:number}>- Errors and behavior
- Out-of-range or nonnumeric progress rejects.
await ZUQ.loadingProgress(50);ZUQ.gameReady()
- Parameters
- None. Call after loading and before the player can start.
- Returns
Promise<{tracked:boolean, test?:true}>- Errors and behavior
- Event recording failure rejects in the live wrapper.
await ZUQ.gameReady();ZUQ.gameplayStart()
- Parameters
- None. Call when active gameplay begins or resumes.
- Returns
Promise<{tracked:boolean, test?:true}>- Errors and behavior
- Event recording failure rejects in the live wrapper.
await ZUQ.gameplayStart();ZUQ.gameplayStop()
- Parameters
- None. Call when play pauses, ends or opens a menu.
- Returns
Promise<{tracked:boolean, test?:true}>- Errors and behavior
- Event recording failure rejects in the live wrapper.
await ZUQ.gameplayStop();ZUQ.happyMoment()
- Parameters
- None. Call for a win or other positive milestone.
- Returns
Promise<{tracked:boolean, test?:true}>- Errors and behavior
- Records an event only; it does not request an ad or promise a reward.
await ZUQ.happyMoment();ZUQ.saves.get()
- Parameters
- None. Saves are scoped to the game and current account or guest device.
- Returns
Promise<JSON value | null>- Errors and behavior
- Rejects if account saves are still loading or account identity changes. A missing save is null.
const save = await ZUQ.saves.get();
const level = save?.level ?? 1;ZUQ.saves.set(value)
- Parameters
- value: JSON-serializable value. Keep the complete request below 65,536 UTF-8 bytes; its envelope also takes space.
- Returns
Promise<{saved:true, cloud:boolean}>; Inspector returns {saved:true, test:true}.- Errors and behavior
- Non-JSON or oversized values, storage/network failures, account changes and concurrent live save requests can reject. Serialize saves and retry visibly.
await ZUQ.saves.set({level: 4, stars: 12});ZUQ.invite(code)
- Parameters
- code: string, 3–64 letters, digits, underscores or hyphens.
- Returns
Promise<{shared:true, notice:string}>- Errors and behavior
- Invalid codes reject. This shares a room code with the chat overlay; sending requires an eligible signed-in account and recipient.
await ZUQ.invite("ROOM_A");ZUQ.room(code)
- Parameters
- code: string, same validation as invite, or null to leave. Announces your current room to the wrapper.
- Returns
Promise<{shared:true, notice:string}>- Errors and behavior
- Does not create a game server or provide matchmaking. Read an incoming code from init().room. Invalid codes reject.
await ZUQ.room("ROOM_A");ZUQ.track(event, data = {})
- Parameters
- event: 1–40 characters, starts with a letter, then letters, digits, underscores, periods or hyphens. data: JSON object; ordinary event data is discarded. The reserved stars event accepts {value:0..3} once per active run for challenge progress.
- Returns
Promise<{tracked:true}>; Inspector returns {tracked:false, test:true}.- Errors and behavior
- Invalid names, unavailable live version, network failure or rate limits reject. Never send personal data.
await ZUQ.track("level_complete", {level: 4});ZUQ.ads.showInterstitial()
- Parameters
- None. Reserved for future ads integration.
- Returns
Promise<{shown:false}>- Errors and behavior
- Currently a safe no-op. Initialization and transport errors can still reject.
const ad = await ZUQ.ads.showInterstitial();
// Resume play regardless of ad.shown.ZUQ.ads.showRewarded()
- Parameters
- None. Reserved for a future rewarded-ad integration.
- Returns
Promise<{shown:false}>- Errors and behavior
- No ad is shown and no reward completion is reported. Do not grant ad-earned rewards for shown:false.
const ad = await ZUQ.ads.showRewarded();
if (ad.shown) grantReward();ZUQ.ads.requestAd()
- Parameters
- None. Reserved generic ad request.
- Returns
Promise<{shown:false}>- Errors and behavior
- Currently a safe no-op. No provider, payment or monetization is enabled.
await ZUQ.ads.requestAd();