JavaScript SDK

Install options

The SDK can be used from npm in a bundled game, or directly from the browser bundle for plain HTML games. Use npm when your game has a build step; use the browser file for simple ZIP uploads.

npm install @qubiz/game-sdk

import { QubizSDK } from "@qubiz/game-sdk";

QubizSDK.configure({
  targetOrigin: "https://qubiz.fun",
  timeoutMs: 8000
});

<script src="https://qubiz.fun/sdk/qubiz-game-sdk.js"></script>
<script>
  QubizSDK.configure({ targetOrigin: "https://qubiz.fun" });
</script>

targetOrigin security

Always set targetOrigin in production. The SDK talks to the Qubiz host through postMessage. A specific origin prevents responses from being sent to an unexpected parent window.

Use the wildcard only for local experiments where the final host is unknown. Published games should use the production origin.

• Production: https://qubiz.fun
• Local testing: http://localhost:3000 or your current dev origin
• Avoid '*', except for very early prototypes

getContext

getContext returns the game id, player identity fields allowed by the permission policy, and the scopes currently granted by the host.

Email and avatar are privacy-sensitive and may be null when the player has not granted those scopes.

const context = await QubizSDK.getContext();

console.log(context.gameId);
console.log(context.player.id);
console.log(context.player.username);
console.log(context.grantedScopes);

SDK surface map

The browser SDK is organized into small namespaces so game code can stay close to the game loop. Top-level methods cover context, permissions, saves, scores, and analytics; namespaces cover local events, assets, scripts, debug console, rooms, progress, economy, sandbox execution, and CLI command hints.

• QubizSDK.events - local event bus for game systems, editor events, and host events.
• QubizSDK.assets - list reviewed project assets and preload images, sprites, audio, models, scripts, data, fonts, and UI files.
• QubizSDK.scripting and QubizSDK.sandbox - request isolated script execution from the host.
• QubizSDK.debug - open a developer console overlay, set the hotkey, and forward logs.
• QubizSDK.multiplayer - create, join, leave, update, and send events to realtime rooms.
• QubizSDK.cloud - save, load, and remove player data.
• QubizSDK.achievements, QubizSDK.quests, QubizSDK.economy - player progression and economy APIs.
• QubizSDK.analytics - track events directly or create reusable analytics hooks.