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.

README.md

@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

Documentation tree

Status of the upstream migration

Modules