Voidrush SDK – Setup

The SDK provides a high-level WebSocket client for your HTML5/Unity (WebGL) games: auto-connect, presence management, real-time and turn-based messaging.

1) Including the SDK

Serve the UMD bundle directly:

<script src="https://games.voidrush.com/sdk/voidrush-sdk.umd.js"></script>

The bundle exposes window.VoidrushSDK: VoidrushClient, SimpleGameClient, AutoJoinClient, TurnBasedGameClient, and helpers (createClient, createAutoJoinClient, etc.).

2) Getting a Token & a Room

On the platform side, the endpoint POST /api/games/<slug>/auto-join/ returns a short-lived token and the WS URL:

curl -X POST https://voidrush.com/api/games/<slug>/auto-join/ \
  -H "X-CSRFToken: ..." -H "Cookie: sessionid=..."

JSON Response: { success, token, room_id, ws_url }.

3) “1-Line” Connection (Auto-Join)

If your game page is opened with ?token=..., the client can extract it automatically and construct the WS URL:

<script>
  const client = VoidrushSDK.createAutoJoinClient({
    gameId: "YOUR_GAME_ID",     // required for security
    // optional: room, wsUrl (otherwise inferred from URL)
  });
  client.connect();
</script>

The client requires a non-empty gameId and can infer token from the query string. It can also derive room and the WebSocket URL if you don't pass them.

4) Manual Quick-Start

If you prefer to pass everything as parameters:

<script>
  const client = new VoidrushSDK.VoidrushClient({
    gameId: "YOUR_GAME_ID",
    token:  "<TOKEN_BACKEND>",
    room:   "lobby-1",
    wsUrl:  "wss://games.voidrush.com/ws/games/<slug>/lobby-1/?token=<TOKEN_BACKEND>"
  });

  client.on("open",   () => console.log("WS open"));
  client.on("close",  () => console.log("WS closed"));
  client.on("error",  (e) => console.error(e));
  client.on("message",(m) => console.log("server:", m));
  client.connect();
</script>

The client exposes connect(), close(), send(type, data, opts), on(event, cb), off(event, cb), and provides high-level helpers (see below).

5) Essential Helpers

• ready(): marks the player “ready” and triggers a presence update.
• joinTeam(team): joins any logical team (string).
• requestSync(): requests the current room state.
• updateGameState(patch) / updateBatch(updates): updates the game state server-side.
• sendCustomMessage(type, data): sends your “custom.*”, “game.*”, etc. messages.

6) Turn-Based

A specialized client wraps turn-based game actions:

<script>
  const tb = VoidrushSDK.createTurnBasedClient({ gameId: "YOUR_GAME_ID" });
  tb.connect().then(() => {
    tb.sendMove({ from: "A2", to: "A3" });
    tb.endTurn();
    // tb.claimVictory("opponent_disconnected");
  });
</script>

This client constructs game.action messages with action_type (move / end_turn / victory_claim), which the server validates and relays.

7) Client-Side Events

The SDK triggers callbacks upon receiving key messages (e.g., room.state, game.data, game.turn_move, etc.). Example:

<script>
  client.on("message", (msg) => {
    if (msg.type === "room.state") { /* render lobby */ }
    if (msg.type === "game.data")  { /* merge state */ }
    if (msg.type === "game.turn_move") { /* apply move */ }
  });
</script>

These types are emitted by the Channels consumer (server).