suaveplan/openspec/archive/2026-05-24-game-server-integrations/proposal.md

Proposal — game-server integrations (Wave C-5)

Why

Waves B and C-1 shipped the GameEngine, PluginManager, and eight concrete plugins. Consumers still have to wire them together by hand: construct the loop, the plugin manager, install every plugin, register them, and tear everything down on shutdown. Wave C-5 closes that gap with a single-entry-point EnhancedGameServer integration that bootstraps the canonical stack via one bootstrap(options) call.

The integration is universal-tier (zero browser / React deps). React component shells from upstream (game-lobby/) are explicitly deferred to a future react-game-server package — they cannot live inside a universal-tier package.

What changes

ADDED EnhancedGameServer

Top-of-stack orchestrator that:

• Accepts injectable Clock, IdGenerator, LoggerLike, TimersLike, EventBusLike, plus per-plugin external collaborators (FlagManager, RuleEngine, StorageLike, AnalyticsSink, Rng, GameEventEmitter).
• Constructs a GameLoop, PluginManager, and GameEngine in canonical wiring order.
• Pre-registers all eight plugins (BasePlugin-derived) in declared install order, honouring the topoSort guarantee of PluginManager.
• Surfaces bootstrap(options) as the single user-facing entry point.
• Exposes start(), tick(), stop(), dispose() deferring to the underlying GameEngine.
• Throws BOOTSTRAP_FAILED if any plugin install fails, and ALREADY_BOOTSTRAPPED on double-bootstrap.

ADDED error codes

• GAME_SERVER.BOOTSTRAP_FAILED
• GAME_SERVER.ALREADY_BOOTSTRAPPED

DEFERRED — components/game-lobby/

The upstream React lobby component cannot ship in a universal-tier package. It will land in a follow-up react-game-server package and is out of scope for Wave C-5.

Impact

• Affected packages: @suaveplan/game-server.
• Affected specs: game-server (ADDED integrations capability).
• Public surface: ./integrations/enhanced-server subpath export only.
• No breaking change — purely additive.