Add multiplayer

​

Before you start

• Your game loads @opengamehq/sdk and calls og.init(). Connect the SDK covers that.
• For local tests, one browser with two tabs open on the same page.
• For network tests, two browsers on different networks and either a published release or the private preview of a ready release, with multiplayer.mode set to p2p.

​

Host and join a room

{
  "multiplayer": {
    "mode": "p2p",
    "maxPlayers": 4
  }
}

import { og } from "@opengamehq/sdk";
import {
  multiplayer,
  RoomError,
} from "@opengamehq/sdk/multiplayer";

await og.init();

const room =
  (await multiplayer.joinInvite()) ??
  (await multiplayer.host({ maxPlayers: 4 }));

if (room.role === "host") {
  showInvite(room.code, room.inviteUrl);
}

const room = await multiplayer.join(code);

// A Cancel button calls controller.abort().
const controller = new AbortController();

try {
  const room = await multiplayer.join(code, {
    signal: controller.signal,
  });
  startGame(room);
} catch (error) {
  if (!(error instanceof RoomError)) {
    throw error;
  }
  showJoinError(error.code, error.retryable);
}

​

Test with two players

1. Open your game locally in two tabs of one browser. Host in one, then join in the other with the code or by opening room.inviteUrl. This tests game logic only: rooms run over BroadcastChannel, no broker is involved, and each tab gets a random guest ID in place of og.player.id.
2. Open a published release, or the private preview of a ready release with multiplayer.mode set to p2p, in two browsers on different networks. For a private preview, sign both browser profiles in to the creator account.
3. Host in one browser and join from the other.
4. Send reliable messages and unreliable snapshots both ways.
5. Close one peer and confirm the game recovers.

​

Send messages

room.on("join", (peer) => {
  addPlayer(peer.slot, peer.player);
});
room.on("leave", (peer) => removePlayer(peer.slot));
room.on("message", (peer, data, channel) => {
  receive(peer, data, channel);
});
// The room is gone, for any reason.
room.on("close", (reason) => showEnded(reason));

// Reliable and ordered.
room.send({ type: "ready" });
// Latest wins: use for snapshots.
room.send({ x: 2, y: 3 }, { reliable: false });
// Every peer.
room.broadcast({ type: "round", n: 3 });
// One peer.
room.on("join", (peer) => {
  room.send({ type: "welcome" }, { peer: peer.id });
});

• A message is finite JSON, at most 24 levels deep and at most 16 KiB once wrapped.
• send returns { sent, dropped, closed }. It throws only for a payload that can never be sent.
• When a peer falls behind, unreliable sends to it stop once 64 KiB is queued, and the peer is disconnected at 1 MiB.
• peer.player comes from the broker’s signed ticket, not from the peer, so a guest cannot claim someone else’s name or slot. peer.slot stays with a player, so one who reconnects gets theirs back. peer.seat counts from zero and is reused after someone leaves, so use it for colours and spawn points.
• Without a migration adapter, losing the host ends the room. Handle close. host-left fires first when the host leaves on purpose.

​

Room events

​

Use the OpenGame lobby

const room = await multiplayer.lobby({
  minPlayers: 2,
});
startGame(room);

​

Offer room settings

{
  "multiplayer": {
    "mode": "p2p",
    "maxPlayers": 4,
    "lobby": {
      "settings": [
        {
          "key": "map",
          "label": "Map",
          "kind": "map",
          "default": "garden",
          "choices": [
            { "id": "garden", "label": "Garden" },
            { "id": "rooftop", "label": "Rooftop" }
          ]
        },
        {
          "key": "round_length",
          "label": "Round length",
          "kind": "choice",
          "default": "short",
          "choices": [
            { "id": "short", "label": "Short" },
            { "id": "long", "label": "Long" }
          ]
        }
      ]
    }
  }
}

applySettings(room.configuration);
room.on("configuration", ({ selection }) => {
  applySettings(selection);
});

​

Start a round together

// Host
room.phase("countdown", {
  delayMs: 3000,
  waitForReady: true,
});

// Every peer, in the game loop. phaseState is
// { epoch, name, at }, and `at` stays null until
// every player is ready, because of waitForReady.
const { name, at } = room.phaseState;
const due = at !== null && room.now() >= at;
if (name === "countdown" && due) startRound();

​

Restore the match after losing the host

const migration = {
  schema: "my-game-v1",
  checkpoint: () => captureMatch(),
  restore: async (state, { epoch, role }) => {
    await restoreMatch(state);
    setAuthority(epoch, role);
  }
};

const room = await multiplayer.host({
  maxPlayers: 4,
  migration,
});
// Guests pass the same adapter:
// multiplayer.join(code, { migration })

room.on("migrating", () => pauseMatch());
room.on("authority", ({ role }) => {
  resumeMatch(role);
});

​

Check connection quality

const stats = room.stats();
const { rtt, loss, relay, relayReason } = stats;

​

Keep the host in charge

• Guests send inputs, not outcomes. Send “fired at this angle”, not damage numbers or “I hit them”. The host works out the result.
• Validate every message against one table that sender and receiver both import, and drop anything with an extra key. defineMessages in @opengamehq/sdk/netcode does this.
• Send the last few inputs with every packet, and apply no more of a guest’s inputs than host ticks have passed. InputHistory resends them and InputQueue drops repeats, but drain returns everything pending. Applying all of it lets a guest move several times per tick by sending more commands, which is a speed hack the host runs for them. Give each guest one move per tick, banked for a few ticks so inputs delayed by a lost packet still count, as guest-inputs.js in the repository’s templates/multiplayer starter does. The starter is not in the CLI or SDK package; ask the team for it if you have no repository.
• Quantise on a grid with an exact zero. Without one, an idle guest drifts. Use symmetricQuantizer.
• Calculate the lag-compensation window from round trip, snapshot age, interpolation delay and jitter. Use lagCompensationMs.
• Correct the simulation at once and smooth only the camera. Use smoothCamera, cyclicLerp for angles, and extrapolateScalar with a cap.

​

Fix a problem

​

Fix by error code

​

Fix by symptom

​

Where next