135 lines
3.5 KiB
Markdown
135 lines
3.5 KiB
Markdown
# OpenSpec Change: enterprise-gaming-lobby
|
|
|
|
- **Change ID**: enterprise-gaming-lobby
|
|
- **Package**: `@suaveplan/lobby`
|
|
- **Category**: gaming/multiplayer
|
|
- **Target path**: `gaming/multiplayer/lobby`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/lobby.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/lobby` on the genesis branch from scratch at enterprise quality. The package provides multiplayer lobby management with matchmaking integration and countdown. A `LobbyManager` creates/destroys typed `Lobby` objects; a `Lobby` tracks member roster, ready state per member, configurable `minPlayers`/`maxPlayers`, game mode settings, and a `CountdownTimer`; when all members are ready, the countdown starts — on expiry the lobby fires `lobby:match_ready` and hands off to `@suaveplan/game-server`. Genesis adds Zod lobby config schemas, structured errors, OTel lobby-count gauge, injectable clock, and 100% coverage.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Package does not exist on genesis yet — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | `LobbyError`; `LOBBY.*` codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `Clock`, `IdGenerator` |
|
|
| `@suaveplan/events` (`workspace:^`) | `lobby:joined`, `lobby:left`, `lobby:ready`, `lobby:match_ready` events |
|
|
| `zod` (`catalog:forms`) | `LobbyConfig`, `LobbyMember` schemas |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Active lobby gauge, match-ready counter |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
interface LobbyConfig {
|
|
gameMode: string
|
|
minPlayers: number
|
|
maxPlayers: number
|
|
countdownSeconds?: number // default 5
|
|
settings?: Record<string, unknown>
|
|
}
|
|
|
|
interface LobbyMember {
|
|
playerId: string
|
|
displayName: string
|
|
isReady: boolean
|
|
joinedAt: number
|
|
isHost: boolean
|
|
}
|
|
|
|
function createLobbyManager(options?: { clock?: Clock }): LobbyManager
|
|
|
|
interface LobbyManager {
|
|
createLobby(config: LobbyConfig): Lobby
|
|
getLobby(lobbyId: string): Lobby | undefined
|
|
destroyLobby(lobbyId: string): void
|
|
listLobbies(filter?: LobbyFilter): Lobby[]
|
|
readonly count: number
|
|
}
|
|
|
|
interface LobbyFilter {
|
|
gameMode?: string
|
|
hasOpenSlots?: boolean
|
|
}
|
|
|
|
interface Lobby {
|
|
readonly id: string
|
|
readonly config: LobbyConfig
|
|
readonly members: ReadonlyMap<string, LobbyMember>
|
|
readonly isCountingDown: boolean
|
|
readonly countdownRemaining: number
|
|
join(playerId: string, displayName: string): void
|
|
leave(playerId: string): void
|
|
setReady(playerId: string, ready: boolean): void
|
|
transferHost(toPlayerId: string): void
|
|
kick(playerId: string): void
|
|
tick(dt: number): void
|
|
}
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type LobbyErrorCode =
|
|
| 'LOBBY_NOT_FOUND'
|
|
| 'LOBBY_FULL'
|
|
| 'LOBBY_MEMBER_NOT_FOUND'
|
|
| 'LOBBY_ALREADY_JOINED'
|
|
| 'LOBBY_NOT_ENOUGH_PLAYERS'
|
|
| 'LOBBY_PERMISSION_DENIED'
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
gaming/multiplayer/lobby/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
constants/index.ts
|
|
types/common.ts
|
|
types/common.md
|
|
core/
|
|
lobby/
|
|
lobby.ts
|
|
lobby.md
|
|
lobby.types.ts
|
|
lobby.test.ts
|
|
index.ts
|
|
lobby-manager/
|
|
lobby-manager.ts
|
|
lobby-manager.md
|
|
lobby-manager.types.ts
|
|
lobby-manager.test.ts
|
|
index.ts
|
|
tests/
|
|
integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream**: `@suaveplan/party` shares member management patterns; `@suaveplan/api-plugin-matchmaking` creates lobbies when a match is found. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`.
|