Skip to content
ZokoGames

Log in

Multiplayer and invites

Multiplayer and invites

The portal does not host your real-time traffic: your servers do. What the portal adds is the social layer around it. Signed-in players see an Invite friends tray under the game that lists their online friends with an Invite button, plus a Copy link button. Your game tells the portal which room the player is in, and the portal turns that into an invite.

The requirements are on the multiplayer page; the method reference is in the game module. This guide is the order to do it in.

How the pieces fit#

Piece What it does
updateRoom({ roomId, isJoinable, inviteParams }) Tells the portal "this player is in this room". The portal shows the invite tray as ready and keeps presence ("playing your game") for friends.
Invite (friend list) The host presses Invite on a friend; the friend gets an in-app notification. Accepting opens your game with the inviteParams as query parameters.
inviteLink(params) The game page's URL with your parameters added. Players paste it anywhere.
inviteParams / getInviteParam(key) What your game was opened with. Read them at start and join.
addJoinRoomListener(fn) Fires when an invite is accepted while your game is already open, so you can move the player into the room without a reload.
isInstantMultiplayer true when the page was opened with instantJoin=true ("play together"): skip the menu and go straight to a lobby.

Rooms and presence need a signed-in player. For guests, updateRoom succeeds and nothing is announced, so offer sign-in before an invite button.

1. Join from the page address#

await SDK.init();

const roomFromLink = SDK.game.getInviteParam("room");
if (SDK.game.isInstantMultiplayer) startMatchmaking();
else if (roomFromLink) joinRoom(roomFromLink);
else showMenu();

2. Announce the room you host#

Create your room on your server, then tell the portal. Use the same id you will put in the link.

async function hostRoom() {
  const room = await myServer.createRoom({ max: 4 });              // your own backend
  await SDK.game.updateRoom({
    roomId: room.id,                                               // letters, digits, _ . - (64 characters max)
    isJoinable: true,
    inviteParams: { room: room.id },                               // flat map of strings only
  });
  copyBtn.onclick = async () => navigator.clipboard.writeText(await SDK.game.inviteLink({ room: room.id }));
}

If you omit roomId, the portal generates one and always adds it to inviteParams as roomId. The portal caps the room capacity it shows at the game's maximum lobby size (up to 100).

3. Update and leave#

await SDK.game.updateRoom({ isJoinable: false });                  // room full or round started
await SDK.game.leftRoom();                                          // the player left the room

Call updateRoom again when the room changes, and leftRoom on exit, disconnect and when the game goes back to the menu.

4. Handle invites accepted mid-game#

SDK.game.addJoinRoomListener(async (params) => {
  if (currentRoom) await leaveCurrentRoom();
  await joinRoom(params.room);
});

5. Respect chat settings#

const apply = (s) => { chatPanel.hidden = s.disableChat; };
apply(SDK.game.settings);
SDK.game.addSettingsChangeListener(apply);

Chat needs moderation (a profanity filter and a report option) and must never render raw HTML from other players.

Test with two tabs#

  1. Serve the game on localhost and open http://localhost:8080/?sdk_debug=true.
  2. Host a room. In local mode inviteLink returns your own URL with the parameters added, for example http://localhost:8080/?room=abc.
  3. Open that link in a second tab (or an incognito window). getInviteParam("room") returns abc; check that your game joins.
  4. The local host does not simulate friends' invites or joinRoom events. To exercise them, load the game in the Preview tool and use the event log to confirm the updateRoom and leftRoom calls arrive, then test the real invite tray with two accounts on the live portal.

Checklist#

  • updateRoom on create and join; leftRoom on leave.
  • Parameters from inviteParams joined at start; join listener registered.
  • isInstantMultiplayer skips the menu.
  • Lobby sizes in the listing match the game; a full room sets isJoinable: false.
  • A dropped player does not freeze the room; your server being down shows a message, not a hang.

Something unclear, wrong or missing on this page? Tell us through support · Test your game in the preview tool