skills/plugins/document-navigator/docs/gaming/games/game-server

@suaveplan/game-server - Universal game server framework: typed dependency-injection container, error registry and Zod-validated core types (game-config, session-metadata, player-info, move-validation-result) as foundation for the broader engine/session/state/matchmaking surface migrated from main

Universal game-server framework. Migrated from @suaveplan/game-server on the reference branch claude/review-game-engine-arch-Kaykr (main repo packages/universal/game-server/). The port lands in dependency-ordered slices; this initial slice (0.1.0) ships the foundations that every later slice will depend on:

• ./errors — GameServerError + GAME_SERVER_CODES (defineCodes registry).
• ./types — GameConfig, SessionMetadata, PlayerInfo, MoveValidationResult, GameResult, SessionType, DeepReadonly, plus Zod schemas and throwing/non-throwing validators for every boundary.
• ./engine/di-container — typed singleton/transient service locator, ported with a typed GAME_SERVER.SERVICE_NOT_REGISTERED error and a cache-invalidating re-register semantic (improvement).

Documentation tree

• abstract-game-logic — AbstractGameLogic<TState, TMove> is the abstract base every concrete game type extends. It implements the `IG…
  • abstract-game-logic — AbstractGameLogic<TState, TMove> is the abstract base every concrete game type extends. It implements the `IG…
• game-event-emitter — GameEventEmitter is the typed event hub every game-server subsystem publishes to and listens on. It exposes the stand…
  • game-event-emitter — GameEventEmitter is the typed event hub every game-server subsystem publishes to and listens on. It exposes the stand…
• game-events — This module owns the typed event-payload map every game-server consumer keys off — players, sessions, game lifecycle, m…
  • game-events — This module owns the typed event-payload map every game-server consumer keys off — players, sessions, game lifecycle, m…
• i-game-logic — IGameLogic is the strategy-pattern contract every concrete game type plugs into the universal game server through. Th…
  • i-game-logic — IGameLogic is the strategy-pattern contract every concrete game type plugs into the universal game server through. Th…
• i-player-manager — IPlayerManager is the contract every connection-tracking implementation must satisfy so the engine, session manager,…
  • i-player-manager — IPlayerManager is the contract every connection-tracking implementation must satisfy so the engine, session manager,…
• i-session-manager — ISessionManager is the contract every session-tree implementation must satisfy. The session hierarchy is the core org…
  • i-session-manager — ISessionManager is the contract every session-tree implementation must satisfy. The session hierarchy is the core org…
• i-state-manager — IStateManager<TState> is the contract every state-management implementation in the game server stack must satisfy. St…
  • i-state-manager — IStateManager<TState> is the contract every state-management implementation in the game server stack must satisfy. St…
• di-container — DIContainer is a small, type-safe service locator that the broader @suaveplan/game-server engine uses to thread sha…
  • di-container — DIContainer is a small, type-safe service locator that the broader @suaveplan/game-server engine uses to thread sha…
• game-engine — GameEngine is the top-level orchestrator for @suaveplan/game-server. It owns a DIContainer, a GameLoop, and a `…
  • game-engine — GameEngine is the top-level orchestrator for @suaveplan/game-server. It owns a DIContainer, a GameLoop, and a `…
• game-loop — GameLoop drives a deterministic, injection-friendly game loop with three operating modes (tick-based, `event-driven…
  • game-loop — GameLoop drives a deterministic, injection-friendly game loop with three operating modes (tick-based, `event-driven…
• player-manager — PlayerManager is the IPlayerManager implementation backing the player lifecycle in @suaveplan/game-server. It tra…
  • player-manager — PlayerManager is the IPlayerManager implementation backing the player lifecycle in @suaveplan/game-server. It tra…
• plugin-manager — PluginManager is the typed plugin registry for @suaveplan/game-server. It owns the install/uninstall/enable/disable…
  • plugin-manager — PluginManager is the typed plugin registry for @suaveplan/game-server. It owns the install/uninstall/enable/disable…
• session-lifecycle — SessionLifecycle is the per-session finite-state machine that models each session's progression through the three hig…
  • session-lifecycle — SessionLifecycle is the per-session finite-state machine that models each session's progression through the three hig…
• session-node — SessionGraphNode is the internal mutable graph node powering the hierarchical session tree at the heart of `@suavepla…
  • session-node — SessionGraphNode is the internal mutable graph node powering the hierarchical session tree at the heart of `@suavepla…
• session-store — SessionStore is the ISessionManager implementation that consumers wire into a GameEngine. It composes a `SessionT…
  • session-store — SessionStore is the ISessionManager implementation that consumers wire into a GameEngine. It composes a `SessionT…
• session-tree — SessionTree is the hierarchical session graph backing @suaveplan/game-server. It owns the `Map<id, SessionGraphNode…
  • session-tree — SessionTree is the hierarchical session graph backing @suaveplan/game-server. It owns the `Map<id, SessionGraphNode…
• anti-cheat-validator — AntiCheatValidator performs server-authoritative validation for player movement and action streams in real-time multi…
  • anti-cheat-validator.internal — Internal pure helpers backing AntiCheatValidator. Holds default configuration constants (movement, rate limits, punis…
  • anti-cheat-validator — AntiCheatValidator performs server-authoritative validation for player movement and action streams in real-time multi…
• interest-manager — InterestManager implements area-of-interest (AOI) culling for open-world multiplayer games: it tracks zones, entities…
  • interest-manager.internal — Pure geometry helpers backing InterestManager: Euclidean vectorDistance (z defaults to 0 for 2D interop), `zoneCont…
  • interest-manager — InterestManager implements area-of-interest (AOI) culling for open-world multiplayer games: it tracks zones, entities…
• lag-compensator — LagCompensator performs server-side state rewinding for accurate hit registration in networked multiplayer games. It…
  • lag-compensator.internal — Pure helpers backing LagCompensator: RTT_SAMPLE_SIZE, the initialStats factory, RTT-sample-window management (`pu…
  • lag-compensator — LagCompensator performs server-side state rewinding for accurate hit registration in networked multiplayer games. It…
• leaderboard-manager — LeaderboardManager provides multi-leaderboard score tracking for game servers with three independent ranking modes —…
  • leaderboard-manager — LeaderboardManager provides multi-leaderboard score tracking for game servers with three independent ranking modes —…
• game-persistence — GamePersistence persists game state to a pluggable key-value backend via the StorageLike structural contract from `…
  • game-persistence — GamePersistence persists game state to a pluggable key-value backend via the StorageLike structural contract from `…
• replay-player — ReplayPlayer plays back a ReplayData<TState, TInput> document produced by ReplayRecorder. It exposes the controls…
  • replay-player — ReplayPlayer plays back a ReplayData<TState, TInput> document produced by ReplayRecorder. It exposes the controls…
• replay-recorder — ReplayRecorder captures gameplay into a deterministic, replay-ready ReplayData<TState, TInput> document. It records…
  • replay-recorder — ReplayRecorder captures gameplay into a deterministic, replay-ready ReplayData<TState, TInput> document. It records…
• game-instance-registry — GameInstanceRegistry is the in-memory primitive that tracks every live game-server instance in a multi-host deploymen…
  • game-instance-registry.internal — Pure helpers extracted from GameInstanceRegistry so the orchestrator class stays inside the per-file budget. The help…
  • game-instance-registry — GameInstanceRegistry is the in-memory primitive that tracks every live game-server instance in a multi-host deploymen…
• bitpacker-state-sync — BitPackerStateSync is the byte-packed state-synchronisation primitive for low-bandwidth, high-frequency multiplayer u…
  • bitpacker-state-sync — BitPackerStateSync is the byte-packed state-synchronisation primitive for low-bandwidth, high-frequency multiplayer u…
• vector-clock-sync — VectorClockSync is the distributed event-ordering primitive used by multiplayer game sessions to decide whether two a…
  • vector-clock-sync.internal — This module factors out the pure helpers that drive VectorClockSync — happens-before / concurrent predicates, conflic…
  • vector-clock-sync — VectorClockSync is the distributed event-ordering primitive used by multiplayer game sessions to decide whether two a…
• tournament-manager — TournamentManager orchestrates single-elimination and round-robin tournaments. Participants register during the `pend…
  • tournament-bracket.internal — Pure bracket-generation helpers used by TournamentManager. Extracted to a sibling internal module to keep `tournament…
  • tournament-manager — TournamentManager orchestrates single-elimination and round-robin tournaments. Participants register during the `pend…
  • tournament-standings.internal — Pure helper utilities for the standings table inside a tournament: applying a win/loss outcome, marking participants el…
• errors — GameServerError is the single typed-exception class for the @suaveplan/game-server package. It extends `SuaveplanEr…
  • game-server-error — GameServerError is the single typed-exception class for the @suaveplan/game-server package. It extends `SuaveplanEr…
• enhanced-server — EnhancedGameServer is the top-of-stack integration layer for @suaveplan/game-server. Waves B and C-1 shipped the en…
  • enhanced-server — EnhancedGameServer is the top-of-stack integration layer for @suaveplan/game-server. Waves B and C-1 shipped the en…
• matchmaking-engine — MatchmakingEngine is the top-level façade for the game-server's matchmaking pipeline. It composes three optional coll…
  • matchmaking-engine — MatchmakingEngine is the top-level façade for the game-server's matchmaking pipeline. It composes three optional coll…
• queue-manager — QueueManager is the in-memory priority queue at the heart of the matchmaking pipeline. Each call to addToQueue inse…
  • queue-manager — QueueManager is the in-memory priority queue at the heart of the matchmaking pipeline. Each call to addToQueue inse…
• skill-matcher — SkillMatcher picks the closest-rated viable opponent for a queue seeker out of a candidate pool, widening its accepta…
  • skill-matcher — SkillMatcher picks the closest-rated viable opponent for a queue seeker out of a candidate pool, widening its accepta…
• spectator-manager — SpectatorManager owns the live spectator roster for every active game session. Spectators join a session through `add…
  • spectator-manager — SpectatorManager owns the live spectator roster for every active game session. Spectators join a session through `add…
• winner-stays-on — WinnerStaysOnManager models the classic arcade format where the round winner keeps their seat while the next challeng…
  • winner-stays-on — WinnerStaysOnManager models the classic arcade format where the round winner keeps their seat while the next challeng…
• network-adapter — NetworkAdapter is the unified bridge between the @suaveplan/game-server framework and any concrete network transpor…
  • network-adapter — NetworkAdapter is the unified bridge between the @suaveplan/game-server framework and any concrete network transpor…
• reconnection-manager — ReconnectionManager drives transport reconnection with exponential backoff and configurable jitter for the `@suavepla…
  • reconnection-manager — ReconnectionManager drives transport reconnection with exponential backoff and configurable jitter for the `@suavepla…
• webrtc-transport — WebRTCTransport is the game-server-tier Transport adapter for WebRTC data channels. It wraps an underlying client c…
  • webrtc-transport — WebRTCTransport is the game-server-tier Transport adapter for WebRTC data channels. It wraps an underlying client c…
• websocket-transport — WebSocketTransport is the game-server-tier Transport adapter for WebSocket connections. It wraps an underlying clie…
  • websocket-transport — WebSocketTransport is the game-server-tier Transport adapter for WebSocket connections. It wraps an underlying clie…
• observability — This module owns the three OpenTelemetry instruments the @suaveplan/game-server engine, loop, and plugin manager emit…
  • otel — This module owns the three OpenTelemetry instruments the @suaveplan/game-server engine, loop, and plugin manager emit…
• network-tier-adapter — NetworkTierAdapter bridges the game-server's matchmaking + session layer to the @suaveplan/network tier model. Each…
  • network-tier-adapter — NetworkTierAdapter bridges the game-server's matchmaking + session layer to the @suaveplan/network tier model. Each…
• object-pool — ObjectPool<T> is a generic typed object pool that dampens GC pressure in hot allocation paths — game-loop frame alloc…
  • object-pool — ObjectPool<T> is a generic typed object pool that dampens GC pressure in hot allocation paths — game-loop frame alloc…
• session-pool — SessionPool is a session-specific wrapper around ObjectPool<T> that recycles PooledSession records — plain-data s…
  • session-pool — SessionPool is a session-specific wrapper around ObjectPool<T> that recycles PooledSession records — plain-data s…
• ab-test-plugin — ABTestPlugin registers weighted experiments and assigns players to variants deterministically via an injected Rng.…
  • ab-test-plugin — ABTestPlugin registers weighted experiments and assigns players to variants deterministically via an injected Rng.…
• analytics-plugin — AnalyticsPlugin tracks per-session counters and per-event activity for a @suaveplan/game-server engine. It subscrib…
  • analytics-plugin — AnalyticsPlugin tracks per-session counters and per-event activity for a @suaveplan/game-server engine. It subscrib…
• base-plugin — BasePlugin is the abstract base class every concrete @suaveplan/game-server plugin extends. It implements the `Engi…
  • base-plugin — BasePlugin is the abstract base class every concrete @suaveplan/game-server plugin extends. It implements the `Engi…
• feature-flag-plugin — FeatureFlagPlugin wraps a @suaveplan/feature-flags FlagManager and exposes its evaluation surface as a lifecycle-…
  • feature-flag-plugin — FeatureFlagPlugin wraps a @suaveplan/feature-flags FlagManager and exposes its evaluation surface as a lifecycle-…
• logging-plugin — LoggingPlugin subscribes to a GameEventEmitter at install time and forwards every observed event to an injected `Lo…
  • logging-plugin — LoggingPlugin subscribes to a GameEventEmitter at install time and forwards every observed event to an injected `Lo…
• persistence-plugin — PersistencePlugin tracks per-session game state via a GameEventEmitter and persists it to an injectable `StorageLik…
  • persistence-plugin — PersistencePlugin tracks per-session game state via a GameEventEmitter and persists it to an injectable `StorageLik…
• rules-plugin — RulesPlugin integrates @suaveplan/rules with the game-server engine. It maintains three rule sets — move validation…
  • rules-plugin — RulesPlugin integrates @suaveplan/rules with the game-server engine. It maintains three rule sets — move validation…
• workflow-plugin — WorkflowPlugin lets the game-server orchestrate multi-step @suaveplan/workflow engines under a stable id. Callers r…
  • workflow-plugin — WorkflowPlugin lets the game-server orchestrate multi-step @suaveplan/workflow engines under a stable id. Callers r…
• delta-compressor — DeltaCompressor is the wire-format layer that sits between StateDiffer and StateSync. It computes a StateDelta…
  • delta-compressor — DeltaCompressor is the wire-format layer that sits between StateDiffer and StateSync. It computes a StateDelta…
• state-differ — StateDiffer is a pure structural diff and patch utility for plain-object game state. It produces a compact, determini…
  • state-differ — StateDiffer is a pure structural diff and patch utility for plain-object game state. It produces a compact, determini…
• state-manager — StateManager is the canonical, observable container for game-session state. It holds a single typed value, exposes re…
  • state-manager — StateManager is the canonical, observable container for game-session state. It holds a single typed value, exposes re…
• state-sync — StateSync is the orchestration layer that turns StateManager mutations into wire packets and applies received packe…
  • state-sync — StateSync is the orchestration layer that turns StateManager mutations into wire packets and applies received packe…
• types — This module defines the runtime Zod schemas and validator helpers for the core boundary types of `@suaveplan/game-serve…
  • common — This module defines the runtime Zod schemas and validator helpers for the core boundary types of `@suaveplan/game-serve…

Status of the upstream migration

Surface area	Status
core/types, errors, engine/di-container	Shipped in this slice.
core/{AbstractGameLogic, interfaces/*, events/*}	Deferred (see spec change enterprise-game-server-core).
engine/{GameEngine, GameLoop, PlayerManager, PluginManager, SessionLifecycle, SessionNode, SessionStore, SessionTree}	Deferred — each requires kebab-case rename, 5-file layout, typed errors, OTel wiring, Zod boundaries, 100% test coverage.
state/{DeltaCompressor, StateDiffer, StateManager, StateSync}	Deferred.
matchmaking/{MatchmakingEngine, QueueManager, SpectatorManager, skill-matcher, winner-stays-on}	Deferred.
network/{NetworkAdapter, ReconnectionManager, WebRTCTransport, WebSocketTransport}	Blocked — missing dependencies @suaveplan/network-webrtc, @suaveplan/network-websockets.
performance/* → telemetry/*	Deferred (folds into engine slice).
plugins/*	Blocked — missing dependencies @suaveplan/workflow, @suaveplan/keys.
enhanced/* (73 files)	Priority 2 — separate change enterprise-game-server-enhanced.
integrations/* (game-lobby UI + enhanced-server)	Priority 3 — React-coupled, belongs in a react-game-lobby package.

See the design proposal for the full deferral table and rationale.

Modules

• src/errors/game-server-error.md
• src/types/common.md
• src/engine/di-container/di-container.md
• src/engine/game-engine/game-engine.md
• src/engine/game-loop/game-loop.md
• src/engine/plugin-manager/plugin-manager.md
• src/observability/otel.md