Build multiplayer without a server.

GameRelay gives a browser game rooms, lobbies, parties, chat, leaderboards and saves, and an SDK that owns the netcode: you declare what exists and who owns it, and it syncs, smooths and hands over. One player’s browser is the host; if it leaves or hides its tab, another player takes over without losing anything. This page covers the JavaScript SDK and the REST API your backend can call.

Quickstart

1. Sign in and create an instance for your game.
2. Copy its public key (gr_pub_…). It is safe to ship in the game. To stop other sites from reusing it, list your game's sites under Allowed origins on the instance (e.g. https://mygame.com, https://*.itch.zone; localhost matches any port).
3. Paste this into your page and open it in two tabs:

<canvas id="c" width="640" height="400"></canvas>
<script src="https://gamerelay.io/sdk/gamerelay.js"></script>
<script type="module">
  const c = document.getElementById('c');
  const relay = await GameRelay.connect({ publicKey: 'gr_pub_…' });
  const room = await relay.quickMatch({ maxPlayers: 4 });
  const dots = room.define('dot', { x: 'number', y: 'number' });
  const me = dots.spawn({ x: 320, y: 200 });           // yours: just write it
  c.onpointermove = (e) => { me.x = e.offsetX; me.y = e.offsetY; };
  const ctx = c.getContext('2d');
  (function draw() {
    ctx.clearRect(0, 0, 640, 400);
    for (const d of dots.all()) ctx.fillRect(d.x - 4, d.y - 4, 8, 8); // everyone's, smoothed
    requestAnimationFrame(draw);
  })();
</script>

Each tab is its own player, so two tabs are enough to test. For a whole game, start from one of the three starters in llms.txt (see Pick your shape). The arena demo (mixed) and Blocky Cup (host simulates) are complete games.

Concepts

Instance

One per game. It has a public key for the game and a secret key for your backend only, plus settings (chat, parties, saves, room size, allowed origins, direct connections).

Room

Players who play together, joined by quick match, a code or a public room list. A player is in one room at a time.

Host

One player’s browser runs the host’s work: host entities, timers and room.state. If it leaves, hides its tab or freezes, GameRelay moves the role to another player, who carries on from there.

Entities, events, state

Things that move or last (ships, balls, coins) are entities: one owner writes each, everyone else sees it smoothed. Moments (a shot, a hit) are events. Facts (score, round) are state.

Use player.slot for sides, colours and spawn points, never isHost: the host can change mid-game.

Pick your shape

Every multiplayer game mixes the same few pieces. Pick the row closest to yours: llms.txt has a complete starter for each, and the MCP tool get_starter_game serves them too.

JavaScript SDK

Load it with a script tag, which exposes window.GameRelay, or install it with npm i @gamerelay/sdk and import { GameRelay } from '@gamerelay/sdk'. It has no dependencies, is fully typed, and is about 28 KB gzipped.

Connecting

await GameRelay.connect(options) returns a Relay. It reconnects on its own and puts the player back in their room.

Players are anonymous by default. If your game has accounts, mint tokens on your backend (see Player token):

// your server
const res = await fetch('https://gamerelay.io/v1/auth/token', {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.GAMERELAY_SECRET_KEY}` },
  body: JSON.stringify({ playerId: user.id, playerName: user.name }),
});
const { token } = await res.json();

// your game
const relay = await GameRelay.connect({
  getToken: () => fetch('/my/gamerelay-token').then((r) => r.text()),
});

Entities

const ships = room.define('ship', { x: 'number', y: 'number', h: 'angle', alive: 'flag' });
const me = ships.spawn({ x: 100, y: 100, h: 0, alive: true }); // you own it
me.x += 5;                                  // write fields; the SDK sends changes ~20/s
for (const s of ships.mine()) s.x += speed * dt; // update only what you own (others' are skipped, with a warning)
for (const s of ships.all()) draw(s);       // draw every one: yours live, others smoothed ~100 ms behind
ships.on('remove', (s, reason) => explode(s)); // 'removed' | 'left' | 'expired'
me.teleport();                              // after a respawn: everyone snaps, no slide

// The host owns the world; the next host carries on from where it was.
const coins = room.define('coin', { x: 'number', y: 'number' });
if (room.isHost) coins.spawn({ x, y }, { owner: 'host' });

Field types: 'number' and 'angle' are smoothed; 'flag', 'text' and 'value' (any JSON) change at their moment. Only the owner writes an entity: update over kind.mine() and draw over kind.all(). Keep local-only values (cooldowns, input) in your own variables, not on the entity. A disconnected player’s entities freeze until they’re back; when they leave, their entities go, unless spawned with { onLeave: 'host' }. In TypeScript the handle is typed from your fields.

Events, requests & claims

room.emit('fire', { x, y, a });              // everyone, you included (echo)
room.on('fire', ({ x, y, a }, from) => spawnBullet(from, x, y, a));

room.onRequest('buy', ({ item }, from) => {  // on every player: the host answers
  if (!canAfford(from, item)) throw room.reject('Not enough gold');
  return { item };
});
const { item } = await room.request('buy', { item: 'sword' });

if (await room.claim(coin.id)) score++;     // exactly one player gets true

Events echo to the sender, so handle an action in one place. Requests reject with rejected, host_changed or timeout (5 s). A claim is held until released or its holder leaves; use one key per thing.

Inputs

room.input({ left, right, jump });            // every frame, on every player
relay.tick(60, (dt) => {
  if (!room.isHost) return;
  for (const p of room.players) move(p.id, room.inputs.get(p.id), dt); // neutral after 500 ms of silence
});

relay.tick(rate, fn) runs at a fixed step and keeps going in hidden tabs, so a hidden host keeps the game running. Draw in requestAnimationFrame.

State, timers & teams

room.setState({ score: [1, 0] });            // host only; everyone gets 'state'
room.timer('round', 60_000);                // host only: fires once, even across host changes
room.on('timer', 'round', endRound);
room.timeLeft('round');                     // ms left, for countdowns
if (room.isHost) room.assignTeams(2);       // balanced; joiners placed automatically
room.teamOf(playerId);

Debugging

GameRelay.connect({ …, debug: true }) shows an overlay (ping, smoothing delay, traffic, entities, host). Warnings print either way, once each, with the fix and the llms.txt section to read:

• room.on('playerJoined') and other guessed names: the built-in is player_joined
• positions sent with room.send() more than 20×/s: use entities (room.define, then its .spawn())
• room.setState() more than 10×/s, or one event type more than 30×/s: state and events are for facts and moments
• room.all('shp') for a kind that was never defined (with the closest name)
• a respawn without teleport(); fields that differ between players (different builds)
• a write to someone else’s entity, an undeclared field or the wrong type: the write is skipped, and your game keeps running
• the room at 1,024 entities or 1,024 claims; a request repeated while the first waits
• the server dropping messages over 120/s; the tick loop falling back to setInterval

simulate: { latency, jitter, loss } tests on a bad network.

Relay

Room

Invite links

Put the room code in the page URL and send the link: friends who open it join your room. An old link can point at a room that has closed, so catch joinInvite() and fall back.

// Join the room in this page's link (?room=CODE), or start one.
const room = (await relay.joinInvite().catch(() => null)) ?? (await relay.createRoom({ maxPlayers: 4 }));
history.replaceState(null, '', room.inviteUrl()); // the address bar is now the invite link

inviteButton.onclick = () => room.shareInvite();

Every room also has a short link, gamerelay.io/<game>/<link> once you set a slug and a play URL on the instance (Short links): room.shareLink(). It previews in chat apps with the room's name and your cover image, and sends players to your play URL with ?join=, which joinInvite() joins. A room made with linkOnly: true is joined by its link only, so nobody gets in by guessing its code.

Events

Subscribe with relay.on(…) or room.on(…). Your own event names (room.emit) use the same room.on.

Saves & leaderboards

await relay.storage.set('best', { score: 1200 });
const best = await relay.storage.get('best'); // null if unset

const { rank, improved } = await relay.leaderboard.submit('points', 1200);
const { entries, me } = await relay.leaderboard.top('points', { limit: 10 });
// Lower is better: fix the order on the board's first submit.
await relay.leaderboard.submit('fastest-lap', 41.73, { order: 'asc' });

Saves are any JSON value per player, per game. Leaderboards keep each player’s best score; ties share a rank, and top() includes your own entry as me even outside the top. Both need the “Persisted data” setting (on by default). Scores come from the browser, so they suit casual games. To make faking one a hassle, give a board rules in the dashboard (instance → Leaderboards): a score range, a maximum per minute of play, a minimum play time, “only while in a room” and a cooldown. A score that breaks one fails with rejected, and the reason shows in your logs.

Chat

room.on('chat', ({ name, text }) => addLine(name, text)); // render as text, never HTML
for (const m of room.chatHistory) addLine(m.name, m.text);
room.chat('gg');

Names and avatars come from the player’s token, so nobody can chat as someone else. Lines are single-line, at most 120 characters.

Errors

Calls reject with a GameRelayError that has a code and a message:

REST API

Base URL https://gamerelay.io. Bodies are JSON. Endpoints that act for your game take the instance secret key as authorization: Bearer gr_sk_…; call them from your backend only. Errors look like { "error": "unauthorized", "message": "Invalid secret key" } with a matching HTTP status.

curl -X POST https://gamerelay.io/v1/auth/anonymous \
  -H 'content-type: application/json' \
  -d '{ "publicKey": "gr_pub_…", "playerName": "ada" }'

{
  "token": "eyJhbGciOiJIUzI1NiIs…",
  "playerId": "p_x7k2m9q4w1ab",
  "name": "ada",
  "avatar": null,
  "expiresAt": 1790000000000
}

curl -X POST https://gamerelay.io/v1/auth/token \
  -H "authorization: Bearer $GAMERELAY_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "playerId": "user_42",
    "playerName": "Ada",
    "playerAvatar": "https://example.com/ada.png",
    "ttlSeconds": 3600,
    "claims": { "role": "admin" }
  }'

curl -X POST https://gamerelay.io/v1/rooms/K7QM/kick \
  -H "authorization: Bearer $GAMERELAY_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{ "playerId": "user_42", "message": "Be nice", "ban": true }'

curl -X POST https://gamerelay.io/v1/rooms/K7QM/close \
  -H "authorization: Bearer $GAMERELAY_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{ "message": "Server maintenance" }'

Webhooks

Add a webhook in the dashboard (instance → Webhooks) and GameRelay POSTs signed JSON to your backend when things happen. Production URLs must be https:// on port 443. Deliveries that don’t get a 2xx within 5 seconds are retried with backoff for about 8½ hours. Webhooks notify; they can’t block or change the game.

room is { id, code, tag, isPublic, maxPlayers }. Every delivery is an envelope:

{
  "id": "evt_…",           // use to ignore duplicates (delivery is at least once)
  "type": "player.joined",
  "version": 1,
  "createdAt": 1790000000000,
  "instanceId": "ins_…",
  "data": { "room": { … }, "player": { "id": "…", "name": "…", "claims": null }, "resumed": false }
}

Verify every request. The gamerelay-signature header is t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of `${t}.${rawBody}` with the webhook’s signing secret (whsec_…):

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyGamerelay(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay window
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return v1?.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Limits

Experimental: player to player

Players' browsers can also send broadcasts straight to each other over WebRTC, racing the server's copy, so they arrive sooner. Everything still goes through the server as well, so remote players, metering and state work as before. It's on by default (lan: false turns it off), it's for rooms of up to 8, and it may change or be removed. It isn't in llms.txt yet.

// On by default: each pair takes its best route (direct on one network, else our relay).
const relay = await GameRelay.connect({ publicKey });

// Also directly over the internet, between members of your party only:
// GameRelay.connect({ publicKey, lan: { direct: 'party' } })

// Off: everything through the server only.
// GameRelay.connect({ publicKey, lan: false })

• Same network: players connect directly, sharing only local addresses (usually hidden names).
• Different networks: players connect through our nearest relay, when the server has one. Players don't see each other's IP address.
• Party members (direct: 'party'): members of your party may also connect directly over the internet, which shows each of them the other's public IP address. Only party members get it, not other players in the room. It also needs the instance's Direct connections setting turned on in the dashboard (off by default).

Before using direct: 'party', ask each player in your game, for example "Connect directly with your party? They'll be able to see your IP address.", and only pass it for players who agree. Don't use it in games children under 13 may play. See the Privacy Policy and Terms.

Plans

Limits apply per account, across all of its games. Traffic is what GameRelay sends to your players and resets on the 1st of each month (UTC). On the Free plan, new players are turned away (quota_exceeded) once it is used up; players already in a game are never kicked. GameRelay is in alpha, so prices and limits may change.

For AI agents

llms.txt is this guide as one plain-text file, written for LLMs: give it to your agent before it writes GameRelay code. Two MCP servers (Streamable HTTP) cover the rest:

• https://gamerelay.io/mcp: the guide, a starter game and a key check. No account.
• https://gamerelay.io/mcp/admin: everything in the dashboard, as you (create instances, change settings, read logs, moderate rooms, manage webhooks). The first call opens your browser to sign in.

claude mcp add --transport http gamerelay https://gamerelay.io/mcp
claude mcp add --transport http gamerelay-account https://gamerelay.io/mcp/admin