Architecture

How PlayMesh organizes multiplayer environments and what each layer is responsible for.

The hierarchy

PlayMesh organizes multiplayer environments using four concepts: Universe, Domain, Instance, and Session.

Universe — PlayMesh instance

├── Domain "world"

│ ├── Instance "city-center"

│ └── Instance "dungeon-1"

└── Domain "guild"

└── Instance "dragon-slayers"

Sessions join Instances and can be in multiple at once

Universe

The Universe is the root of a PlayMesh deployment. It maps to a single PlayMesh instance. It owns all Domains, manages Sessions, runs authentication and admission, and coordinates the Socket.IO server and Redis connections.

const mesh = new PlayMesh({ port: 4000 });
await mesh.start();

Domain

A Domain is a logical grouping of related Instances. Think of it as a region or service within your game: the open world, the matchmaking lobby, the social hub, ranked mode.

const world = mesh.createDomain('world');
const social = mesh.createDomain('social');

// Broadcast to everyone in 'world', across all its instances
world.broadcast('maintenance-warning', { minutesLeft: 5 });

Instance

An Instance is an isolated multiplayer environment. Sessions join instances to participate in them. Instances handle events from their member sessions and broadcast to them.

const city = world.createInstance('city-center');

city.on('chat', (session, payload) => {
  city.broadcast('chat', { sender: session.userId, ...payload });
});

// Synchronized state scoped to this instance
await city.state.set('player-count', city.sessions.length);

// Count across all nodes
const total = await city.memberCount();

Session

A Session represents a connected client. It can join multiple Instances simultaneously — world zone, guild chat, party channel all at once.

await session.join(cityInstance);
await session.join(guildInstance);
await session.join(partyInstance);

session.isIn(cityInstance);  // true
session.instances;           // [cityInstance, guildInstance, partyInstance]

await session.leave(partyInstance);
session.send('inventory-update', { items });

Horizontal scaling

When Redis is configured, multiple PlayMesh nodes run simultaneously. Socket.IO uses the Redis adapter for cross-node pub/sub. Presence and state are backed by Redis. Queues are shared across the cluster.

Redis

│

──────────────────────

Node 1

Node 2

Node 3

Philosophy

PlayMesh provides

Real-time socket communication
Session management & lifecycle
Presence tracking
Domain / Instance topology
Distributed messaging & pub/sub
Runtime state storage
Background queues (BullMQ)

You provide

Authentication logic
Admission / placement rules
Game logic & rules
Databases & persistence
Economy & inventory
Analytics
Business rules