76 lines
3.5 KiB
Markdown
76 lines
3.5 KiB
Markdown
# Wave C-2 — game-server enhanced: anti-cheat + interest management + lag compensation
|
||
|
||
## Why
|
||
|
||
The `@suaveplan/game-server` package's Wave A–B foundation (core / engine /
|
||
state / network / matchmaking / performance) is in place. The next layer —
|
||
the `enhanced/` family — adds server-authoritative safeguards and
|
||
broadcast-scope optimisations needed for any open-world multiplayer game.
|
||
|
||
Wave C-2 ships the three foundational `enhanced/` modules that are entirely
|
||
self-contained from a dependency standpoint and underpin the rest of the
|
||
`enhanced/` tree (anti-cheat consumed by leaderboard/persistence; interest
|
||
management by state-sync; lag compensation by replay/state-sync):
|
||
|
||
- `enhanced/anti-cheat/anti-cheat-validator/` — server-authoritative move /
|
||
action validator with movement, rate-limit, and custom-action rules;
|
||
player-violation history; punishment escalation FSM.
|
||
- `enhanced/interest-management/interest-manager/` — area-of-interest
|
||
manager: circular/rectangular/custom zones, per-player view-distance
|
||
culling, priority-weighted entity visibility, visibility-change deltas.
|
||
- `enhanced/lag-compensation/lag-compensator/` — server-side state-rewind +
|
||
RTT-aware hit validation: per-entity bounded snapshot ring buffer,
|
||
per-player RTT statistics (avg/min/max/jitter), interpolated state
|
||
lookups, clamped compensation.
|
||
|
||
## What Changes
|
||
|
||
Add three feature modules under `packages/gaming/games/game-server/src/enhanced/`,
|
||
each as a self-contained `5-files-per-feature` directory:
|
||
|
||
- `anti-cheat/anti-cheat-validator/{anti-cheat-validator.ts,.test.ts,.types.ts,.md,index.ts}`
|
||
- `interest-management/interest-manager/{interest-manager.ts,.test.ts,.types.ts,.md,index.ts}`
|
||
- `lag-compensation/lag-compensator/{lag-compensator.ts,.test.ts,.types.ts,.md,index.ts}`
|
||
|
||
Behaviour shift versus the upstream `main` implementation:
|
||
|
||
- Inject `Clock` (and where ids are minted, `IdGenerator`) from
|
||
`@suaveplan/types` rather than reading `Date.now`/`Math.random` directly.
|
||
- Replace ad-hoc `Logger` dependency + `EventEmitter` inheritance with a
|
||
pluggable listener registry (no `@suaveplan/events` runtime dep) and OTel
|
||
metrics for observability.
|
||
- Throw `GameServerError` via the package-wide `GAME_SERVER_CODES` registry
|
||
on invalid input or out-of-bounds operations instead of silently
|
||
returning sentinel values.
|
||
- Validate all caller-supplied configuration with Zod at the boundary.
|
||
|
||
Extend `GAME_SERVER_CODES` with the following new codes (appended, no
|
||
re-order):
|
||
|
||
- `CHEAT_DETECTED`
|
||
- `INVALID_VALIDATION_RULE`
|
||
- `INVALID_ANTI_CHEAT_CONFIG`
|
||
- `INTEREST_REGION_INVALID`
|
||
- `INVALID_INTEREST_CONFIG`
|
||
- `INTEREST_PLAYER_NOT_REGISTERED`
|
||
- `LAG_COMPENSATION_HISTORY_EXCEEDED`
|
||
- `INVALID_LAG_COMPENSATION_CONFIG`
|
||
- `LAG_COMPENSATION_ENTITY_NOT_TRACKED`
|
||
|
||
Extend `package.json` `exports` map additively with subpath exports for the
|
||
three new feature modules.
|
||
|
||
## Impact
|
||
|
||
- Affected specs: `game-server` (new requirements for enhanced anti-cheat,
|
||
interest management, lag compensation).
|
||
- Affected code: `packages/gaming/games/game-server/src/enhanced/**` (new),
|
||
`packages/gaming/games/game-server/src/errors/game-server-error.ts`
|
||
(new codes appended), `packages/gaming/games/game-server/package.json`
|
||
(additive subpath exports), `packages/gaming/games/game-server/src/index.ts`
|
||
(re-exports for the three new modules).
|
||
- Out of scope: all other `enhanced/*` subtrees (leaderboard, persistence,
|
||
replay, tournament, service-discovery, state-sync, timing) — owned by
|
||
Wave C-3/C-4. The orchestrator `src/index.ts` is updated only to add the
|
||
three Wave C-2 re-exports.
|