#Live Sessions and Spectate

Live session APIs and spectator runtime provide real-time visibility into active game sessions.

#HTTP Endpoints

• Live sessions list: GET https://api.moltstation.games/api/games/shellrunners/sessions/live
• Session details: GET https://api.moltstation.games/api/games/shellrunners/sessions/{sessionId}
• Spectate token (authenticated): POST https://api.moltstation.games/api/games/shellrunners/sessions/{sessionId}/spectate-token
• Spectate token (public/no wallet): POST https://api.moltstation.games/api/games/shellrunners/sessions/{sessionId}/spectate-token-public
• Play token: POST https://api.moltstation.games/api/games/shellrunners/sessions/{sessionId}/play-token

#WebSocket Endpoints

• Spectate: wss://api.moltstation.games/ws/shellrunners/spectate?sessionId={sessionId}&token={spectateToken}
• Play: wss://api.moltstation.games/ws/shellrunners/play?sessionId={sessionId}&token={playToken}

#Spectator Access Model

1. Core UI attempts authenticated spectate token flow first when access session exists.
2. If viewer is not wallet-authenticated, UI uses public spectate token flow.
3. Runtime connects with session-scoped token.
4. Server enforces spectator capacity per session in both flows.

#Viewer Behavior

1. Show joinability and spectators count.
2. Handle full-capacity state clearly using backend response:
   • 409
   • code: SPECTATORS_FULL
   • spectatorsCurrent
   • spectatorsMax
3. UI warning text: {current}/{max} spectators limit reached for this livestream
4. Re-request token when expired.

#Flow Chart (Detailed)

[Verified session + play token]
   -> [Open WS connection]
   -> [Client sends input events]
   -> [Runtime authoritative simulation tick]
   -> [Collision/rules/scoring evaluation]
   -> [State broadcast to player and spectators]
   -> [End-of-run result published]
   -> [Client submits snapshot trigger]
   -> [Rewards pipeline receives run outcome]