59 lines
2.8 KiB
Markdown
59 lines
2.8 KiB
Markdown
# Wave B-5a: `@suaveplan/game-server` matchmaking slice
|
|
|
|
**Package**: `@suaveplan/game-server`
|
|
**Status**: PROPOSED
|
|
**Type**: feature-add (additive to existing 0.1.0 package)
|
|
|
|
## Why
|
|
|
|
Wave A landed the `@suaveplan/game-server` core foundation (DI
|
|
container, error registry, Zod-validated boundary types). Five parallel
|
|
waves now extend the package along orthogonal axes; B-5 owns the
|
|
**matchmaking + performance** axis. This change covers the matchmaking
|
|
half; a sibling change (`game-server-performance`) covers pooling and
|
|
network-tier adapter.
|
|
|
|
The upstream reference
|
|
(`/mnt/s/web/suaveplan/packages/universal/game-server/src/matchmaking/`)
|
|
ships five modules — `MatchmakingEngine`, `QueueManager`,
|
|
`SpectatorManager`, `skill-matcher`, `winner-stays-on` — but couples
|
|
them to upstream-only types (`Logger`, `GameEventEmitter`,
|
|
`AbstractStorage`) and emits events that do not appear in the genesis
|
|
`GameEvents` map. This slice ports the algorithms, replaces the
|
|
upstream couplings with `@suaveplan/types` (`Clock`, `IdGenerator`,
|
|
`Rng`) plus typed observer callbacks, and adds OTel-native
|
|
instrumentation that the upstream lacked.
|
|
|
|
## What changes
|
|
|
|
- ADDED: `src/matchmaking/queue-manager/` — priority-queue manager with
|
|
premium / wait-time / explicit-offset priority math, configurable
|
|
`maxQueueSize`, four OTel instruments, Zod-validated boundary, typed
|
|
`MATCHMAKING_QUEUE_FULL` / `INVALID_QUEUE_REQUEST` errors.
|
|
- ADDED: `src/matchmaking/skill-matcher/` — Elo-style matcher with
|
|
pluggable scoring fn, base + wait-time range, injectable `Clock` and
|
|
`Rng`, two OTel instruments.
|
|
- ADDED: `src/matchmaking/spectator-manager/` — per-session spectator
|
|
roster with cap enforcement, three OTel counters, Zod-validated
|
|
permissions, `onSpectatorJoined` / `onSpectatorLeft` callbacks.
|
|
- ADDED: `src/matchmaking/winner-stays-on/` — winner-stays-on strategy
|
|
with champion / streak / challenger-queue tracking, two OTel
|
|
counters, configurable streak cap.
|
|
- ADDED: `src/matchmaking/matchmaking-engine/` — top-level façade
|
|
composing the above; `createMatch(players, criteria, algorithm)` +
|
|
`createMatchFromQueue(queueKey, criteria, algorithm)` (drain + match
|
|
+ restore on shortfall); `quick` and `skill-based` algorithms;
|
|
injectable `IdGenerator`; three OTel instruments.
|
|
|
|
## Impact
|
|
|
|
- Affected specs: `openspec/specs/game-server/spec.md` (game-server
|
|
capability).
|
|
- New error codes: `MATCHMAKING_QUEUE_FULL`, `INVALID_QUEUE_REQUEST`,
|
|
`INVALID_MATCH_CRITERIA`, `NO_MATCH_FOUND`, `INVALID_SKILL_SCORE`,
|
|
`SPECTATOR_LIMIT_REACHED`, `INVALID_SPECTATOR_REQUEST`,
|
|
`UNKNOWN_MATCHING_ALGORITHM`.
|
|
- New subpath exports: `./matchmaking/{queue-manager, skill-matcher,
|
|
spectator-manager, winner-stays-on, matchmaking-engine}`.
|
|
- No `core/` / `state/` / `engine/` / `network/` modifications.
|