# Connect a game to WorldsBay

See [World presence](WORLD-PRESENCE.md) for the public directory, authenticated heartbeats, player counts, public ports, portals, and world pictures. The shared adapter reports automatically; independent servers must implement the heartbeat contract to appear online.

See [Tags and managed groups](WORLD-STARTER.md#tags-and-managed-groups) for the builder desk's tag suggestions, group ownership and membership approvals. Portal targets can be a world ID, `random`, or `group:<group-id>`; group travel resolves approved membership centrally. Tag edits or heartbeat data cannot grant group membership.

You are integrating a game with WorldsBay. Preserve the game's art direction and gameplay.

For the optional low-poly modular builder, also read CHARACTER-BUILDER.md. Its
v2 rig families, bundled parts and full animation libraries are available through
`/client/runtime/character.js` and the downloadable character package. The normal
SDK remains renderer-independent. `openCharacterCreator()` opens central editing
with a return path to the current world; account writes stay central.

1. Read WORLD-STARTER.md, ARCHITECTURE.md, and RIG-PROFILE.md from the same guides directory. Use the existing generated JavaScript template as the executable reference.
2. Give the world a unique stable ID and its own HTTPS hostname. Different paths or ports on one hostname do not isolate cookies. Never share the central account hostname with a third-party world.
3. Keep the world's private credential on its server. Install the `@worldsbay/api` release from `https://worldsbay.com/downloads/worldsbay-api-0.1.0.tgz` and import it in your game's browser bundle. The starter also serves that installed package at `/client/runtime/sdk.js`. Inspect the module's actual exports; do not invent SDK calls.
4. Make the game's own URL playable. Read `enterSession()`, try the noncreating `resumeSession()` on a 401, then show **Play as guest**, **Create account**, and **Sign in** inside the game. Guest entry calls `startGuestSession()`. Account entry calls `openAccountPage(sdk, { mode: 'signup' })` or `{ mode: 'signin' }`; this visits the central account host and returns automatically to the game. Catch navigation errors and unlock controls if browser Back resolves the promise. Keep a visible **Save account** option for guests after joining, and account options inside the game's menu. The logo opens that menu; travel to another site is a separately labeled choice. Password fields belong only to the top-level WorldsBay-controlled account page. Never proxy passwords through a world's server. The included server adapter creates canonical guests through the authenticated central API and sets HttpOnly, Secure, host-only session and remembered-identity cookies. Never automatically create a guest on a network error. If a remembered identity is revoked or expired, offer an explicit **Start a new guest** choice using `startGuestSession({ newGuest: true })`; explain that it starts a new character and progress. Keep normal 60-second single-use entry-ticket exchange for hub travel and account/wardrobe return. Acknowledge entry only after creating the local session. Never treat a player ID, store context, or browser-supplied appearance as authentication.
5. Use the world's server session for appearance, travel, and store calls. Keep keys, tickets, cookies, and authorization headers out of logs and error reports.
6. Cache avatar bytes by the immutable asset revision. Use one in-flight request per revision and reuse resources for repeated actors. Apply bounded cache retention. Distribute validated bytes or a trusted immutable asset URL; never proxy arbitrary player-supplied URLs.
7. Preserve the named humanoid joints, rest pose, and animation clips. Reject unvalidated uploads, external glTF references, oversized assets, and invalid animation data. Do not pass uploads directly to players.
8. Keep multiplayer movement authoritative on the world server. The shared identity system does not validate your game rules.
9. Test two separate browser contexts starting directly at the game's own URL. Create distinct guests, see both avatars, reload and restart the world server without losing the identity, save a guest's account without losing world progress, sign in from another browser, cancel account forms, and test invalid credentials. Verify account forms use the central top-level origin on phones, support saved-password form semantics, and return automatically to the originating game. Test an existing central login with Continue as, a different-account guest signup, cancellation, browser Back, and confirmation opened in a fresh browser. Also change a look, travel to another world and back. Verify guest retries do not duplicate players, resume never creates players, and expired/revoked remembered identities require an explicit fresh start. Verify expired and replayed tickets, destination mismatches, offline services, and origin violations fail safely.
10. Production must disable seeded demo identity selection. Wardrobe items are free; do not add payment or crypto flows.

Nano checkout, external identity providers, and self-service registration must be used only when the deployment explicitly exposes those capabilities. Do not fabricate credentials or promise that unconfigured providers work.