specter-multiplayer

Specter Multiplayer — matchmaking, parties, match sessions

Two surfaces work together:

1. REST (https://api.specterapp.xyz/v2/client, headers per the specter skill) — initiate actions: find match, create/start/end sessions, party CRUD.
2. Socket.io WebSocket (https://multiplayer.specterapp.xyz, staging: https://staging.multiplayer.specterapp.xyz) — receive real-time events: match found, ready check, server assignment, score updates, party state.

A correct integration connects the socket first, then triggers REST actions, and reacts to socket events. Match configurations (team size, MMR rules, regions) are defined in the dashboard.

Complete real-time event contract — the exact handshake, namespaces (/ and /notifications), room conventions, and every client→server / server→client event with its payload across all gateways (matchmaking, match, party, group, online-presence, reward notifications): references/realtime-socketio.md. This is the authoritative source for event names/payloads (they're not in any REST/OpenAPI doc).

Connecting

import { io } from "socket.io-client";

const socket = io("https://multiplayer.specterapp.xyz", {
  transports: ["websocket"],
  auth: {
    token: accessToken,   // same JWT from Specter login
    apiKey: API_KEY,      // same project api-key
    type: "client",
  },
});

Invalid/expired credentials reject the connection. On reconnect during an active flow the server restores state (match:reconnect, match:rejoined).

Matchmaking flow (the happy path)

REST  POST /matchmaking/find-match { matchId, region, ... }   → queued
WS    queue:joined / queue:status                              → show queue UI (position, wait)
WS    match:found { pendingMatchId, players, acceptTimeout }   → show ready check (~15s)
WS    matchmaking:accept-match { matchId } (emit)              → or decline
WS    match:playerStatus                                       → "3/4 accepted…"
WS    match:confirmed { sessionId }                            → all accepted
WS    match:server-ready { serverInfo: { ip, port, connectionToken } }
                                                               → connect to game server