Documentation — Igrax SDK
Igrax Game SDK

How to build a game
for the Igrax platform

Igrax games are written in plain JavaScript — no frameworks needed. Below is the full API — or copy the AI prompt and let ChatGPT, Claude, or Gemini build the game for you.

Connect ChatGPT, Claude or Cursor directly (MCP)Instead of copying files, let your AI assistant create and edit games in your igrax account through https://igrax.com/mcp. Step-by-step setup for every tool →
AI Chat Prompt

Paste this prompt at the start of a conversation with ChatGPT, Claude, or Gemini. Then describe what you want — e.g. "Build me a quiz game with 5 questions" or "A game where players tilt their phone to drive a car".

You are an assistant for building games on the Igrax platform. Igrax is a real-time multiplayer party game platform. One device (TV) displays the game as the HOST screen, while players connect with their phones... Game format uses .igx files (plain JavaScript): types.igx — TypeScript interfaces game.igx — shared code, loaded first host.igx — TV screen logic player.igx — phone controller game.conf.json — metadata
File Structure
types.igx
TypeScript interfaces — GameState, ActionMap, payload types. Documentation only.
not executed
game.igx
Shared code — constants, helpers. Available in both host.igx and player.igx.
loaded first
host.igx
Game logic and TV screen rendering. Contains onStart, onAction and render.
executed
player.igx
Phone display and controls. Contains render and uses sendAction.
executed
game.conf.json
Metadata — name, description, icon, color, min/max players, version.
configuration
host.igx — API
Required functions
onStart(players)
Called once when the game starts. Returns initial game state (must be JSON-serializable).
onAction(playerId, action, payload, state)
Called on every player action. Returns the new state. Must be a pure function.
render(state, players)
Returns an HTML string displayed on the TV screen.
Available functions
endGame()
End the game and show results.
setTimer(sec, cb)
One-shot timer. Belongs to the current state — cleared when the next state arrives, so re-arm it in onUpdate for a game loop.
Optional — real-time canvas games
onUpdate(state, players)
The host iframe loads once and then receives every new state by message. If you define onUpdate, it is called instead of replacing the DOM — return a <canvas> from render() once, run a requestAnimationFrame loop and draw from the latest state. Smooth movement, sprites, particles. player.igx may define onUpdate(state, me, players) the same way.
player.igx — API
Required functions
render(state, me, players)
Returns an HTML string displayed on this player's phone.
Automatically available
sendAction(action, payload)
Sends an action to the host. The only way for player → host communication.
me
This player: { id, name, avatar }
state
Always fresh game state (synced with host).
players
List of all players in the room.
Gamepad — PS4 / Xbox / Nintendo

The platform detects Bluetooth/USB controllers on phones and on the host TV — your game never touches the Gamepad API. A controller on the host joins as a normal player (master-gamepad, 🎮), so a game can start with zero phones. Every input reaches onAction as action 'gamepad':

Payloads
{ dir }
D-pad or left stick — 'up' | 'down' | 'left' | 'right'; fires on press, then auto-repeats every ~150 ms while held.
{ button, pressed }
Any button on press (true) and release (false): a b x y l1 r1 l2 r2 select start l3 r3 up down left right. PS4: a = ✕, b = ○, x = □, y = △, select = Share, start = Options.
Pattern — map it onto your own actions
if (action === 'gamepad') { if (payload.dir) return onAction(playerId, 'move', { direction: payload.dir }, state); if (payload.pressed && payload.button === 'a') return onAction(playerId, 'tap', {}, state); return state; }
Rules and Constraints
  • 1
    No imports — all code must be self-contained. No import/export/require.
  • 2
    Serializable state — game state may only contain string, number, boolean, array, plain object. No classes, functions, or DOM elements.
  • 3
    onAction must be a pure function — receives state, returns new state. No side effects, no global mutation.
  • 4
    render() returns an HTML string — may contain inline CSS and event handlers (onclick, onmousedown...), but no external scripts.
  • 5
    game.igx loads first — all var and function declarations from game.igx are available in host.igx and player.igx without any imports.
  • 6
    Handle the gamepad action — map 'gamepad' onto your own actions, or return state unchanged.
  • 7
    Saving progress — declare "saves": { "slots": ["progress"] } in game.conf.json, read players[i].profile.saved in onStart and call igrax.save(playerId, slot, data) in onAction. Max 10 slots × 64 KB, no personal data. Preview simulates saving (restart loads it).
  • 8
    Publishing — Play privately puts your current draft on your own TV (no review). Submit for review stores an immutable version; exactly that version is what gets published after review.