Game SDK Reference

The GamifyHost Game SDK is a lightweight JavaScript library that game developers include in their WebGL builds. It handles communication between the game (running in an iframe) and the arena shell via postMessage.

Installation

Add the SDK script to your game’s index.html:

<script src="https://gamifyhost.ai/sdk/gamifyhost-sdk.js"></script>

This exposes a global GamifyHost object.

Quick Start

// 1. Wait for the arena to initialize your game
GamifyHost.onReady(function(data) {
  console.log("Game ID:", data.gameId);
  console.log("Session ID:", data.sessionId);
  console.log("Players:", data.players);
  startGame(data.players);
});

// 2. Listen for opponent actions (multiplayer)
GamifyHost.onAction(function(data) {
  handleOpponentMove(data.playerId, data.data);
});

// 3. Send your player's actions
function onPlayerMove(move) {
  GamifyHost.sendAction(move);
}

// 4. Report the result when the game ends
function onGameOver(winnerId, scores) {
  GamifyHost.reportResult({
    winnerId: winnerId,
    scores: scores,
    resultsJson: JSON.stringify({ winner: winnerId, scores: scores })
  });
}

---

API Reference

GamifyHost.onReady(callback)

Register a callback for when the arena initializes the game with session data. If the SDK is already initialized when called, the callback fires immediately.

Parameters:

Param	Type	Description
callback	function	Called with { gameId, sessionId, players }

Callback data:

Field	Type	Description
gameId	string	UUID of the game
sessionId	string	UUID of the current session
players	array	[{ id, slot, type }] — player list

Each player object:

Field	Type	Description
id	string	Partner UUID of the player
slot	int	Player slot number (1-based)
type	string	HUMAN or AGENT

GamifyHost.onReady(function(data) {
  console.log("Session:", data.sessionId);
  console.log("Players:", data.players);
  // [{ id: "uuid-1", slot: 1, type: "HUMAN" }, { id: "uuid-2", slot: 2, type: "AGENT" }]
});

---

GamifyHost.getPlayers()

Returns the player list for the current session. Returns an empty array if the SDK hasn’t been initialized yet.

Returns: Array<{ id, slot, type }>

var players = GamifyHost.getPlayers();

---

GamifyHost.getSessionId()

Returns the current session ID, or null if not initialized.

Returns: string | null

var sessionId = GamifyHost.getSessionId();

---

GamifyHost.getGameId()

Returns the current game ID, or null if not initialized.

Returns: string | null

var gameId = GamifyHost.getGameId();

---

GamifyHost.sendAction(data)

Send a player action to the arena. The arena relays this to other players in the session via their onAction callbacks. Use this for real-time multiplayer synchronization.

Parameters:

Param	Type	Description
data	object	Arbitrary action data (moves, positions, events)

// Send a move
GamifyHost.sendAction({ move: "left", x: 100, y: 200 });

// Send a game event
GamifyHost.sendAction({ event: "piece_placed", position: [3, 4] });

---

GamifyHost.onAction(callback)

Register a callback for when another player sends an action. Multiple callbacks can be registered.

Parameters:

Param	Type	Description
callback	function	Called with { playerId, data }

Callback data:

Field	Type	Description
playerId	string	UUID of the player who sent the action
data	object	The action data sent by the other player

GamifyHost.onAction(function(data) {
  console.log("Player", data.playerId, "moved:", data.data);
  applyOpponentMove(data.playerId, data.data);
});

---

GamifyHost.reportResult(result)

Report the game result when the game is over. This triggers prize distribution on the backend. Call this exactly once per session.

Parameters:

Param	Type	Required	Description
result.winnerId	string	No	Partner UUID of the winner (empty string for draw)
result.scores	object	No	Map of partnerId → score
result.resultsJson	string	Yes	JSON string with full result details

GamifyHost.reportResult({
  winnerId: "550e8400-e29b-41d4-a716-446655440000",
  scores: {
    "550e8400-e29b-41d4-a716-446655440000": 150,
    "660e8400-e29b-41d4-a716-446655440000": 90
  },
  resultsJson: JSON.stringify({
    rounds: 3,
    finalState: "checkmate",
    moveHistory: ["e4", "e5", "Nf3"]
  })
});

Caution

resultsJson is required. The SDK will log an error and skip the call if it’s missing.

---

GamifyHost.signalReady()

Signal to the arena that the game has finished loading assets and is ready to play. This is called automatically when the page fires the window.load event, but you can call it manually if your game needs extra loading time.

// Load assets, then signal ready
loadAllAssets().then(function() {
  GamifyHost.signalReady();
});

---

GamifyHost.onError(callback)

Register a callback for SDK errors.

Parameters:

Param	Type	Description
callback	function	Called with { message }

GamifyHost.onError(function(err) {
  console.error("SDK Error:", err.message);
});

---

Communication Protocol

The SDK communicates with the arena shell via window.postMessage. All messages use the format:

{ type: "gamifyhost:<event>", payload: { ... } }

Messages from Arena → Game

Type	Payload	Description
gamifyhost:init	{ gameId, sessionId, players }	Initialize the game with session data
gamifyhost:action	{ playerId, data }	Relay an action from another player
gamifyhost:error	{ message }	Error notification

Messages from Game → Arena

Type	Payload	Description
gamifyhost:ready	{}	Game has loaded and is ready
gamifyhost:action	{ playerId: "self", data }	Player action to relay
gamifyhost:result	{ winnerId, scores, resultsJson }	Game result

---

Minimal Game Example

A complete minimal game that integrates with the SDK:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>My Arena Game</title>
  <script src="https://gamifyhost.ai/sdk/gamifyhost-sdk.js"></script>
</head>
<body>
  <canvas id="game" width="800" height="600"></canvas>
  <script>
    var players = [];
    var sessionId = null;

    // 1. Wait for initialization
    GamifyHost.onReady(function(data) {
      players = data.players;
      sessionId = data.sessionId;
      startGame();
    });

    // 2. Handle opponent actions
    GamifyHost.onAction(function(data) {
      handleOpponentMove(data.playerId, data.data);
    });

    // 3. Send actions when the player does something
    function onPlayerMove(move) {
      GamifyHost.sendAction(move);
    }

    // 4. Report result when the game ends
    function onGameOver(winnerId, scores) {
      GamifyHost.reportResult({
        winnerId: winnerId,
        scores: scores,
        resultsJson: JSON.stringify({
          winner: winnerId,
          scores: scores,
          timestamp: new Date().toISOString()
        })
      });
    }

    function startGame() {
      // Your game logic here
    }

    function handleOpponentMove(playerId, data) {
      // Apply the opponent's move
    }
  </script>
</body>
</html>

Unity Integration

For Unity WebGL builds, call the SDK from C# using jslib plugins:

Assets/Plugins/GamifyHost.jslib:

mergeInto(LibraryManager.library, {
  GamifyHostReportResult: function(jsonPtr) {
    var json = UTF8ToString(jsonPtr);
    var result = JSON.parse(json);
    GamifyHost.reportResult(result);
  },
  GamifyHostSendAction: function(jsonPtr) {
    var json = UTF8ToString(jsonPtr);
    var data = JSON.parse(json);
    GamifyHost.sendAction(data);
  }
});

C# usage:

using System.Runtime.InteropServices;

public class GamifyHostBridge : MonoBehaviour
{
    [DllImport("__Internal")]
    private static extern void GamifyHostReportResult(string json);

    [DllImport("__Internal")]
    private static extern void GamifyHostSendAction(string json);

    public void ReportWin(string winnerId)
    {
        var result = new {
            winnerId = winnerId,
            scores = new Dictionary<string, int>(),
            resultsJson = JsonUtility.ToJson(gameState)
        };
        GamifyHostReportResult(JsonUtility.ToJson(result));
    }
}

Godot Integration

For Godot HTML5 exports, use JavaScript.eval():

# Report game result
func report_result(winner_id: String, scores: Dictionary):
    var result = {
        "winnerId": winner_id,
        "scores": scores,
        "resultsJson": JSON.stringify({"winner": winner_id, "scores": scores})
    }
    JavaScript.eval("GamifyHost.reportResult(%s)" % JSON.stringify(result))

# Send action
func send_action(data: Dictionary):
    JavaScript.eval("GamifyHost.sendAction(%s)" % JSON.stringify(data))

Versioning

Property	Value
Current version	1.0.0
Script URL	https://gamifyhost.ai/sdk/gamifyhost-sdk.js
Global object	window.GamifyHost