Skip to content

Real-Time Multiplayer Infrastructure

The WebSocket-based shared-state layer that gives the universe its sense of presence: who's in your sector, live combat, instant trades, multi-channel chat. This doc is the operations view — the prescriptive subsystem spec is in ../SYSTEMS/realtime-bus.md.

1. What it does

Capability Surface
Presence awareness See other players in your current sector in real time
Movement updates Sector transitions broadcast immediately to relevant rooms
Status indicators online / away / busy / in combat
Chat (multi-channel) Global, sector, team, private DM, system notifications
Real-time combat No loading screens; live drone-exchange visibility; nearby-player alerts; team coordination
Shared economy Port prices and inventory reflect recent activity; instant trade execution
Event broadcast Major game events fan out to all relevant players
Mobile experience Adaptive update frequency, battery-aware, bandwidth-conserving, offline action queue

2. Connection model

  • Transport: WebSocket (bi-directional). The player client speaks the gameserver's custom realtime protocol via services/realtimeWebSocket.ts; the admin UI uses a thin client wrapper in services/websocket.ts.
  • Reconnection: automatic with state preservation across brief disconnects.
  • Adaptive quality: monitors connection quality; degrades gracefully on high latency; tunes update frequency on mobile.

Auth

  • JWT-verified handshake — same token as REST.
  • Session/login state respected for room access.
  • Device-tracking flags suspicious multi-location access.
  • Clean teardown on logout.

Anti-abuse

  • Rate limiting on commands.
  • Server-side validation of every client action (no trust in client state).
  • Periodic state-verification checks against authoritative store.
  • Fair-play enforcement for balanced multiplayer.

3. Rooms

Players are auto-assigned to a hierarchy of rooms:

  • Global — universal announcements.
  • Sector — players currently in the same sector.
  • Team — private team channel.
  • Private — direct player-to-player.

Movement triggers seamless transitions between sector rooms.

4. State synchronization

  • Delta updates — only changed fields go over the wire.
  • Priority queue — combat and trades pre-empt chat / cosmetic updates.
  • Verification ticks — periodic full-state checksums catch drift.
  • Conflict resolution — server arbitrates simultaneous actions.
  • Optimistic UI — clients render predicted state immediately; server confirmation reconciles.

5. Code surface

Backend (services/gameserver/src/)

  • services/websocket_service.py — base WebSocket service.
  • services/enhanced_websocket_service.py — richer real-time features.
  • services/redis_pubsub_service.py — cross-instance fanout via Redis.
  • services/redis_service.py — Redis client wrapper.
  • API endpoints: 9 WebSocket endpoints in the inventory (under api/routes/websocket* — auto-discovered via _discover_api_endpoints.py).

Redis (port 6379) handles cross-process pub/sub so multiple gameserver workers stay in sync. In multi-regional mode a dedicated redis-nexus instance handles cross-region traffic.

Player client (services/player-client/src/services/)

  • realtimeWebSocket.ts — realtime protocol client.
  • contexts/WebSocketContext.tsx — React provider; also handles ARIA message routing.

Admin UI (services/admin-ui/src/services/)

  • services/websocket.ts — shared client.
  • contexts/WebSocketContext.tsx — React provider.

6. Notification delivery

Notifications surface in-app to keep players in the flow:

  • New chat in any channel
  • Combat alerts when sectors you control are attacked
  • Team activity updates
  • Sector entry/exit alerts
  • System-wide announcements

7. Operational notes

  • Scaling: Redis pub/sub is the fanout mechanism; horizontal scaling of gameserver instances depends on it.
  • Test coverage: e2e_tests/foundation-sprint/websocket-realtime.spec.ts exercises the layer end-to-end.
  • Regional services use the same primitives — redis-nexus mirrors the local Redis for cross-region traffic when multi-regional is active.