Getting started

How the SDK works

1. Your game loads the SDK via a script tag pointing at the SDK server
2. The SDK creates a hidden iframe loading the bridge from the same server
3. The bridge makes REST/WebSocket calls to the backend API
4. Responses flow back through postMessage to the SDK
5. The backend proxies requests to external APIs (GO3, etc.)

You interact with the SDK through window.RollerzSDK — the bridge and network layer are invisible to your game code.

Installation

Add the script tag

Include the SDK script in the head of your game's HTML:

<script src="https://rollerzsdk-testing.up.railway.app/sdk"></script>

Hosting

Your game must be served over HTTP or HTTPS. Opening the HTML file directly (file://) will not work because the bridge iframe and API calls require a proper origin.

IDE autocomplete (TypeScript / IntelliSense)

For full autocomplete in VS Code and other IDEs, install the SDK as a dev dependency. You still load the script from your SDK server; the package provides types only.

npm install @rollerz/sdk --save-dev

With the package installed, RollerzSDK and window.RollerzSDK will have full IntelliSense (e.g. RollerzSDK.init, RollerzSDK.go3.placeBet, etc.).

Single source of truth for types

All SDK types live in the @rollerz/types package — it's the canonical source for everything the SDK returns or accepts (Go3BetResult, StepperSession, Currency, bet-type unions, etc.). @rollerz/sdk depends on @rollerz/types directly. If you want to reference named types in your own game code, import them from @rollerz/types. See the Types reference for the complete list.

IntelliSense limitations in VS Code

A few things to know so autocomplete actually shows up:

• Script tags inside .html files do not get autocomplete. Typing window.RollerzSDK directly inside an HTML file will not surface suggestions. Put your game logic in a .js or .ts file to get IntelliSense.
• If your project has a jsconfig.json or tsconfig.json, it must include "@rollerz/sdk" in the compilerOptions.types array:

  {
    "compilerOptions": {
      "types": ["@rollerz/sdk"]
    }
  }

Game Development

Designing the game loop

Follow the Game Design Guide to learn how to design your game around the different providers and their math models.

Initialize the SDK

Before calling any SDK methods, you must initialize with a game ID. The SDK is asynchronous — use await or .then().

const sdk = window.RollerzSDK;

// Initialize (must be before any other SDK calls)
await sdk.init('my-game-id');

Await initialization

The SDK creates a hidden iframe and waits for the bridge to be ready. Do not call any other SDK methods until init() resolves.

Launch parameters (auto-detected)

When a host platform (e.g. Rollerz) launches your game, it appends two URL parameters that the SDK reads automatically — you never touch URLSearchParams:

Parameter	Purpose	Fallback when absent
?server=	Math server URL for this launch	The provider's default (configured server-side)
?session=	Session token issued by Reelsoft	A UUID stored in sessionStorage — stable across refreshes of the same tab; minted fresh on a new tab or new launch

This means your game runs unchanged in three modes:

• Hosted launch (?server=…&session=… present) — uses the host-supplied values.
• Server-only launch (?server=… only) — uses the URL server with an auto-managed session.
• Standalone dev (no params) — uses provider defaults and a sessionStorage-backed dev session.

The host-driven values always win over any explicit openGame({ serverUrl }) argument (only relevant for the GP provider).

Develop your game

Follow the Game Building Guide to learn how to place bets, handle results, and build your game loop. You can study the Smash Game Example for a complete game integration, or use the SDK Provider Playground to exercise provider APIs interactively.

Use the references

Throughout development, refer to the API Reference and Types documentation for the full list of available methods, events, and data structures.

Test your game

When your game is ready for testing, point it at the testing environment and verify the full flow — init, open game, bet, animation, collect — against hosted servers.

Deploy

When you're ready to go live, Submit a Game to see the deployment guide.