# GameServerError

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`GameServerError` is the single typed-exception class for the `@suaveplan/game-server` package. It extends `SuaveplanError<GameServerCode>` from `@suaveplan/error`, anchoring every failure raised by the server framework to a stable, lint-checkable code string in the `GAME_SERVER.*` namespace. Callers can branch on `error.code` without depending on `instanceof` semantics that fail across module realms.

The companion `GAME_SERVER_CODES` constant is produced by `defineCodes("GAME_SERVER", [...])` so the registry is verified at compile time and contributes its codes to the global suaveplan error catalog. The registry only enumerates codes that an actual production code path throws today — follow-up migrations (engine, state, matchmaking, telemetry, network) extend the array as their throw sites land, in line with `AGENTS.md` §13.

## Features

- Single typed error class for the entire package.
- Codes resolved through `@suaveplan/error`'s `defineCodes` registry.
- Optional `cause` and `context` for chained diagnostics.
- Compile-time exhaustiveness on the `GameServerCode` union.
- Code namespace `GAME_SERVER.*` is reserved for this package across the workspace.

## Usage: Basic

```typescript
import {
    GAME_SERVER_CODES,
    GameServerError,
} from "@suaveplan/game-server/errors";

try {
    container.resolve("missing");
} catch (err) {
    if (
        err instanceof GameServerError &&
        err.code === GAME_SERVER_CODES.SERVICE_NOT_REGISTERED
    ) {
        // recover by registering a fallback
    }
}
```

## Usage: Advanced

```typescript
import { GameServerError, GAME_SERVER_CODES } from "@suaveplan/game-server/errors";

function loadConfig(input: unknown) {
    const parsed = GameConfigSchema.safeParse(input);
    if (!parsed.success) {
        throw new GameServerError(
            GAME_SERVER_CODES.INVALID_GAME_CONFIG,
            "Game config failed Zod validation",
            { cause: parsed.error, context: { input } },
        );
    }
    return parsed.data;
}
```

The optional `context` bag is logged by the standard `@suaveplan/logger`
formatter and forwarded as OpenTelemetry span attributes by
`@suaveplan/opentelemetry`, so diagnostic data flows without bespoke wiring.

## API Reference

### `GAME_SERVER_CODES`

A frozen object of code constants:

- `SERVICE_NOT_REGISTERED` — thrown by `DIContainer.resolve` on an unknown identifier.
- `INVALID_GAME_CONFIG` / `INVALID_SESSION_METADATA` / `INVALID_PLAYER_INFO` — thrown by the corresponding `parse*` boundary functions in `./types`.
- `INVALID_MOVE` — `AbstractGameLogic.processMove` validation failure.
- `PLAYER_ALREADY_EXISTS` / `PLAYER_NOT_FOUND` — `AbstractGameLogic.{addPlayer,removePlayer}`.
- `LISTENER_LIMIT_EXCEEDED` / `INVALID_LISTENER_COUNT` / `EVENT_WAIT_TIMEOUT` — `GameEventEmitter`.
- `STATE_DIFF_FAILED` / `STATE_PATCH_FAILED` / `STATE_RESTORE_FAILED` / `INVALID_SNAPSHOT` / `STATE_DECOMPRESS_FAILED` / `STATE_SYNC_TRANSPORT_FAILED` — state-manager / differ / compressor / sync.
- `TRANSPORT_ALREADY_INITIALIZED` / `TRANSPORT_NOT_INITIALIZED` / `TRANSPORT_NOT_CONNECTED` / `INVALID_MESSAGE_FORMAT` / `RECONNECT_EXHAUSTED` / `RECONNECT_IN_PROGRESS` — network adapter + reconnection manager + transports.
- `ENGINE_NOT_STARTED` — engine method called before `start()`.
- `ENGINE_ALREADY_STARTED` — second `start()` call on a live engine.
- `ENGINE_DISPOSED` — engine method called after `dispose()`.
- `INVALID_ENGINE_OPTIONS` — Zod failure on `GameEngineOptions`.
- `INVALID_GAME_LOOP_OPTIONS` — Zod failure on `GameLoopOptions`.
- `GAME_LOOP_NOT_RUNNING` — `pause`/`resume`/`stop` called on an idle loop.
- `GAME_LOOP_ALREADY_RUNNING` — second `start()` call on a running loop.
- `PLUGIN_NOT_FOUND` — `uninstall`, `enable`, `disable`, `get` on an unknown plugin name.
- `DUPLICATE_PLUGIN` — `install` called with an already-registered plugin name.
- `PLUGIN_LIFECYCLE_FAILED` — wraps any error thrown from a plugin lifecycle hook.
- `MATCHMAKING_QUEUE_FULL` — `QueueManager.addToQueue` rejected because the per-key queue is at the configured cap.
- `INVALID_QUEUE_REQUEST` — Zod failure on a `QueueRequest` arriving at `QueueManager` / `MatchmakingEngine`.
- `INVALID_MATCH_CRITERIA` — Zod failure on a `MatchCriteria` arriving at `MatchmakingEngine.createMatch`.
- `NO_MATCH_FOUND` — `MatchmakingEngine.createMatch` returned `null` when the caller requested `throwOnNoMatch`.
- `INVALID_SKILL_SCORE` — `SkillMatcher` received a non-finite rating or seeker missing a positive `waitingSince`.
- `SPECTATOR_LIMIT_REACHED` — `SpectatorManager.addSpectator` rejected because the session is at its spectator cap.
- `INVALID_SPECTATOR_REQUEST` — Zod failure on `SpectatorPermissions` or duplicate spectator id.
- `UNKNOWN_MATCHING_ALGORITHM` — `MatchmakingEngine.createMatch` was passed an algorithm string outside the registered union.
- `POOL_EXHAUSTED` — `ObjectPool.acquire` rejected because the pool's `maxSize` is reached and no slots are free.
- `POOL_DISPOSED` — `ObjectPool` method called after `dispose()`.
- `RELEASE_FOREIGN_OBJECT` — `ObjectPool.release` received an object that did not originate from this pool.
- `INVALID_POOL_CONFIG` — `ObjectPool` constructor received a non-positive `initialSize` / `maxSize`, or `maxSize` smaller than `initialSize`.
- `INVALID_TIER_CONFIG` — `NetworkTierAdapter` constructor received an empty / malformed tier list or a node-capability with a non-finite score.
- `UNKNOWN_TIER` — `NetworkTierAdapter` queried for a tier index / node-type that is not registered.

Each value is the fully-qualified string e.g. `"GAME_SERVER.SERVICE_NOT_REGISTERED"`.
The latter six codes are introduced by Wave A (core foundation): `INVALID_MOVE`
fires from `AbstractGameLogic.processMove` when validation fails;
`PLAYER_ALREADY_EXISTS` / `PLAYER_NOT_FOUND` from `addPlayer` / `removePlayer`;
`LISTENER_LIMIT_EXCEEDED` / `INVALID_LISTENER_COUNT` / `EVENT_WAIT_TIMEOUT`
from `GameEventEmitter`.

The state-domain codes added in Wave B-3 (`STATE_*`, `INVALID_SNAPSHOT`)
are thrown by the `state-manager`, `state-differ`, `delta-compressor`,
and `state-sync` modules. `STATE_DIFF_FAILED` and `STATE_PATCH_FAILED`
wrap unexpected exceptions raised while walking deeply-nested structures;
`STATE_RESTORE_FAILED` and `INVALID_SNAPSHOT` surface when callers try to
restore a snapshot whose shape disagrees with the manager's state schema;
`STATE_DECOMPRESS_FAILED` wraps malformed wire packets; and
`STATE_SYNC_TRANSPORT_FAILED` flags transport-layer send/receive faults.

### `type GameServerCode`

Union of all fully-qualified code strings in the registry.

### `new GameServerError(code, message, options?)`

- `code`: `GameServerCode`
- `message`: `string`
- `options?`: `{ cause?: unknown; context?: Record<string, unknown> }`

Instances expose `.code`, `.message`, `.cause` (or `undefined`),
`.context` (or `undefined` when not supplied), and
`.name === "GameServerError"`.

## Implementation Notes

`SuaveplanError` is parameterised over a code union, so removing a code from
the `defineCodes` literal array produces a TypeScript error at every throw
site — this is the lint-checkable contract that keeps the registry minimal
and honest. Codes are flat strings (no nesting) because `@suaveplan/error`'s
canonical form is a single dot-delimited identifier. The class explicitly
sets `this.name` because subclasses of `Error` inherit the parent name in
some runtimes; downstream log scrapers key on the exact string
`"GameServerError"`.