@web-engine-dev/matchmaking

Matchmaking and lobby system for multiplayer games.

Features

• Skill-Based Matching: ELO/MMR rating systems
• Lobby Management: Create, join, leave lobbies
• Queue System: Player queuing with priorities
• Custom Filters: Match by game mode, region, etc.
• Party Support: Group players together
• Backfill: Fill empty slots in ongoing games

Installation

npm install @web-engine-dev/matchmaking
# or
pnpm add @web-engine-dev/matchmaking

Quick Start

import { MatchmakingService, Lobby, MatchmakingQueue } from '@web-engine-dev/matchmaking';

// Create matchmaking service
const matchmaking = new MatchmakingService({
  ratingSystem: 'elo',
  ticketTimeout: 60000,
});

// Create a matchmaking ticket
const ticket = await matchmaking.createTicket({
  playerId: 'player-123',
  rating: 1500,
  gameMode: 'deathmatch',
  region: 'eu-west',
});

// Listen for match found
matchmaking.on('matchFound', (match) => {
  console.log('Match found:', match.id);
  console.log('Players:', match.players);
  console.log('Server:', match.serverAddress);
});

// Cancel matchmaking
await matchmaking.cancelTicket(ticket.id);

API Overview

Matchmaking Service

const mm = new MatchmakingService({
  ratingSystem: 'elo', // 'elo', 'glicko2', 'trueskill'
  matchSize: 10, // Players per match
  teamSize: 5, // Players per team
  ticketTimeout: 120000, // Ticket expiry (ms)
  ratingTolerance: 200, // Initial rating range
  toleranceGrowth: 50, // Growth per 10s
});

Lobbies

// Create lobby
const lobby = await matchmaking.createLobby({
  name: 'My Game',
  maxPlayers: 8,
  isPrivate: false,
  gameMode: 'capture-flag',
});

// Join lobby
await matchmaking.joinLobby(lobby.id, playerId);

// List lobbies
const lobbies = await matchmaking.listLobbies({
  gameMode: 'capture-flag',
  hasOpenSlots: true,
});

// Start match from lobby
await lobby.startMatch();

Rating Systems

// Update ratings after match
const results = await matchmaking.updateRatings({
  matchId: match.id,
  teams: [
    { teamId: 1, players: ['a', 'b'], score: 10 },
    { teamId: 2, players: ['c', 'd'], score: 5 },
  ],
});

// Get player rating
const rating = await matchmaking.getRating(playerId);

Party System

// Create party
const party = await matchmaking.createParty(leaderId);

// Invite to party
await party.invite(playerId);

// Queue as party
await matchmaking.createTicket({
  partyId: party.id,
  gameMode: 'ranked',
});