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 roomCall 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#
- Serve the game on
localhostand openhttp://localhost:8080/?sdk_debug=true. - Host a room. In local mode
inviteLinkreturns your own URL with the parameters added, for examplehttp://localhost:8080/?room=abc. - Open that link in a second tab (or an incognito window).
getInviteParam("room")returnsabc; check that your game joins. - The local host does not simulate friends' invites or
joinRoomevents. To exercise them, load the game in the Preview tool and use the event log to confirm theupdateRoomandleftRoomcalls arrive, then test the real invite tray with two accounts on the live portal.
Checklist#
-
updateRoomon create and join;leftRoomon leave. - Parameters from
inviteParamsjoined at start; join listener registered. -
isInstantMultiplayerskips 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.