hizi docs

Appearance

Getting Started with hizi engine SDK ​

The hizi engine SDK (@hizi.io/engine-sdk) provides type-safe helper functions for your game frontend to communicate with a running hizi engine.

Installation ​

The SDK is published to the public npm registry — install it like any other npm package:

bash
npm install @hizi.io/engine-sdk
bash
pnpm add @hizi.io/engine-sdk
bash
yarn add @hizi.io/engine-sdk

How It Works ​

The hizi engine is already running and managed by hizi. Your frontend communicates with it through the hizi RGS platform:

plaintext
Your Game Frontend  ↔  HTTP/WebSocket  ↔  hizi RGS  ↔  hizi engine  ↔  output files

The backend handles outcome selection, balance management, authentication, and game state. You just make API calls and render results.

The Four Essential Calls ​

typescript
import { login, loadConfig, placeBet, collect } from '@hizi.io/engine-sdk';

// 1. Get launch parameters from the URL
const loginURL = new URLSearchParams(window.location.search).get('login');
const launchToken = new URLSearchParams(window.location.search).get('token');

// 2. Login - exchange launch token for session token
const loginResponse = await login({ loginURL, launchToken });
if (!loginResponse.success) throw new Error('Login failed');

const { token, backendURL, gameSettings } = loginResponse.result;

// Apply operator platform settings (stake limits, enabled features, UI rules).
// The engine does not re-enforce these — your frontend must honour them.
if (gameSettings) {
  applyStakeLimits(gameSettings.minStake, gameSettings.maxStake, gameSettings.customStakes);
  ui.setAutoplayEnabled(gameSettings.autoplayEnabled);
  ui.setGambleEnabled(gameSettings.gambleEnabled);
  // …see /sdk/endpoints#login for the full list
}

// 3. Load game configuration
const configResponse = await loadConfig({ backendURL, token });
if (!configResponse.success) throw new Error('Config load failed');

const config = configResponse.result.config;
console.log('Stakes:', config.stakes); // e.g. [10, 20, 50, 100]
console.log('RTP:', config.rtp); // e.g. 95

// 4. Place a bet
const stake = config.stakes[0];
const betResponse = await placeBet({ backendURL, token, stake });
if (!betResponse.success) throw new Error('Bet failed');

const gameResult = betResponse.result.result;
console.log('Scenario data:', gameResult.scenario); // your game-specific data
console.log('Total win:', gameResult.totalWin); // win multiplier

// 5. Handle multi-step rounds
if (gameResult.engineData.inProgress) {
  // Call placeBet again to continue
  const nextResponse = await placeBet({ backendURL, token });
}

// 6. Collect winnings when available (games with wager features)
if (gameResult.engineData.canCollect) {
  const collectResponse = await collect({ backendURL, token });
}

TIP

Every response has a success boolean. Always check it before accessing result. See Error Handling for details.

What You Need ​

  • Access credentials to hizi Backoffice
  • A frontend game client (HTML5, React, Unity, etc.)
  • TypeScript recommended for type safety

Next Steps ​