# Metaverse Multiplayer Stack

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.

```
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.
