Game building guide

This guide walks you through building a game with the Rollerz SDK from scratch. It covers everything from installation to production — follow the steps in order for a complete walkthrough.

For a game example, see the Smash Game walkthrough. You can also take a look at the Developer Playground and its implementation.

Step 1: Install and initialize

Set up your project

Use whatever stack you prefer — React, Vue, Phaser, plain HTML, or anything else that runs in a browser. The only requirement is a served HTML page.

Create your project folder and serve it locally with any HTTP server:

bash

npx serve -p 5500
# or use Vite, webpack-dev-server, etc.

WARNING

The game must be served over HTTP/HTTPS. Opening the HTML file directly (file://) will not work.

Add the SDK script tag

Add the Rollerz SDK script to the <head> of your main HTML file:

Add to <head> in index.html:

html

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

TypeScript support

For autocomplete and type safety, install the SDK types as a dev dependency:

bash

npm install @rollerz/sdk --save-dev

This gives you full IntelliSense on window.RollerzSDK without changing how the SDK is loaded at runtime. All SDK types (Go3BetResult, StepperSession, Currency, bet-type unions, etc.) are defined in the @rollerz/types package — that's the single source of truth. If you want to reference named types in your own code you can import them from @rollerz/types. See the Types reference for the full list.

VS Code caveats: autocomplete only works in .js / .ts files — not inside <script> tags in .html. If your project has a jsconfig.json or tsconfig.json, add "@rollerz/sdk" to compilerOptions.types.

Initialize the SDK

Before calling any SDK methods, initialize with your game ID:

javascript

const sdk = window.RollerzSDK;

await sdk.init('my-game-id', {
  enableLogging: true, // show SDK logs in the browser console
});

Step 2: Design your game around a provider

The Rollerz SDK connects your game to a provider — a backend math engine (RGS) that determines bet outcomes. Each provider returns different data in its bet result, and your game's visuals and mechanics should be designed around that data.

Provider	Access	Best for
GO3	`sdk.go3`	Instant-reveal games (scratch cards, smash games, slot-style)
Stepper	`sdk.stepper`	Crash / climb / risk-reward games
Rippin Rumble	`sdk.rippinrumble`	Card-draw, pack-opening, collection-style games

Pick a provider, then design your game's theme and animations around the fields it returns. See Designing around providers for game ideas and design tips, and Types for the full bet result type definitions.

Step 3: Integrate the RGS flow

Every provider follows the same core flow: open → bet → result → settle. However, the Stepper provider adds a multi-step loop between bet and settle — see the Stepper tab below for details.

Stepper flow is different

For Go3 and Rippin Rumble, the round resolves in a single placeBet → collect sequence. For Stepper, the round is interactive: after placeBet, the player repeatedly calls step() (risking a crash) or collect() (cashing out). The first step is mandatory — collect is only available after at least one successful step. See the Stepper code example for the full loop.

Here's how to wire it up.

Open a game session

After initialization, open a session with your chosen provider:

javascript

const session = await sdk.go3.openGame();
// or: sdk.stepper.openGame() / sdk.rippinrumble.openGame()

console.log('Balance:', session.balance);
console.log('Currency:', session.currency);
console.log('Default bet:', session.defaultBet);

The session gives you the player's balance, currency formatting info, and the valid bet range.

Get valid bets

Before letting the player place a bet, query the valid bet amounts for the bet type the player is about to commit to:

javascript

const bets = sdk.go3.getValidBets();                              // default — same as { betType: 'BASE' }
const boostedBets = sdk.go3.getValidBets({ betType: 'BOOSTED' }); // boosted list (chip levels × multiplier)

Each provider declares its supported bet types via getBetTypes() — see the Bet types section for the full table.

TIP

The rollerz-framework package includes a ready-made bet selector component that handles bet selection, boost toggling, and amount display for you. See Step 5 to add it.

Place a bet and render the result

Place a bet and use the result fields to drive your game visuals:

javascript

async function playRound(amount, betType) {
  const result = await sdk.go3.placeBet(amount, { betType });

  // Use the result to drive your game:
  // - result.count → how many items to animate
  // - result.hasBonus → whether to show a bonus effect
  // - result.multiplier → the win multiplier
  // - result.totalWinAmount → the payout
  await showGameAnimation(result);

  // Collect to finalize the round
  const collected = await sdk.go3.collect(result.roundId);
  updateBalance(collected.balance);
}

Step 4: Platform events (hosted games)

If your game runs inside a host platform (e.g. embedded in an iframe), you'll need to respond to platform events like mute, pause, or resize. Pass event callbacks to init() — the SDK handles the postMessage listening for you.

javascript

await sdk.init('my-game-id', {
  enableLogging: true,
  platformEvents: {
    mute: ({ muted }) => {
      myAudio.muted = muted;
    },
  },
});

The host platform sends events via postMessage as flat objects:

javascript

// Host side
gameIframe.contentWindow.postMessage(
  { type: 'mute', muted: true },
  'https://staging.rollerz.gg', // must be an allowlisted origin
);

You only need to define the callbacks — the SDK matches incoming messages by data.type and invokes the right handler with the full flat message. The SDK checks event.origin against a build-time allowlist (PLATFORM_ORIGINS env var) — messages from any other origin are dropped. If your game is not embedded in a platform, you can skip this step.

Step 5 (optional): Add framework components

The rollerz-framework package provides ready-made UI components so you don't have to build common game chrome from scratch. Everything here is optional — use what you need.

bash

npm install rollerz-framework

Bet selector

A drop-in component with a segmented bet-type selector, bet amount picker, and commit button. Pass the provider's getBetTypes() and getDefaultBetType() directly — for predefined providers it just works; for GP, call sdk.gp.configureBetTypes([...]) first.

javascript

import * as framework from 'rollerz-framework';

const betSelector = framework.createBetSelector({
  container: document.getElementById('betSelector'),
  currency: session.currency,
  betTypes: sdk.go3.getBetTypes(),
  defaultBetType: sdk.go3.getDefaultBetType(),
  getValidBets: (betType) => sdk.go3.getValidBets({ betType }),
  actionLabel: 'Play!',
  onCommit: ({ amount, betType }) => playRound(amount, betType),
  defaultBet: session.defaultBet,
});

// Disable during a round, re-enable after collect
betSelector.setDisabled(true);
// ...
betSelector.setDisabled(false);

Currency formatting

Format monetary values anywhere in your game:

javascript

import { formatAmount } from 'rollerz-framework';

const display = formatAmount(session.balance, session.currency);
// e.g. "$10.00"

Add a hamburger menu with help content and settings:

javascript

framework.showGameMenu({
  container: document.getElementById('menuContainer'),
  helpContent: '<p><strong>My Game</strong></p><p>Instructions go here.</p>',
});

Dev panel

During development, add the dev panel to control bet outcomes locally — force wins, losses, specific multipliers, etc. No network calls are made when dev mode is enabled.

javascript

framework.createDevPanel({
  providers: [{ name: 'GO3', provider: sdk.go3 }],
  position: 'top-right',
});

TIP

Remove or conditionally hide the dev panel before shipping to production.

See the Rollerz Framework guide for the full API and customization options.

Step 6: Go to production

When your game is ready for release, see the Submit a Game guide for the full checklist.

See Environments for details on Dev, Staging, and Production configurations.

Game building guide ​

Step 1: Install and initialize ​

Set up your project ​

Add the SDK script tag ​

Initialize the SDK ​

Step 2: Design your game around a provider ​

Step 3: Integrate the RGS flow ​

Open a game session ​

Get valid bets ​

Place a bet and render the result ​

Step 4: Platform events (hosted games) ​

Step 5 (optional): Add framework components ​

Bet selector ​

Currency formatting ​

Game menu ​

Dev panel ​

Step 6: Go to production ​

Game building guide

Step 1: Install and initialize

Set up your project

Add the SDK script tag

Initialize the SDK

Step 2: Design your game around a provider

Step 3: Integrate the RGS flow

Open a game session

Get valid bets

Place a bet and render the result

Step 4: Platform events (hosted games)

Step 5 (optional): Add framework components

Bet selector

Currency formatting

Game menu

Dev panel

Step 6: Go to production