Game Development Guide

Components

Server-side Game SDK — app/Sdk/

The abstraction every new game is built on. A game is one stateless PHP class; the SDK handles everything else.

Client SDK — resources/rgs-games/_shared/

Your rendering layer (PixiJS) sits on top of this — the SDK talks to the server, PixiJS draws the results. See step 3.

RGS API — app/Actions/Rgs/, RgsController

One endpoint, POST /api/rgs, dispatched by the rquest parameter — the full reference is below.

Wallet abstraction — app/Services/Wallet/

Games never touch money. The play pipeline settles every round through a wallet adapter selected by the WALLET_ADAPTER environment variable:

Data model

Tooling

Random Number Generator (RNG)

The RGS includes a certified-random module that all games must use for outcome determination. The App\Sdk\Rng class wraps PHP's cryptographically secure random number generator (random_int) and provides game-specific helpers.

Accessing the RNG

The RNG is available in your game's play() method via the context object:

public function play(GameContext $context): array
{
    $rng = $context->rng;

    // Roll a die (1-6)
    $roll = $rng->int(1, 6);

    // Draw 20 unique numbers from 1-80 (keno)
    $drawn = $rng->uniqueInts(1, 80, 20);

    // Shuffle a deck of cards
    $deck = $rng->deck();
}

RNG Methods

Card deck encoding

The deck() method returns card indexes 0–51. To decode:

$cardIndex = 27; // Example card
$suit = intdiv($cardIndex, 13);  // 0=spades, 1=hearts, 2=diamonds, 3=clubs
$rank = $cardIndex % 13;         // 0=2, 1=3, ... 8=10, 9=J, 10=Q, 11=K, 12=A

Weighted picks for slots/symbols

Use weightedPick() for slot reels or any outcome where symbols have different probabilities:

$symbol = $rng->weightedPick([
    'cherry'  => 50,  // 50/56 ≈ 89.3%
    'seven'   => 5,   // 5/56 ≈ 8.9%
    'wild'    => 1,   // 1/56 ≈ 1.8%
]);

Security & compliance

• CSPRNG backed — All methods use PHP's random_int(), which sources entropy from the operating system's cryptographic random number generator.
• Auditable — Centralizing RNG in one class makes it easy to audit, test, and potentially swap for a hardware RNG or third-party certified source.
• Deterministic testing — For unit tests, you can mock the Rng class to produce predictable sequences.

Build a game, step by step

php artisan make:game hilo "Hi-Lo Cards" --rtp=96.5 --category=table

public function play(GameContext $context): GameResult
{
    // 1. Validate input (untrusted!) — GameException aborts before any charge
    $guess = strtolower((string) $context->requireInput('guess'));
    if (! in_array($guess, ['low', 'high'], true)) {
        throw new GameException('guess must be "low" or "high"');
    }

    // 2. Decide the outcome — ONLY via $context->rng
    $card = $context->rng->int(1, 13);
    $won  = ($guess === 'high') === ($card > 7);
    $win  = $won ? round($context->betAmount * 1.9, 2) : 0.0;

    // 3. Return payload (for the client) + replay data (for history)
    return GameResult::completed($win)
        ->payload(['card' => $card, 'won' => $won])
        ->input(['guess' => $guess])
        ->outcome(['card' => $card, 'won' => $won])
        ->step('draw', ['card' => $card])
        ->summary("Guessed {$guess}, drew {$card}.");
}

<script src="https://cdn.jsdelivr.net/npm/pixi.js@8.x/dist/pixi.min.js"></script>
<script src="../_shared/query_string.js" onerror="this.remove()"></script>
<script src="../_shared/rgs_bootstrap.js"></script>
<script src="../_shared/rgs-sdk.js"></script>
<script src="../_shared/GameMenuHtml.js"></script>
<script src="js/game.js"></script>

var app, stage;

RgsSdk.boot({
    onReady: function (game) {
        // game.minBet / maxBet / betSteps / defaultBet / balance are decimal strings; game.currency, game.decimals
        app = new PIXI.Application();
        app.init({ resizeTo: window, background: '#0f0f23' }).then(function () {
            document.body.appendChild(app.canvas);
            buildTable(game);            // draw the idle scene + bet UI
        });
    },
    onReplay: function (replay) {
        // Replay mode: render replay.input / replay.result / replay.steps.
        // replay.winamount and replay.betamount are decimal strings (same as the play API).
        renderReplay(replay);
    },
    onError: function (message) { showErrorOverlay(message); }
});

RgsSdk.onBalanceChange(function (balance) { hud.balance.text = RgsSdk.formatMoney(balance); });

function onSpinPressed(bet, guess) {
    RgsSdk.play({ bet_amount: bet, guess: guess })
        .then(function (res) {
            // res = your GameResult payload + winamount, accountsum, new_game_session
            animateOutcome(res, function () { RgsSdk.ack(); });
        })
        .catch(function (err) { showErrorOverlay(err.message); });
}

RgsSdk.boot({
    onReady: function (game) {
        var menu = RgsSdk.createMenu({
            betOptions: game.betSteps,
            bet: game.defaultBet,
            currency: game.currency,
            onPlay: function (bet) {
                RgsSdk.play({ bet_amount: bet, guess: 'high' })
                    .then(function (res) { menu.setWin(res.winamount); animateOutcome(res, function () { RgsSdk.ack(); }); })
                    .catch(function (err) { showErrorOverlay(err.message); });
            }
        });
    },
    onReplay: function (replay) { renderReplay(replay); },
    onError: function (message) { showErrorOverlay(message); }
});

RgsSdk.setTheme({
    panelBg: 'rgba(20, 8, 2, .85)', panelBorder: '#c9a14a', panelRadius: '18px',
    labelColor: '#e8d5a3', valueColor: '#ffd36b', winColor: '#7cf29a', textColor: '#fff',
    buttonBg: '#3a2410', buttonBorder: '#c9a14a', buttonColor: '#ffe9b0', buttonRadius: '50%',
    buttonHoverBg: '#5a3818', buttonHoverBorder: '#ffd36b', buttonHoverColor: '#fff',
    playBg: 'linear-gradient(135deg, #ffd36b, #c98a1a)', playHoverBg: 'linear-gradient(135deg, #ffe08f, #ffd36b)',
    playColor: '#2a1300', playRadius: '999px',
    font: '"Cinzel", Georgia, serif'
});

var menu = null;
var gameRoot = document.getElementById('game-root');

function fitGameRoot() {
    gameRoot.style.bottom = menu.height() + 'px';
}

RgsSdk.boot({
    onReady: function (game) {
        menu = RgsSdk.createMenu({
            betOptions: game.betSteps,
            bet: game.defaultBet,
            currency: game.currency,
            onPlay: function (bet) {
                RgsSdk.play({ bet_amount: bet, guess: 'high' })
                    .then(function (res) { menu.setWin(res.winamount); renderResult(res); RgsSdk.ack(); })
                    .catch(function (err) { showError(err.message); });
            }
        });
        fitGameRoot();
        window.addEventListener('resize', fitGameRoot);
        renderTable(game);
    },
    onReplay: function (replay) { renderReplay(replay); },
    onError: showError
});

<script src="/games/common/query_string.js" onerror="this.remove()"></script>
<script src="/games/common/rgs_bootstrap.js"></script>
<script src="/games/common/rgs-sdk.js"></script>
<script src="/games/common/GameMenuHtml.js"></script>

it('plays a round', function () {
    $load = $this->postJson('/api/rgs', [
        'rquest' => 'load_game', 'token' => 't', 'game_id' => 'hilo',
    ])->json();

    $res = $this->postJson('/api/rgs', [
        'rquest' => 'play',
        'token' => 't',
        'game_session' => $load['game_session'],
        'bet_amount' => '1.00',
        'guess' => 'high',
    ]);

    $res->assertOk()->assertJsonPath('status', 'OK');
});

Sandbox mode (preview development)

The sandbox environment lets you develop and test games without wallet/platform registration. Games run with an isolated sandbox wallet (1000.00 EUR balance).

php artisan make:game hilo "Hi-Lo Cards" --sandbox --rtp=96.5 --category=table

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────┐
│  RGS MCP Server     │     │  Local AI / Dev     │     │  Developer  │
│  (Backend)          │     │  (Frontend)         │     │  (Human)    │
└──────────┬──────────┘     └──────────┬──────────┘     └──────┬──────┘
           │                           │                       │
  1. scaffold-game ────────────────────┼───────────────────────┤
     --sandbox                         │                       │
           │                           │                       │
           │                  2. Build frontend                │
           │                     (HTML/JS/CSS)                 │
           │                           │                       │
           │◄──────────────────────────┤                       │
           │   3. upload-game-frontend │                       │
           │      (base64 ZIP)         │                       │
           │                           │                       │
  4. Preview URL ──────────────────────┼──────────────────────►│
     /sandbox/games/{code}/play.html   │                       │
           │                           │                       │
           │                           │              5. Test & Approve
           │                           │                       │
  6. export-sandbox-game ◄─────────────┼───────────────────────┤
           │                           │                       │

# Upload frontend (base64-encoded ZIP)
curl -X POST "https://rgs.cloudvlt.com/mcp/game-sdk" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "upload-game-frontend",
      "arguments": {
        "code": "mygame",
        "zip_base64": "UEsDBBQ..."
      }
    }
  }'

php artisan sandbox:export hilo
# Or via MCP: export-sandbox-game code=hilo

Multi-step games

Games where the player makes decisions mid-round (blackjack: hit / stand / double) keep the round open by returning awaitingAction:

public function play(GameContext $context): GameResult
{
    if (! $context->isContinuation) {
        // First call: the bet is taken now.
        $deck = $context->rng->deck();
        $hand = [array_shift($deck), array_shift($deck)];

        return GameResult::awaitingAction([
                'deck' => $deck,
                'hand' => $hand,
                'bet'  => $context->betAmount, // remember the stake yourself
            ])
            ->payload(['hand' => $hand, 'actions' => ['hit', 'stand']])
            ->step('deal', ['hand' => $hand]);
    }

    // Continuation: betAmount is 0, your saved state comes back.
    $state = $context->state;

    return match ($context->action()) {
        'hit'   => $this->hit($context, $state),
        'stand' => $this->stand($context, $state),  // -> GameResult::completed(...)
        default => throw new GameException('Illegal action'),
    };
}

What the SDK does for you:

• The session is marked resumable; the next play call routes back with isContinuation = true and your $state.
• The stake is charged once, on the opening call; the win is paid when you return completed.
• One round row is kept and updated each step; each step's ->step() entries are added to the earlier ones, so the whole round replays. Record ->input() and ->outcome() on every step too.
• The client keeps the same game_session until it receives new_game_session (automatic with the client SDK).

Game replay

Every completed round can be re-watched: the game frontend is re-opened in a special replay mode and re-renders the round purely from the data persisted when it was played — no game logic runs again, no wallet is touched, nothing is random. Replay powers the player history page and admin round inspection, so recording good replay data is a hard requirement, not a nicety. Every game must do both halves: the backend records the round, and the frontend draws it in onReplay. The MCP tools check both (see 4).

1. Recording — what the backend persists

On the GameResult of every play call — continuation steps of multi-step games included — your game records:

A call that records no input keeps only the client's own fields — never the player's token or session — and a call with no outcome keeps the client payload. Neither is enough to replay a round: validate-game and play-test-round report it as a failure.

2. Delivery — how a replay reaches the game

1. GET /player/history?token=… lists the player's rounds; each row carries a temporary signed replay URL (valid 2 hours). Replay URLs cannot be constructed by hand.
2. The signed URL opens GET /player/replay/{roundId}, which loads the stored round and embeds the game frontend, launching it with replay=<roundId> plus a #replay_data=<base64url-JSON> fragment containing the full round payload.
3. The same payload is also available raw (with a valid signature) at GET /api/game-round/{roundId}/replay.
4. A released game replays from /games/{code}/play.html; a game still in the sandbox replays from /sandbox/games/{code}/play.html, whose bootstrap reads the same fragment. The game's index.html is the same in both.

3. Rendering — the onReplay callback

The client SDK detects the replay fragment during RgsSdk.boot(), decodes it, skips the load_game handshake and fires onReplay(replay) instead of onReady. The replay object:

How Dice Duel renders it (resources/rgs-games/dd/js/game.js) — show a replay badge, disable the controls, hide the live balance (there is none), and run the normal outcome animation from the stored result:

function runReplay(replay) {
    el.replayBadge.style.display = 'block';
    setBusy(true);                                   // no betting in replay

    var result = replay.result || {};
    var winAmount = replay.winamount || '0';

    el.balance.parentNode.style.visibility = 'hidden';
    if (result.dice) {
        animateRoll(result.dice, function () {
            showOutcome(!!result.won, winAmount, result.total);
        });
    }
}

Behaviour in replay mode:

• RgsSdk.isReplay() returns true; RgsSdk.play() rejects with "Cannot play in replay mode" — the mode is read-only by construction.
• No RGS calls are made: there is no session, no live balance, no ack(). Hide or freeze the bet UI and balance HUD.
• Reuse your normal rendering/animation path fed from replay.result / replay.steps — a PixiJS frontend replays by running the same timeline it uses for live results, just sourced from the stored steps instead of a play() response.

4. Verifying replay (definition of done)

• validate-game fails a game whose frontend has no onReplay, or whose backend never calls ->input(), ->outcome() or ->step().
• play-test-round shows, per call, what the round recorded (recorded_for_history), lists replay data a call left out under history.problems (must be empty), and returns history.replay_url: a signed link that opens the last round in the replay viewer.
• Open history.replay_url in a browser: the round must be redrawn exactly as it was played — same cards/reels/multipliers, same win — with no bet or PLAY controls. The win shown must match the header of the replay page.
• For multi-step games, play a round through every action with play-test-round's sequence, replay it, and confirm every step re-renders in order.
• Without MCP: play a few rounds, open /player/history?token=… and replay one.
• Endpoint details: History & replay API; launch parameters: Game launch URL.

Using Dice Duel as a template

Dice Duel (code dd) is the reference implementation every new game should imitate — a complete, shippable game in two small files:

The game itself: the player bets low or high, two dice are rolled; totals 2–6 are low, 8–12 are high, 7 pushes (stake returned). A correct guess pays 2.3×.

Workflow: template → your game

1. Read both Dice Duel files (or use the MCP read-reference-game tool).
2. Scaffold your game: php artisan make:game <code> "<Name>" — the scaffold is itself a minimal Dice-Duel-shaped game.
3. Replace the outcome logic in play() keeping the same structure: validate → RNG → payout → record.
4. Replace the DOM rendering in js/game.js with your PixiJS stage, keeping the SDK calls (boot/play/ack/onBalanceChange/onReplay) exactly as the template uses them.
5. Try it live: /games/dd/index.html?token=dev&game_id=dd (requires WALLET_ADAPTER=local).

Building with AI agents (MCP)

The repo ships an MCP (Model Context Protocol) server exposing the whole game-building workflow as tools, so an AI agent can scaffold, implement, validate and play-test a game end-to-end without human plumbing.

Connect via HTTP (Remote / Cloud)

The MCP server is available via HTTP at:

https://rgs.cloudvlt.com/mcp/game-sdk

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "rgs-game-sdk": {
      "url": "https://rgs.cloudvlt.com/mcp/game-sdk"
    }
  }
}

Restart Claude Desktop after editing.

Cursor / Windsurf

Add to .cursor/mcp.json or .windsurf/mcp.json in your project:

{
  "mcpServers": {
    "rgs-game-sdk": {
      "url": "https://rgs.cloudvlt.com/mcp/game-sdk"
    }
  }
}

Test with curl

curl -X POST https://rgs.cloudvlt.com/mcp/game-sdk \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Connect via stdio (Local Development)

For local development, the MCP server is auto-wired for Claude Code via .mcp.json:

{
  "mcpServers": {
    "rgs-game-sdk": {
      "command": "php",
      "args": ["artisan", "mcp:start", "game-sdk-local"]
    }
  }
}

The agent workflow

1. read-docs (topic game-development, then game-sdk) — learn components, process, requirements.
2. read-reference-game — study Dice Duel (backend + frontend) before writing code.
3. scaffold-game — generate the runnable skeleton. Never create the files by hand.
4. Edit app/Games/{Class}Game.php (PHP outcome module) and resources/rgs-games/{code}/js/game.js + index.html (PixiJS UI).
5. validate-game — verify all wiring is consistent, replay support included.
6. play-test-round — play real rounds, including invalid input (it must fail cleanly with no charge). history.problems must be empty; open history.replay_url and check the round is redrawn as played.
7. run-tests — the whole suite must pass; add Pest tests per tests/Feature/Sdk/GameSdkTest.php.

Server implementation: app/Mcp/GameSdkServer.php. Start manually with php artisan mcp:start game-sdk for any MCP-compatible client.

API reference — POST /api/rgs

One endpoint; the rquest parameter selects the method. (POST /api/api.php is a legacy alias.) The client SDK wraps all of this — game code normally never calls these directly.

Conventions

• Requests: POST with application/x-www-form-urlencoded or JSON bodies.
• Responses: JSON. Every success carries "status": "OK"; every failure is HTTP 400 with {"status": "Failed", "msg": "reason"}.
• Money: decimal strings with exactly the currency's decimals, in responses and requests ("accountsum": "998.70"; see decimals on load_game). Send a bet_steps entry as bet_amount unchanged; never parse amounts into numbers.
• Auth: the wallet session token from the launch URL authenticates every call.
• CORS: /api/rgs answers with Access-Control-Allow-Origin: *.

Common parameters for every method:

POST {platform_url}/api/portal/players/login
Content-Type: application/json

{
  "email": "player@example.com",
  "password": "secret",
  "player_ip": "1.2.3.4",
  "portal_id": 1
}

{
  "status": "success",
  "wallet_session_token": "1|abc123xyz...",
  "player": {
    "id": 42,
    "email": "player@example.com",
    "name": "John Doe",
    …
  }
}

POST /api/rgs
rquest=load_game&token=<wallet-token>&game_id=dd

{
  "game_id": "dd",
  "sname": "dd",
  "name": "Dice Duel",
  "game_session": "01JZWX3E5H8Q2R9T0V1W2X3Y4Z",
  "player_name": "mrCat",
  "currency": "EUR",
  "decimals": 2,
  "language": "en",
  "accountsum": "1000.00",
  "min_bet": "0.10",
  "max_bet": "100.00",
  "bet_steps": ["0.10", "0.20", "0.50", "1.00", "2.00", "5.00"],
  "default_bet": "0.10",
  "lines": 1,
  "jurisdiction": "SE",
  "rgs_features": {
    "autoplay": { "enabled": false, "maxSpins": null, "lossLimit": true },
    "turbo": false, "slamStop": false, "bonusBuy": false, "gambleFeature": true,
    "jackpots": true, "parallelPlay": true, "maxStake": null, "minRoundMs": 3000,
    "bigWin": true, "celebrateLowWins": true,
    "realityCheck": { "enabled": true, "intervalMinutes": 60, "pausesPlay": false },
    "sessionTime": true, "netPosition": true, "showRtp": false
  },
  "status": "OK"
}

POST /api/rgs
rquest=play&token=<t>&game_session=01JZ…&bet_amount=1.00&guess=high

{
  "dice": [6, 4],
  "total": 10,
  "guess": "high",
  "won": true,
  "winamount": "2.30",
  "status_id": 0,
  "accountsum": "1001.30",
  "multi_state": 0,
  "new_game_session": "01JZWX4A7B8C9D0E1F2G3H4J5K",
  "status": "OK"
}

{ "accountsum": "998.70", "currency": "EUR", "status": "OK" }

{ "msg": "game session acknowledged", "status": "OK" }

GET /api/round/739/outcome?token=…

{
  "round_id": 739,
  "replay_url": "https://rgsaws.cloudvlt.com/player/replay/739?expires=1767225600&signature=abc123...",
  "expires_at": "2026-01-01T00:00:00+00:00"
}

Game launch URL

Games are static frontends served at /games/{code}/index.html. The casino/aggregator launches them with query parameters:

https://rgsaws.cloudvlt.com/games/dd/index.html?token=abc123&game_id=dd&currency=EUR&lang=es_ES&device_id=web

The player's jurisdiction is not a launch URL parameter: the operator names it in the server-to-server launch API and the game gets its rules from load_game — see jurisdiction features.

Currencies & languages

Every game must support the RGS defaults, set by the operator in the backoffice (Configuration → Currencies / Languages): currencies EUR, USD and languages en_US, es_ES, ja_JP. A launch that names none uses EUR / en_US.

• The operator passes both on the launch URL: ?currency=USD&lang=es_ES. lang may be a locale code (es_ES) or ISO 639-1 (es); games accept both. A language or currency the RGS doesn't support falls back to EUR / en_US.
• Read them with the client SDK — RgsSdk.getCurrency(), getLanguage(), getLanguageIso() and formatMoney(amount) — never by hardcoding. Once the game is loaded the wallet's currency wins over ?currency=.
• Money formatting. The number of decimals depends on the currency, as set in the backoffice (USD/EUR 2, JPY 0); load_game returns it as decimals (and currency_format). Amounts are formatted by the currency only — never by the player's language: each currency has its own symbol position, symbol spacing and thousands and decimal separators, set in the backoffice (symbol_position, symbol_space, thousands_separator, decimal_separator in currency_format), e.g. €1,234.50, R$ 1.234,50, 5.000 ₫, ¥1,234. formatMoney applies it — it pads to the currency's decimals and never rounds an exact amount; games that draw digits themselves use RgsSdk.getCurrencyFormat().
• Every visible text comes from a translation table with every RGS default language; every amount is shown with formatMoney. Amounts on the wire are the same in every currency; the backend never converts. Dice Duel and the scaffolded frontend show the pattern.
• Test in the sandbox lobby (currency and language selectors) or with the MCP tool play-test-round (currency, lang). validate-game checks the frontend.

Jurisdiction features

Every player plays under a jurisdiction (backoffice: Configuration → Jurisdictions). The operator names it in the launch API (jurisdiction, e.g. SE, UK), else the operator's default applies (Wallets → Default jurisdiction), else Curaçao (CW, everything allowed). An unknown or inactive code refuses the launch. It is fixed for the session, and load_game returns it with its features:

"jurisdiction": "SE",
"rgs_features": {
  "autoplay": { "enabled": false, "maxSpins": null, "lossLimit": true },
  "turbo": false, "slamStop": false, "bonusBuy": false, "gambleFeature": true,
  "jackpots": true, "parallelPlay": true, "maxStake": null, "minRoundMs": 3000,
  "bigWin": true, "celebrateLowWins": true,
  "realityCheck": { "enabled": true, "intervalMinutes": 60, "pausesPlay": false },
  "sessionTime": true, "netPosition": true, "showRtp": false
}

Features are data, not code. Each feature is a row with a default (Configuration → Jurisdiction features) and each jurisdiction stores only where it differs. The operator adds features and changes rules in the backoffice, and a game that reads a feature follows the change without an update. Read every feature you support with the value your game would use without the rule:

if (RgsSdk.getFeature('autoplay.enabled', true)) showAutoplay(RgsSdk.getFeature('autoplay.maxSpins', null));

if ($context->input('buy') && ! $context->features->get('bonusBuy', true)) {
    throw new GameException('Bonus buy is not available'); // before the player is charged
}

Current features:

Seeded jurisdictions:

• Never read the jurisdiction from the URL: the player can edit it.
• In replay, getFeature() and getFeatures() return the replayed round's features.
• Verify: validate-game fails a sandbox frontend that offers autoplay, turbo, slam stop or bonus buy without reading the features, or that reads jurisdiction from the URL. play-test-round takes jurisdiction (e.g. "SE") and reports the rgs_features the game got. In the sandbox lobby, the Jurisdiction dropdown launches the game in that jurisdiction.

Free rounds

Operators give players free rounds on a game: a number of rounds at a fixed stake, paid for by the operator. The player stakes nothing; the round plays exactly like a paid round at that stake, and its win is paid to the player's balance as cash. The client SDK and the kernel do almost all of it, so a single-stake game supports free rounds with no code. The full feature reference (awards, their lifecycle, settlement) is docs/FREE-ROUNDS.md; operators award them as described in the operator guide.

What the player sees (built in)

• The offer when the game opens: the rounds, the stake per round, the expiry, the max win and any actions switched off, with PLAY FREE ROUNDS and, when the award allows it, NO THANKS. There is no "later": until the player answers, and until an accepted award is played, real-money play of that game is refused with FREE_ROUNDS_PENDING and the offer comes back.
• A counter at the top while free rounds are played ("FREE ROUNDS 2/10 · WON €1.50"), each round's win shown as a free-round win.
• A summary at the end ("You won €3.00 in 10 free rounds"; "Maximum win reached" when the award's cap ended it).
• In the shared menu the bet buttons give way to the rounds left, Bet shows the award's stake and Win reads "Free round win". A replay of a free round is marked "FREE ROUND 2/10".

Backend

• $context->bet already is the award's stake. Take the stake only from there, never from client input.
• $context->freeRound (awardId, roundNumber, totalRounds, bet) and $context->isFreeRound() are there for presentation only. Never change the math on them.
• A game whose round can add stake after it opens (double, split, insurance, a bonus buy, a gamble) implements App\Sdk\Contracts\HasFreeRoundRules. The kernel then refuses those actions in a free round before the game runs, and the offer and rules show the RTP without them:

public function freeRoundDisabledActions(): array { return ['double', 'split', 'insurance']; }
public function freeRoundRtp(?int $rtpLevel): string { return '99.10'; } // the RTP without them

A game whose math cannot settle against one fixed stake implements NoFreeRounds (noFreeRoundsReason()). That is rare: table games take free rounds with HasFreeRoundRules. Legacy engine games never get free rounds: their engine takes the stake from the wallet itself.

Frontend

With the shared menu there is nothing to do. A game with its own bet controls (Dice Duel is the reference) does this while RgsSdk.isFreeRound() is true:

function renderBet() {
    var free = RgsSdk.isFreeRound();
    betLabel.textContent = RgsSdk.formatMoney(free ? RgsSdk.getFreeRounds().bet : betSteps[betIndex]);
    betDown.disabled = betUp.disabled = free;               // the award's stake is fixed
}
RgsSdk.onFreeRoundsChange(renderBet);                       // offer accepted, last round played
// No balance check on a free round's stake; hide RgsSdk.getFreeRounds().disabledActions.
// RgsSdk.play() sends the award's stake whatever bet_amount it is given.

RgsSdk.getFreeRounds() returns {awardId, status, roundsTotal, roundsLeft, roundsPlayed, bet, winnings, maxWin, maxWinReached, forfeitedRounds, expiresAt, rejectable, disabledActions, rtp} or null. A game that draws its own free-round screens boots with RgsSdk.boot({ freeRoundsUi: false, … }) and calls RgsSdk.acceptFreeRounds() / RgsSdk.rejectFreeRounds() itself. Never cover the SDK's offer and counter.

Testing

play-test-round cannot play free rounds yet, validate-game does not check them, and sandbox games cannot be given an award. Locally (WALLET_ADAPTER=local), create an award for player dev in the backoffice (Promotions → Free Round Assignments) and open /games/{code}/index.html?token=dev&game_id={code}: you should see the offer, the counter, the free-round wins and the summary. Requirement T18 in docs/GAME-DEVELOPMENT.md lists what a game must do; the API details are in docs/GAME-SDK.md → Free rounds.

Splash screen (showsplash)

The launch URL tells the game whether to show its splash screen. With showsplash=false the game goes straight into the game: the player lands on the playable screen, ready to bet, with no extra click.

What is skipped, what still shows

• Skipped: an intro animation or video, a title or logo screen, a "loading complete, tap to continue" or "press to start/play" screen, an introductory feature tour (keep help in the menu's rules).
• Still shown: a progress bar while assets load (the game opens as soon as they have), the SDK's free-round offer (a decision, not a splash), errors and anything a jurisdiction requires.

In the game

Read it with RgsSdk.showSplash(), never from the URL yourself: validate-game fails a frontend that reads showsplash.

RgsSdk.boot({
    onReady: function (game) {
        buildUi(game);
        if (RgsSdk.showSplash()) {
            showIntro(function () { showGame(); });
        } else {
            showGame();   // straight to the playable screen
        }
    }
});

Sound. Browsers play audio only after a user gesture, and a "press to start" button often exists just for that. Without it, start the game silent and turn sound on at the player's first tap (the first spin or bet). Don't add a start screen back for it.

Who sets it

The RGS adds showsplash to every launch URL. It follows the backoffice Settings switch "Show splash screen" (off by default, so launches send showsplash=false), and it is always false while the player has free rounds waiting. Test a game with ?showsplash=false, e.g. /sandbox/games/{code}/play.html?showsplash=false. Requirement T19 in docs/GAME-DEVELOPMENT.md.

Max win

A game declares the most one round can pay (GLI-19 4.4.1(r)) by implementing App\Sdk\Contracts\HasMaxWin: a multiple of the round's total stake, the opening stake plus every action stake (double, split, insurance). Use the top paytable award; it must be at least every award the game can pay.

class DiceDuelGame implements GameInterface, HasMaxWin
{
    public function maxWinMultiplier(): string
    {
        return '2.3'; // a decimal string, never a float
    }
}

• The kernel caps each round's win at multiplier × stake, settled exactly like the win; a capped round records win_cap (multiplier, raw, paid) in its result. The game itself never caps, and never touches money.
• The max_win section of rules.json states the same value (a test checks it). Aggregators get it as maxWinBetMultiplier in the game feeds and when the game is registered.
• Without HasMaxWin, validate-game warns (it does not fail) and the RGS assumes the configured default (5000× unless set). Declare the real value: too high hides stakes needlessly, too low caps legitimate wins.

The operator's max win

An operator may set a max win per currency (backoffice → Wallets → Max win). The RGS enforces it; the game only respects what load_game sends.

• Bet ladder: load_game offers no stake above the operator's max win ÷ the game's multiplier (rounded down), and sends max_round_stake and max_win_amount. With a max win of 5000 and a 500× game the highest bet is 10. When no bet fits, the launch is refused. Build the bet selector only from bet_steps / min_bet / max_bet.
• At play: a round whose stake × multiplier exceeds the max win is refused with BET_REJECTED before the game runs (this catches a limit lowered after the load).
• Actions that stake again (HasActionStakes: double, split, insurance) are checked against the max win recorded when the round opened, before the wallet is charged. Grey such actions out with RgsSdk.canStake(cost); blackjack does.
• Free rounds: an award whose stake × multiplier exceeds the max win is refused when it is assigned, and cancelled at load_game if the limit is lowered later.

The game never sees the operator max win and never lowers a win: an accepted round pays in full, capped only by its own multiplier. Details in docs/GAME-SDK.md → Max win.

Bonus buy

A bonus buy lets the player pay a price to enter a feature directly (for example, 10 free spins). The price is a multiple of the bet the player chose (the base bet); the round is one normal round whose stake is the price, and the feature plays on the base bet. The RGS prices, checks and charges every buy; the game only plays the feature.

Declare the options

class StarfallGame implements GameInterface, HasRtpLevels, HasBonusBuy, HasFreeRoundRules
{
    public function bonusBuyOptions(): array
    {
        return [
            new BonusBuyOption(
                id: 'freespins',
                name: '10 free spins',
                priceMultiplier: '100',                                  // price = base bet × 100
                rtp: ['default' => '96.10', 96 => '96.10', 94 => '94.05'], // RTP per level
                maxWinMultiplier: '50',                                  // win cap = price × 50
            ),
        ];
    }

    public function freeRoundDisabledActions(): array
    {
        return [HasBonusBuy::ACTION]; // never in a free round
    }

    public function play(GameContext $context): GameResult
    {
        if ($context->isBonusBuy()) {
            return $this->startFreeSpins($context, $context->baseBet); // same math as a natural trigger
        }
        // ... a normal spin on $context->bet
    }
}

• Multipliers and RTPs are decimal strings. rtp keys are 'default' or the game's RTP levels; a level without an RTP means the option is not offered at that level.
• The feature starts on $context->baseBet; $context->bet is the price. The game reads the option from $context->bonusBuy, never a price or option from the input.
• A bought feature starts from a fixed state: nothing carried over from earlier rounds may change its value.
• A feature of several steps continues with rquest=play like any multi-step round.

What the RGS does

• The offer: load_game sends bonus_buy (or null): the options at the session's RTP level and the exact prices per option and bet step.
• The buy: rquest=bonus_buy with game_session, option and bet_amount (the base bet). The client never sends a price; the RGS charges base bet × priceMultiplier, exactly, before the game runs.
• Refused with REQUEST_DECLINED while a round is open, in a free round or with free rounds pending, in autoplay, where the jurisdiction switches bonusBuy off, or on a game without options.
• Refused with BET_REJECTED: an unknown option or one not offered at the RTP level, a base bet that is not offered, a price above the jurisdiction's bonusBuyMaxPrice or the wallet's max bet, or a price × maxWinMultiplier above the operator's max win.
• Win cap: the whole round pays at most price × maxWinMultiplier; the step that reaches it pays the rest, later steps pay 0.

Client SDK

const offer = RgsSdk.getBonusBuy();              // null when bonus buy is off
const price = RgsSdk.bonusBuyPrice(bet, 'freespins'); // the server's exact price
if (await RgsSdk.confirmBonusBuy(bet)) {         // the standard confirmation dialog
    const result = await RgsSdk.buyBonus('freespins', bet);
}
RgsSdk.createMenu({ onBuyBonus: () => { /* open your buy screen */ } });

buyBonus() is refused without a confirmation. Show the option, the price in the player's currency, its RTP and that the price buys one round.

Proving the RTP

validate-game (and publish-game) checks every option: its RTP inside the 99 % interval of a quick simulation at each level, within ±1.0 percentage point of the game's RTP, an RTP for every level, refused in free rounds, and a fixed starting state. Measure the real RTP with simulate-rtp (MCP) while building and php artisan game:simulate {code} --option={id} --rtp-level={N} --rounds=50000000 for the math sheet: a bought round is far more volatile than a spin.

Wallets

A bonus buy is a normal bet and win on every wallet: the price is one withdrawal, the wins are deposits. A wallet API without tags gets plain calls. The platform wallet gets type: "bonus_buy" on the price and type: "bonus_win" on the wins, also on a wallet set to one call per round (a bought round never uses betandwin). Details in docs/BONUS-BUY.md.

Player history & replay

Everything a game records via GameResult::input() / outcome() / step() powers these automatically. Replay links are temporary signed URLs.

The #replay_data= fragment handed to the game is base64url-encoded JSON of that payload; the client SDK decodes it and calls the game's onReplay(replay) callback. All money values (winamount, betamount) are decimal strings, consistent with the play API. The full flow — recording, delivery, rendering — is described in Game replay.

Health check

GET /api/health   → 200 { "status": "ok" }
GET /up           → 200 (framework liveness)

How operators integrate — launch API and wallet contract — is in the operator integration guide.

Server SDK reference (PHP)

Namespace App\Sdk. Your game implements one method:

interface GameInterface
{
    public function play(GameContext $context): GameResult;
}

Game classes are resolved through the Laravel container (constructor injection works) and must be stateless — all round state travels through GameContext/GameResult.

GameContext (input)

GameResult (output)

Rng

Backed by PHP's CSPRNG. Available as $context->rng:

GameException

Throw it (or use requireInput()) to reject a request cleanly. The request aborts before any wallet transaction — the player is never charged — and the client receives HTTP 400, which the client SDK surfaces as a rejected promise.

Client SDK reference (JS)

resources/rgs-games/_shared/rgs-sdk.js (ES5, no dependencies). Exactly one of the three boot callbacks fires.

The game object passed to onReady: name, balance, currency, decimals, minBet, maxBet, betSteps, defaultBet, session; balance, minBet, maxBet, betSteps and defaultBet are decimal strings. maxRoundStake is the most one round may stake under the operator's max win (a decimal string), or null when the operator sets none. The replay object passed to onReplay: input, result, steps, winamount, betamount (decimal strings).

Hard rules

These keep the RGS certifiable — treat them as non-negotiable requirements:

1. All randomness through $context->rng. Never rand(), mt_rand(), shuffle(), or array_rand() in game code.
2. Games never touch money. No wallet calls, no balance math beyond computing winAmount from betAmount.
3. Stateless game classes. Round state only via awaitingAction($state) → $context->state.
4. Validate every client input — the client is untrusted. Reject with GameException; it aborts before the player is charged.
5. Record replayable data (input/outcome/step) for every round.
6. The frontend never decides outcomes. It renders what the server returns; the displayed balance always comes from the RGS response.
7. Game code is a string stored in the games.game_id column (single source of truth). The game client must exist at resources/rgs-games/{code}/.
8. The stated RTP must match the implemented math model. New games must never use the legacy eval engine.
9. Follow the jurisdiction. Never offer a feature RgsSdk.getFeature() reports as off, read each with a permissive default, and never read the jurisdiction from the URL — see jurisdiction features.

Quick reference

php artisan make:game <code> "<Name>"   # scaffold a new game
./vendor/bin/pest                       # run all tests
WALLET_ADAPTER=local                    # .env — then open:
#   /games/<code>/index.html?token=dev&game_id=<code>
php artisan mcp:start game-sdk          # MCP server for AI agents

Blackjack Frontend Development

Complete guide for building a new blackjack frontend that integrates with the RGS.

POST /api/rgs
rquest=load_game&token={token}&game_id=bj

POST /api/rgs
rquest=play&token={token}&game_session={session}&game_id=bj&bet_amount=10&continue=0&action=bet

POST /api/rgs
rquest=play&token={token}&game_session={session}&game_id=bj&continue=1&action={action}

// JavaScript card decoding
function decodeCard(id) {
    var suits = ['♥', '♦', '♣', '♠'];
    var ranks = ['2','3','4','5','6','7','8','9','10','J','Q','K','A'];
    return ranks[id % 13] + suits[Math.floor(id / 13)];
}
// decodeCard(10) → "Q♥" (Queen of Hearts)
// decodeCard(51) → "A♠" (Ace of Spades)

POST /api/portal/players/login
{
  "email": "player@example.com",
  "password": "password123",
  "portal_id": 1,
  "player_ip": "127.0.0.1"
}

// Response includes wallet_session_token

https://rgsaws.cloudvlt.com/games/bj/play.html?token={wallet_session_token}&game_id=bj&rgs_url=https%3A%2F%2Frgsaws.cloudvlt.com%2Fapi%2Frgs&device_id=web

// API helper
function api(params) {
    var body = Object.assign({}, params, { token: window.RGS_TOKEN });
    return fetch(window.RGS_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: Object.keys(body).map(function(k) {
            return encodeURIComponent(k) + '=' + encodeURIComponent(body[k]);
        }).join('&')
    }).then(function(r) { return r.json(); });
}

// Load game
api({ rquest: 'load_game', game_id: 'bj' }).then(function(res) {
    state.gameSession = res.game_session;
    state.balance = res.accountsum;   // decimal string — show it as is, never parseFloat
    state.bet = res.default_bet;      // a bet_steps entry; send it unchanged
});

// Deal
api({
    rquest: 'play',
    game_session: state.gameSession,
    game_id: 'bj',
    bet_amount: state.bet,
    continue: 0,
    action: 'bet'
}).then(handleResponse);

// Player action
api({
    rquest: 'play',
    game_session: state.gameSession,
    game_id: 'bj',
    continue: 1,
    action: 'hit'  // or 'stand', 'double', 'split', 'insurance'
}).then(handleResponse);

function handleResponse(res) {
    // Update balance
    state.balance = res.accountsum;

    // Parse cards
    state.dealerCards = res.dealercards.split(',').map(Number);
    state.playerCards = res.playercards ? res.playercards.split(',').map(Number) : [];

    // Check for split
    if (res.player_hand1) {
        state.split = true;
        state.hand1 = res.player_hand1.split(',').map(Number);
        state.hand2 = res.player_hand2.split(',').map(Number);
    }

    // Available actions
    state.actions = (res.actions || '').split(',').filter(Boolean);

    // Round complete?
    if (parseInt(res.status_id) === 0) {
        showOutcome(res.result, res.winamount);
        state.gameSession = res.new_game_session;  // For next round
    } else {
        showActionButtons(state.actions);
    }

    renderTable();
}

# Load game
curl -X POST https://rgsaws.cloudvlt.com/api/rgs \
  -d "rquest=load_game&token=1|abc123...&game_id=bj"

# Deal ($5 bet)
curl -X POST https://rgsaws.cloudvlt.com/api/rgs \
  -d "rquest=play&token=1|abc123...&game_session=SESSION_ID&game_id=bj&bet_amount=5&continue=0&action=bet"

# Hit
curl -X POST https://rgsaws.cloudvlt.com/api/rgs \
  -d "rquest=play&token=1|abc123...&game_session=SESSION_ID&game_id=bj&continue=1&action=hit"

# Stand
curl -X POST https://rgsaws.cloudvlt.com/api/rgs \
  -d "rquest=play&token=1|abc123...&game_session=SESSION_ID&game_id=bj&continue=1&action=stand"

Multiplayer Blackjack

Real-time multiplayer blackjack with synchronized rounds. Up to 7 players can sit at a table and play simultaneously against the dealer. Uses WebSocket for instant updates.

Session-Token: <the player's game token>

GET /api/multiplayer/blackjack/tables

Response:
{
    "success": true,
    "tables": [
        {
            "table_id": "table-1",
            "name": "VIP Table 1",
            "type": "vip",
            "min_bet": 1.00,
            "max_bet": 500.00,
            "seat_count": 7,
            "occupied_seats": 2,
            "available_seats": 4,
            "status": "waiting",
            "current_phase": "betting"
        }
    ]
}

POST /api/multiplayer/blackjack/tables
Session-Token: <the player's game token>
Content-Type: application/json

{
    "name": "My Table",        // optional, auto-generated if not provided
    "type": "standard",        // optional: standard, vip, turbo (default: standard)
    "min_bet": 1.00,           // optional, in currency units (default: 1.00)
    "max_bet": 500.00,         // optional, in currency units (default: 500.00)
    "seat_count": 7            // optional: 1-7 (default: 7)
}

Response (201 Created):
{
    "success": true,
    "table": {
        "table_id": "table-a1b2c3d4",
        "name": "My Table",
        "type": "standard",
        "min_bet": 1.00,
        "max_bet": 500.00,
        "seat_count": 7,
        "status": "waiting",
        "current_phase": "betting"
    }
}

GET /api/multiplayer/blackjack/tables/{table_id}?player_id={player_id}

Response:
{
    "success": true,
    "table": {
        "table_id": "table-1",
        "name": "VIP Table 1",
        "current_phase": "player_turn",
        "current_seat": 2,
        "dealer_cards": [8],
        "dealer_value": null,
        "seats": [
            {
                "seat_number": 1,
                "player_id": "player_alice",
                "player_name": "Alice",
                "bet": 10.00,
                "cards": [15, 22],
                "hand_value": 17,
                "status": "standing",
                "is_current": false
            },
            {
                "seat_number": 2,
                "player_id": "player_bob",
                "player_name": "Bob",
                "bet": 25.00,
                "cards": [0, 9],
                "hand_value": 12,
                "status": "playing",
                "is_current": true,
                "is_me": true,
                "available_actions": ["hit", "stand", "double"]
            }
        ]
    }
}

POST /api/multiplayer/blackjack/tables/{table_id}/join
Content-Type: application/json

{
    "seat_number": 3,
    "player_id": "player_charlie",
    "player_name": "Charlie",
    "token": "wallet-session-token"
}

POST /api/multiplayer/blackjack/tables/{table_id}/leave
Content-Type: application/json

{
    "seat_number": 3,
    "player_id": "player_charlie"
}

POST /api/multiplayer/blackjack/tables/{table_id}/bet
Content-Type: application/json

{
    "seat_number": 3,
    "bet_amount": 25.00,
    "player_id": "player_charlie"
}

POST /api/multiplayer/blackjack/tables/{table_id}/action
Content-Type: application/json

{
    "seat_number": 3,
    "action": "hit",
    "player_id": "player_charlie"
}

// Valid actions: hit, stand, double, split, insurance

# List tables
curl https://rgsaws.cloudvlt.com/api/multiplayer/blackjack/tables

# Create table
curl -X POST https://rgsaws.cloudvlt.com/api/multiplayer/blackjack/tables \
  -H "Content-Type: application/json" \
  -d '{"name":"Test Table","type":"standard","min_bet":5,"max_bet":500,"seat_count":6}'

# Join table
curl -X POST https://rgsaws.cloudvlt.com/api/multiplayer/blackjack/tables/{tableId}/join \
  -H "Content-Type: application/json" \
  -d '{"seat_number":1,"player_id":"test123","player_name":"Tester"}'

# Place bet
curl -X POST https://rgsaws.cloudvlt.com/api/multiplayer/blackjack/tables/{tableId}/bet \
  -H "Content-Type: application/json" \
  -d '{"seat_number":1,"bet_amount":25,"player_id":"test123"}'

# Perform action (hit/stand/double/split)
curl -X POST https://rgsaws.cloudvlt.com/api/multiplayer/blackjack/tables/{tableId}/action \
  -H "Content-Type: application/json" \
  -d '{"seat_number":1,"action":"hit","player_id":"test123"}'

https://rgsaws.cloudvlt.com/games/mbj/play.html?token={wallet_session_token}&game_id=mbj

blackjack-table.{table_id}

// Broadcast payload
{
    "table": { /* full table state */ },
    "timestamp": "2026-09-18T14:30:00+00:00"
}

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;
window.Echo = new Echo({
    broadcaster: 'pusher',
    key: 'your-pusher-key',
    cluster: 'mt1',
    forceTLS: true
});

// Subscribe to table updates
Echo.channel(`blackjack-table.${tableId}`)
    .listen('.table.updated', (e) => {
        console.log('Table updated:', e.table);
        updateUI(e.table);
    });