External Game Engines

An external game engine is a game engine that you host on your own infrastructure, outside the hizi.io platform. The hizi.io Remote Gaming Server (RGS) sends the game requests of the player to your engine over HTTP. Your engine calls the Game Studio API V2 to start and end gamerounds, to move money, and to get random numbers.

This page tells you how to connect an external engine, from an empty project to the first bet. Start with the external game engine template. The template is a minimal slot engine. It has two hosting options: a Cloudflare Worker or a self-hosted Node server. Both options use the same game logic.

Jurisdiction restrictions

Some jurisdictions might not allow this external hosting setup. Contact us for further instructions before you use it in production. We can confirm the hosting and deployment requirements for your target jurisdictions.

What you build

You build and host two parts. hizi.io supplies the third part.

Part	Who hosts it	What it does
Frontend	You	The game that the player sees in the browser. It gets a token at launch and sends all game requests to the RGS.
Game engine	You	The game logic. It receives the game requests from the RGS, calculates the result, and books it through the Game Studio API V2.
RGS	hizi.io	It launches the game, checks the token of the player, sends the game requests to your engine, and connects to the wallet of the operator.

Your frontend never calls your engine directly. The RGS is always between the two.

How the calls flow

The diagram shows one bet, from the game launch to the result.

text

Player browser             hizi.io RGS                     Your game engine
(your frontend)
      |                         |                                  |
      |-- GET {login}?token= -->|                                  |
      |<-- token, backendUrl ---|                                  |
      |                         |                                  |
      |-- POST backendUrl ----->|                                  |
      |   {op: "placeBet",      |-- POST {base URL}/placeBet ----->|
      |    token, stake}        |   (signed, with tokenData)       |
      |                         |                                  |
      |                         |<-- POST {V2 API}/getRandomResult-|
      |                         |--- random numbers -------------->|
      |                         |<-- POST {V2 API}/startGameRound -|
      |                         |--- result, new balance --------->|
      |                         |                                  |
      |                         |<-- reply for the frontend -------|
      |<-- reply ---------------|                                  |

The operator launches the game. The RGS opens your game launch URL with two query parameters: token (a short-life token) and login (the URL of the connect call). See Game Launch.
Your frontend calls the login URL with the token. The RGS returns a long-life token and the backendUrl. The backendUrl is an RGS address, not the address of your engine.
Your frontend sends each game request as a POST to backendUrl. The body holds the operation name in op, the long-life token in token, and the data of your game (for example stake).
The RGS checks the token. Then it sends the request to {game engine base URL}/{op}. It adds the data of the token in tokenData.
Your engine calculates the result. It calls the Game Studio API V2 to get random numbers and to book the debit and the credit.
Your engine returns its reply. The RGS sends the reply to the frontend.

Values you need

Collect these values before you deploy.

Value	Where you get it	Where it goes
Game code	You choose it when you create the game in the hizi app.	The routes of your engine. The template uses `game-readme`.
Game provider ID	The hizi.io back office (the hizi app). It identifies your Game Studio.	The `GAMEPROVIDER_ID` setting of your engine. It is the `X-H-AUTH-ID` header of each call.
Game provider secret	The hizi.io back office (the hizi app), with the game provider ID.	The `GAMEPROVIDER_SECRET` setting of your engine. Keep it secret. Do not put it in your frontend or in your repository.
V2 API endpoint	The API host of your hizi.io environment, followed by `/gameapi/v2`. Example: `https://api.<site>/gameapi/v2`. Contact hizi.io support if you do not know the host of your environment.	The `V2_API_QUEUE` setting of your engine.
Engine URL	The public HTTPS address of your deployed engine.	The Game engine base URL field in the hizi app.
Frontend URL	The public HTTPS address of your frontend.	The Game launch URL field in the hizi app.

The V2 API endpoint ends in /gameapi/v2

The endpoint is not the API host alone, and it does not end in /v2 alone. With a wrong path, every call to getRandomResult and startGameRound returns HTTP 404.

Calls your engine receives

The RGS calls these routes below the game engine base URL.

Route	Signed	Required	What it does
`GET /health`	No	Yes	Returns HTTP 200 and a JSON object. The RGS and monitoring tools use it.
`GET /certifiedfiles`	No	For some jurisdictions	Returns the hashes of your certified files.
`GET /getGameConfiguration`	Yes	For freeplay	Returns the stakes and the currency settings of the game.
`POST /getGameResult`	Yes	Yes	Returns an HTML view of one gameround for the support team of the operator.
`POST /doAutoClose`	No	Yes	Closes a gameround that the player did not finish.
`POST /{op}`	Yes	Your choice	Your own game operations. The template has `loadConfig` and `placeBet`. The value of `op` that your frontend sends is the name of the route.

Calls to be implemented by games gives the request, the response and the signature check of each standard route. Leave health and certifiedfiles open to all IP addresses.

Calls your engine sends

Your engine calls the Game Studio API V2 at the V2 API endpoint. Sign each call with the game provider ID and secret. See Signing a POST request.

Call	When
`/getRandomResult`	Get certified random numbers for the result. The template uses this call.
`/startGameRound`	Start the gameround and debit the stake. Optionally credit the win and close the gameround in the same call.
`/addWin`	Credit a win to an open gameround.
`/endGameRound`	Close an open gameround.

All amounts are in minor units (1/100 of the currency). Calls provided by API V2 lists all calls.

Set up the engine

Clone the template repository.
Run the engine locally. Follow the README of your hosting option. Check that GET {engine URL}/{game code}/health returns HTTP 200.
Set V2_API_QUEUE, GAMEPROVIDER_ID and GAMEPROVIDER_SECRET to the values for your environment. For the Cloudflare Worker, put V2_API_QUEUE in wrangler.toml. Put the ID and the secret in Worker secrets (wrangler secret put). For the Node server, put all three in .env or in the environment of the container.
Deploy the engine and the frontend to public HTTPS URLs that the RGS can reach.
Create the game in the hizi app. Set the fields as shown in Configure the game in the hizi app.
Launch the game in demo mode from the hizi app. Place one bet. Check the result in the checklist.

Replace the demo credentials

If you do not set GAMEPROVIDER_ID and GAMEPROVIDER_SECRET, the template uses demo credentials from src/config.ts. Those credentials do not work on your environment.

Configure the game in the hizi app

Set these two fields on the game. The Game launch URL points to your frontend. The Game engine base URL points to your engine. The RGS adds the operation name to the engine base URL when it calls your engine.

Cloudflare Worker. Replace <account> with your Cloudflare account subdomain.

Field	Example value
Game launch URL	`https://game-readme-engine-example.<account>.workers.dev/frontend/`
Game engine base URL	`https://game-readme-engine-example.<account>.workers.dev/game-readme`

For example, the RGS calls https://game-readme-engine-example.<account>.workers.dev/game-readme/placeBet to place a bet.

Self-hosted Node server. Replace engine.example.com and games.example.com with your own hosts.

Field	Example value
Game launch URL	`https://games.example.com/game-readme/index.html`
Game engine base URL	`https://engine.example.com/game-readme`

Do not end the game engine base URL with a /. Do not add an operation name to it.

Check your integration

Do these checks in this sequence. Each check finds a different problem.

Check	Expected result	If it fails
`curl {game engine base URL}/health` from a computer outside your network	HTTP 200 and a JSON object	The RGS cannot reach your engine. Check the URL, the DNS, the TLS certificate and your firewall.
Launch the game in demo mode	The frontend shows a balance	The `connect` call failed. Check the game launch URL. Check that your frontend reads `token` and `login` from the query string.
Place one bet	The frontend shows a result	Read the logs of your engine. Use the table below.
Look at the gameround in the hizi app	The gameround is closed, with the correct debit and credit	Your engine did not close the gameround. Set `endGame` on `startGameRound`, or call `endGameRound`.

Symptom	Usual cause
The RGS gets HTTP 404 from your engine	The game engine base URL is wrong, or it ends with `/`. Or the route for that `op` does not exist.
Your engine gets HTTP 404 from the RGS	`V2_API_QUEUE` does not end in `/gameapi/v2`.
Your engine gets an error about the signature	The game provider ID or secret is wrong, or the template still uses the demo credentials. See Signing a POST request.
The bet fails with an error code	See Response Codes & Error Codes.

Where to read more

Basics: the integration models and the flow of information.
Game Launch: the launch URL and the connect call.
Calls to be implemented by games: the routes your engine must answer.
Calls provided by API V2: the calls your engine sends.
Signing a POST request: how to sign your calls.
Lost Responses & Retries: what to do when a call gets no response.

External Game Engines ​

What you build ​

How the calls flow ​

Values you need ​

Calls your engine receives ​

Calls your engine sends ​

Set up the engine ​

Configure the game in the hizi app ​

Check your integration ​

Where to read more ​