Getting Started

Install PlayMesh and build your first multiplayer server in minutes.

Prerequisites

PlayMesh requires Node.js 18 or later. Redis is optional for development — you can run in single-node, in-memory mode locally and add Redis when you deploy to production.

Installation

Server

Install the server package. Socket.IO, ioredis, and BullMQ are bundled — you don't need to install them separately.

npm install @playmesh/server

Client

Install the client package in your frontend or game client project.

npm install @playmesh/client

Your first server

The following creates a multiplayer chat lobby. No Redis required — it runs entirely in-memory.

◆server.ts

import { PlayMesh } from '@playmesh/server';

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

// 1. Authenticate connections
mesh.onAuthenticate(async request => {
  const username = String(request.auth.username ?? '').trim();
  if (!username) throw new Error('Username required');
  return { userId: username };
});

// 2. Create domains and instances before connections arrive
mesh.bootstrap(async ({ mesh }) => {
  const social = mesh.createDomain('social');
  const lobby = social.createInstance('lobby');

  lobby.on('chat', (session, payload) => {
    const { message } = payload as { message: string };
    lobby.broadcast('chat', {
      sender: session.userId,
      message,
    });
  });

  lobby.onJoin(session => {
    lobby.broadcast('system', { text: `${session.userId} joined` });
  });

  lobby.onLeave(session => {
    lobby.broadcast('system', { text: `${session.userId} left` });
  });
});

// 3. Decide which instances each new session joins
mesh.onAdmission(async () => ({
  instances: ['social/lobby'],
}));

await mesh.start();
console.log('Server running on port 4000');

✦

Omit the redis option to run in single-node mode with in-memory state and presence. Add { redis: { host: "localhost", port: 6379 } } for distributed mode.

Your first client

◆client.ts

import { PlayMeshClient } from '@playmesh/client';

const client = new PlayMeshClient({
  url: 'http://localhost:4000',
  auth: { username: 'alice' },
});

// Listen for events from the server
client.on('chat', payload => {
  const { sender, message } = payload as { sender: string; message: string };
  console.log(`${sender}: ${message}`);
});

client.on('system', payload => {
  console.log(`* ${(payload as { text: string }).text}`);
});

// Connect and authenticate
const session = await client.connect();
console.log('Connected as', session.userId);
console.log('Member of:', session.instances);

// Send events to the server
client.emit('chat', { message: 'Hello, world!' });

Run it

# Terminal 1
npx tsx server.ts

# Terminal 2
npx tsx client.ts

# Terminal 3 (second player)
npx tsx client.ts

With Redis (multi-node)

To run multiple server nodes, provide Redis connection options. All nodes will automatically synchronize sessions, presence, and state.

const mesh = new PlayMesh({
  port: 4000,
  redis: { host: 'localhost', port: 6379 },
});

// Or via a connection string:
const mesh = new PlayMesh({
  port: 4000,
  redis: 'redis://localhost:6379',
});

ℹ

Redis is required for background queues (mesh.queues). In single-node mode without Redis, queue operations will throw.

TypeScript

PlayMesh is written in TypeScript and ships full type definitions. No additional @types packages are needed.

◆tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true
  }
}