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-basedMetaverseStatewith map-encoded player transforms, supporting fast binary patches. - Bridges into the existing
MultiplayerSyncengine so analytics routes (/api/multiplayer/*) continue to report accurate server state. - Emits presence updates through an abstract
PresenceBroadcaster(implemented for Socket.io viaSocketIOPresenceBroadcaster). - Enforces a configurable
maxClients(defaults to 1000) and rejects overflow joins gracefully.
Key message handlers:
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 themetaverseroom).ws://<host>/ws/presence— Socket.io namespace emittingmultiplayer.presenceandmultiplayer.playerevents.
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:
- Join/leave flows with presence broadcast assertions.
- Max client enforcement (rejecting the 1001st player).
- Transform updates via
movemessages.
Tests run with the Colyseus test harness (@colyseus/testing) and local
presence/transport to simulate real clients.
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.presenceormultiplayer.playerevents. - Colyseus rooms are defined as
metaverse; additional room types can be registered by extendingcreateMultiplayerGateway. MultiplayerSyncremains 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.