portals-multiplayer-and-voice

Portals multiplayer, chat, and voice

Portals.net and Portals.voice are the only multiplayer and voice transports available to a hosted game. The sandbox has no outside network access: fetch, WebSocket, and WebRTC to other servers all fail, and networking or voice libraries cannot work. The Portals host page owns the real connections.

Read references/multiplayer-and-voice.md for the full API, code examples, availability matrix, and dev-token setup. It is the official documentation, copied verbatim.

Both transports ship with the SDK the project already includes:

<script src="./_portals/sdk.js"></script>
<script src="./game.js"></script>

Multiplayer rules that are easy to get wrong

• A session is everyone in the same bucket — all players of the game page, or the people in one Portals room. join({ channel }) makes a private sub-lobby: letters, numbers, colons, underscores, hyphens; must start alphanumeric; max 64 characters.
• Sessions run on US servers by default — one worldwide room per channel, so players everywhere meet. Turning on Latency-sensitive multiplayer in the game's settings on portals.to/my-games places each session on servers near its players instead — one room per region, so nearby players get low latency but players in different regions never meet. Recommend it for fast-paced games; it applies to new sessions immediately, no republish. The toggle is not settable through update_web_game_settings — the developer flips it on the settings page.
• In a latency-sensitive game a global: channel prefix shares one worldwide room again. A match arranged in a global lobby needs a global channel too (global:match-x7), or players split back into their own regions and never meet. Global rooms run in the US home region, so keep fast-paced matches regional.
• join({ region: "us" | "eu" }) forces the session onto that region's servers for every player and outranks all of the above, including a global: prefix. Pin only when the game needs one known location (a scheduled event, a persistent world, a region the players share) — distant players pay the latency. Pass the same value for every player of a room: differing pins are different rooms, which is how you would deliberately run separate US and EU worlds. A pin never falls back, so join() rejects if that region has no capacity.
• join() resolves to a plain snapshot, not a handle — every method stays on Portals.net. Use net.players(), net.self(), net.getState() for live synchronous reads after joining.
• send() does not echo to the sender; the state event does fire for the writer. Apply state changes from the event, not at the call site.
• Limits: 8 KB JSON per message and per state value, 128-character keys, 64 keys per session. About 20 broadcasts and 10 state writes per player per second — never send per-frame; sample on a 100–150 ms timer and interpolate locally.
• Anything a late joiner must see belongs in shared state, not in a broadcast.
• There is no automatic reconnect. On status disconnected, show a rejoin control that calls join() again.
• Without a server script, every client is authoritative over what it sends — the session is exactly as trustworthy as its least trustworthy player. The default design for a multiplayer game is a server-simulated one (the portals-server-sim skill); at minimum ship a server-script referee (the portals-server-scripts skill). Validate every incoming message's kind and shape, and never let a peer's messages control currency, prizes, access, or another entitlement. Only purely cosmetic shared spaces and slow turn-based games should ship trust-light.
• Text chat rides the same relay with a kind field — never a third-party chat service. Cap length (e.g. 300 chars) on send and receive, and render with textContent, never innerHTML. For history late joiners see, keep a rolling array (last ~20) in shared state.