Rooms, roles, and authority

A TPG room is a shared session with one authority and several presentation surfaces. The distinction matters: controllers propose actions, while the authority decides what becomes true.

The room is the boundary

Room identity, connected participants, selected game, lifecycle stage, and canonical game state travel together. Keep temporary UI state—an open menu, a hover, an unfinished drawing stroke—inside the surface that owns it.

Shared state should answer a simple question: would another device need this value to render the same moment?

Lifecycle stages

Games receive lifecycle changes from the shell:

Treat lifecycle hooks as idempotent. Browser frames can reload, reconnect, or report readiness more than once.

Intents in, snapshots out

A controller intent should be small and descriptive:

runtime.sendAction({
  type: "answer-submitted",
  answerId: "option-b"
});

The authority validates that intent, applies it once, and publishes the next revision. Do not let controllers replace the full shared-state object; that bypasses validation and creates last-write-wins races.

Keep revisions explicit

If a surface reads state and later asks to change it, include the revision it read. A stale update can then be rejected instead of silently overwriting a newer result.

Keep private state private

Player-specific prompts, hands, or secrets belong in player state. Shared state is visible to the room and should be treated as public within that room.

Reconnect without inventing a second game

Reconnection should restore identity and current canonical state. Avoid local timers or random decisions that become authoritative merely because a frame refreshed.

Seed randomness at the authority, persist the seed or result, and let every presentation surface render from that value.

Related reference

• Game SDK guide
• Capability matrix
• External repository workflow