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

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="js/game.js"></script>

var app, stage;

RgsSdk.boot({
    onReady: function (game) {
        // game.minBet / maxBet / betSteps / defaultBet / balance / currency
        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 is in CENTS — divide by 100.
        renderReplay(replay);
    },
    onError: function (message) { showErrorOverlay(message); }
});

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

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); });
}

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.0,
        'guess' => 'high',
    ]);

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

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 — carry steps forward with ->steps([...$context->steps, ...$newSteps]).
• 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, admin round inspection, and the QTech game-result verification endpoint, so recording good replay data is a hard requirement, not a nicety.

1. Recording — what the backend persists

During play(), your game records the round on the GameResult:

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 (2 hours; QTech game-result links are valid 24 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.

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) / 100;   // history sends cents

    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)

• Play a few rounds against the local wallet, open /player/history?token=dev, and replay one — it must render correctly from stored data alone.
• For multi-step games, replay a round with several actions and confirm every step re-renders in order.
• 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. It is auto-wired for Claude Code via .mcp.json:

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

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.
6. play-test-round — play real rounds, including invalid input (it must fail cleanly with no charge).
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 2 decimals on the wire ("accountsum": "998.70"); bets sent as decimal numbers. Internally integer cents.
• 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 /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",
  "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,
  "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.3,
  "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" }

Game launch URL

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

https://rgs.example.com/games/dd/index.html?token=abc123&game_id=dd&device_id=web

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. Note replay.winamount is in cents. The full flow — recording, delivery, rendering — is described in Game replay.

Health check

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

QTech platform inbound endpoints (/api/qtech/game-launch, /api/qtech/game-result) and the outbound platform-wallet contract are documented in docs/API.md and docs/QTECH-INTEGRATION.md.

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, minBet, maxBet, betSteps, defaultBet, session. The replay object passed to onReplay: input, result, steps, winamount (cents).

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 2–16 lowercase alphanumeric chars and must match in config/games.php, games.game_id, and resources/rgs-games/{code}/.
8. The stated RTP must match the implemented math model. New games must never use the legacy eval engine.

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 getCardInfo(cardIndex) {
    var suits = ['hearts', 'diamonds', 'clubs', 'spades'];
    var ranks = ['2','3','4','5','6','7','8','9','10','J','Q','K','A'];
    return {
        suit: suits[Math.floor(cardIndex / 13)],
        rank: ranks[cardIndex % 13]
    };
}

Portal (Frontend)  →  RGS (Game Logic)  →  Platform (Wallet)
     │                      │                      │
     │ 1. Login             │                      │
     │──────────────────────────────────────────────▶
     │                      │                      │
     │ 2. Get Token         │                      │
     │◀──────────────────────────────────────────────
     │                      │                      │
     │ 3. Launch Game       │                      │
     │─────────────────────▶│                      │
     │                      │ 4. Validate Token    │
     │                      │─────────────────────▶│
     │                      │ 5. Bet/Win           │
     │                      │─────────────────────▶│

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://rgs.example.com/games/bj/play.html?token={wallet_session_token}&game_id=bj&rgs_url=https%3A%2F%2Frgs.example.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 = parseFloat(res.accountsum);
});

// Deal
api({
    rquest: 'play',
    game_session: state.gameSession,
    game_id: 'bj',
    bet_amount: 10,
    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 = parseFloat(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, parseFloat(res.winamount));
        state.gameSession = res.new_game_session;  // For next round
    } else {
        showActionButtons(state.actions);
    }

    renderTable();
}

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

# Deal ($5 bet)
curl -X POST https://rgs.test/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://rgs.test/api/rgs \
  -d "rquest=play&token=1|abc123...&game_session=SESSION_ID&game_id=bj&continue=1&action=hit"

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