qubiz
Back to all docs
Methods and responses

SDK API Reference

Complete method reference for the browser SDK: context, permissions, events, assets, scripts, debug, multiplayer, cloud saves, progress, economy, scores, and analytics.

apimethodsreferencepostmessage

Method summary

All SDK methods return promises. Host responses include status strings so games can show UI, retry, or continue without the feature.

  • getContext(): returns gameId, player fields, and grantedScopes.
  • requestPermissions(scopes): asks the host to evaluate permission scopes.
  • saveData(key, value): saves bounded data for the current player and game.
  • loadData(key): loads a bounded save payload for the current player and game.
  • deleteData(key): removes a save key.
  • submitScore(leaderboard, score): submits a numeric score to the current game leaderboard.
  • trackEvent(event): sends a creator analytics event.
  • events.on/once/off/emit: local game-frame event bus.
  • assets.list(query): asks the host for reviewed project assets.
  • assets.preload(assets): preloads asset URLs in the game frame.
  • scripting.run(input) and sandbox.run(input): request isolated script execution.
  • debug.setHotkey/show/hide/toggle/log/info/warn/error: developer console controls.
  • multiplayer.createRoom/joinRoom/leaveRoom/sendEvent/updateState: realtime room APIs.
  • cloud.save/load/remove: saveData/loadData/deleteData aliases.
  • achievements.unlock(input): unlock a game-specific achievement.
  • quests.update(input): write quest progress.
  • economy.getWallet/transact: read balances and record currency/item transactions.
  • analytics.track/hook: track analytics directly or create reusable event hooks.
  • cli.command(action, args): produce Qubiz CLI command strings.

Status values

SDK write methods return a status. Treat anything other than granted as a soft failure and keep the game playable.

  • granted - the host accepted the operation.
  • denied - the permission or payload was rejected.
  • prompt_required - the user must be asked before the operation can continue.
  • unavailable - Firebase, login, or the host bridge is unavailable.
  • timeout - the host did not respond before timeoutMs.
  • error - the host returned an unexpected failure.

Host bridge message types

The browser bundle wraps postMessage for you, but advanced developers can still reason about the host bridge. The game sends source=nexa-game-sdk with an id, type, and params. The host replies with source=nexa-host, the same id, ok, result, and optional error.

  • getContext - params are empty.
  • requestPermissions - params.scopes is a list of permission strings.
  • saveData - params.key is a short string and params.value is JSON-like data.
  • loadData and deleteData - params.key is a short string.
  • submitScore - params.leaderboard is a string and params.score is numeric.
  • trackEvent - params contains name, stage, source, value, and metadata.
  • listAssets - params can contain kind, tags, projectId, and includeMarketplace.
  • runScript - params can contain scriptId, source, args, timeoutMs, and permissions.
  • debugLog - params contain level, message, and optional data.
  • createRoom, joinRoom, leaveRoom, sendRoomEvent, updateRoomState - room lifecycle and event payloads.
  • unlockAchievement and updateQuest - progress ids and optional metadata.
  • getWallet and economyTransaction - wallet reads and economy mutations.