portals-sdk

Portals SDK

The Portals global connects a hosted web game to the Portals player and host: identity, the player's public username and playable avatar, saved progress, casual scores, leaderboard reads, and closing the game.

Read references/portals-sdk.md for the full API, code examples, and the method reference table. It is the official documentation, copied verbatim.

Wiring

Portals stamps the SDK into every processed preview and published bundle. Include it from the game's own origin, before game code:

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

Never download, edit, or bundle _portals/sdk.js — Portals replaces the managed copy on every process and publish. TypeScript declarations live at https://portals.to/portals-sdk/portals.d.ts; they are not part of the game's files.

Host UI reserve

Every launched game keeps a trusted Portals controls trigger above the game iframe. The current closed trigger is 44×44 CSS pixels at left: max(12px, env(safe-area-inset-left)) and top: max(12px, env(safe-area-inset-top)); a party badge may extend 4px beyond it. Keep essential and interactive HUD UI outside that top-left footprint. For a top HUD, use padding-left: calc(max(12px, env(safe-area-inset-left)) + 56px); for a left HUD, use the equivalent top inset. A full-bleed non-interactive playfield is fine.

The host control is outside and above untrusted game code. Never try to hide, restyle, intercept, or out-z-index it. Its expanded panel may temporarily cover more of the game and owns focus while open, so pause or otherwise keep gameplay safe until focus returns.

Rules that are easy to get wrong

• await Portals.ready() before reading the player or using any hosted capability. session.context is standalone on a game page, room inside a Portals room.
• Call Portals.identity.requestLogin() only from a direct player action such as a button click. Portals owns the sign-in UI — never ask for a Portals password or account credential in-game.
• playerId is stable per player within one game and deliberately different across games. It is not a Portals account ID and must not be used to correlate a player across games. It is null for signed-out players, so always render a fallback name.
• Portals.player.get() reads the current public profile — username without the @, and avatar, the playable look saved on the Portals /avatar screen. avatarUrl is only a 2D profile image; never load it as a 3D character. Both are null for a guest. The first signed-in read is cached for the game load, so call it again after requestLogin().
• Portals.avatar.openPicker() opens the trusted global avatar UI from a direct click and resolves to the refreshed profile once the player saves; Cancel rejects. It is unavailable in the editor preview — catch the rejection, keep the preview playable, and verify the flow in a published host. Games never read inventory or equip items by ID; avatar.wearables is render data, not ownership proof.
• Saved state must be JSON-serializable and at most 64 KB encoded. Signed-out players cannot save; loadState() returns null when nothing is saved. Version the shape (schemaVersion) when it may change.
• Scores and saves require sign-in. A score mode is lowercase letters, numbers, and hyphens, max 32 characters, defaulting to default. getLeaderboard takes a limit of 1–100, default 10.
• submitScore keeps the player's highest score for a mode. Pass { replace: true } as the third argument — Portals.submitScore(score, mode, { replace: true }) — only when the game's score can legitimately go down and the new value must replace a higher stored one.
• Scores are client-reported. Never use them to award currency, paid prizes, access, or any other valuable entitlement.
• The leaderboard works in draft play too — submitScore and getLeaderboard are live in the editor preview and behind a shared ?draft= link. Draft play uses a separate draft board, so test a leaderboard before publishing; those scores never reach the published game's ranking, and the published board starts empty.
• Every async method can reject — no host, invalid request, missing access, network failure. Catch at the player action that caused it and keep the game playable when an optional Portals feature is unavailable.
• Never put API keys, Firebase tokens, payment details, or signed asset URLs in game code, saved state, score modes, logs, or leaderboard UI.