Eve library

Metaverse Multiplayer Stack

Guide

Revision 1

On this page

The metaverse service now ships a production-ready real-time stack aligned with the roadmap requirement for a Colyseus + Socket.io server capable of supporting 1000+ simultaneous seekers.

Transport Overview#

  • Colyseus powers authoritative state rooms, patching player transforms at 20 Hz and handling reconnection, seat reservation, and capacity limits.
  • Socket.io exposes a lightweight presence channel (ws://<host>/ws/presence) to push aggregate stats (player counts, join/leave events) to dashboards and web clients without joining the simulation room.
  • Legacy WebSocket endpoints have been replaced by Colyseus, simplifying consistency across the stack.

Room Implementation#

The new MetaverseRoom class (services/metaverse/src/multiplayer/MetaverseRoom.ts) extends Colyseus Room and composes existing multiplayer utilities:

  • Maintains a Schema-based MetaverseState with map-encoded player transforms, supporting fast binary patches.
  • Bridges into the existing MultiplayerSync engine so analytics routes (/api/multiplayer/*) continue to report accurate server state.
  • Emits presence updates through an abstract PresenceBroadcaster (implemented for Socket.io via SocketIOPresenceBroadcaster).
  • Enforces a configurable maxClients (defaults to 1000) and rejects overflow joins gracefully.

Key message handlers:

ts
this.onMessage('move', (client, payload) => this.handleMove(client, payload));
this.onMessage('latency', (client, latency) =>
  this.handleLatency(client, latency)
);

Fastify Integration#

createApp wires a shared gateway (createMultiplayerGateway) that bootstraps both the Colyseus server and Socket.io broadcaster off the existing Fastify HTTP server. Shutdown hooks gracefully terminate the gateway alongside other subsystems.

Runtime endpoints now include:

  • ws://<host>/colyseus — Colyseus room endpoint (clients seat into the metaverse room).
  • ws://<host>/ws/presence — Socket.io namespace emitting multiplayer.presence and multiplayer.player events.

Server logs (services/metaverse/src/server.ts) advertise these endpoints for operators.

Testing#

Automated coverage lives in services/metaverse/tests/MetaverseRoom.test.ts and exercises:

  1. Join/leave flows with presence broadcast assertions.
  2. Max client enforcement (rejecting the 1001st player).
  3. Transform updates via move messages.

Tests run with the Colyseus test harness (@colyseus/testing) and local presence/transport to simulate real clients.

text
cd services/metaverse
NODE_OPTIONS='--experimental-vm-modules' npx jest --runTestsByPath tests/MetaverseRoom.test.ts

Operational Notes#

  • Socket.io broadcasts use the default namespace and simple event names; downstream consumers should listen for multiplayer.presence or multiplayer.player events.
  • Colyseus rooms are defined as metaverse; additional room types can be registered by extending createMultiplayerGateway.
  • MultiplayerSync remains the authoritative source for analytic endpoints and integrates seamlessly with the new room lifecycle.

This architecture satisfies the 1000+ user target while keeping observability hooks and REST endpoints consistent with prior iterations.