Phase 3: Many Players

This phase is still ahead.

Ships

v0.3.0

Lesson

Latency hiding, client prediction, reconciliation, interest management, bandwidth, load testing and profiling

Depends on

Phase 2

• Decision Position representation: fixed-point integers (for example 1/16 pixel) so client and server compute identical results.
• Movement extracted into a pure step function with identical rules on both sides, documented in docs/design/movement.md.
• Shared test vectors: Go generates input sequences and expected positions; GDScript replays them and must match exactly.

• Client applies local input immediately and keeps a buffer of unacknowledged inputs.
• On each snapshot, the client rewinds to the server’s state for its player and replays pending inputs.
• Small errors are smoothed out visually; large errors snap. Corrections are counted in the debug overlay.
• Prediction can be toggled from the debug menu for side-by-side comparison.

• Decision Spatial index: a uniform grid (recommended) with a cell size chosen by measurement, updated as entities move.
• Per-player area of interest with hysteresis (enter radius smaller than leave radius) so entities don’t flicker at the edge.
• Enter and leave messages driven by area changes; snapshots include only entities in the area.
• Tests at cell boundaries and with fast movement, and a benchmark of grid updates and queries with 1,000 entities.

• Measure bytes per snapshot and per client per second, shown in the debug overlay and exported by the server.
• Decision Snapshot optimization on top of ADR 0008’s changed-only snapshots: quantization and smaller encodings of changed entities (for example position deltas). Implement it and measure the savings.
• Encode once with interest management: each changed entity encoded once per tick and shared by every recipient that can see it, with a benchmark showing encode cost independent of recipient count.
• Per-client bandwidth with 100 bots spread across the map, before and after interest management, in docs/perf/phase-03.md.

• Prometheus text-format metrics on a localhost-only admin port: connections, players per zone, tick duration histogram, inbox and send-queue depth, drops, evictions, messages and bytes in and out, goroutines and GC.
• pprof on the same localhost-only admin port; one profiling pass at 1,000 bots completed and any hotspot fixed, with before and after in docs/perf/.
• Decision GC settings: measure GOGC and GOMEMLIMIT under Case 2 load and record the chosen defaults.

• Bot swarm: lorehallow-bot -n 100 with wander, follow and idle behaviors and configurable latency.
• The bot generator runs 5,000 bots from one process, with its own CPU and memory reported, and can spread bots across several source addresses to get past ephemeral-port limits.
• make loadtest covers the scaling.md scenarios idle, spread, crowd, churn, slow and hostile (storm and reconnect join in Phase 4, burst in Phase 6).
• Load test script reporting tick time p50 and p99, CPU, memory and bandwidth at 10, 50 and 100 bots, with results in docs/perf/phase-03.md.
• Every Tier 1 target in scaling.md, and Case 1 Tier 2 (1,000 connections), measured on dev-m5 and recorded in docs/perf/phase-03.md.
• Race detector clean during a load test run.
• One-hour soak (scaling.md short soak) on dev-m5.

• Draw Batch 04 by hand: three or four player appearance variants and a townsfolk placeholder, so a crowd reads as different people.
• Intake and integrate; bots pick random appearances.

• docs/walkthroughs/phase-03-many-players.md: prediction, reconciliation, fixed-point simulation, interest management, and measuring and reducing bandwidth.
• Devlog draft, release notes, tag v0.3.0 and publish builds.

• With 150 ms simulated latency, your own movement responds on the next frame and corrections aren’t noticeable in normal play.
• With 100 bots spread across the map, per-client bandwidth is at least 70% lower than broadcasting everything.
• Case 1 Tier 2 (1,000 connections), Case 2 Tier 1 (100 active players) and Case 3 Tier 1 (100 in one area) in scaling.md are met on dev-m5.
• With 10% slow clients and 100 hostile bots, healthy players’ tick p99 and bandwidth stay within 10% of a clean run (scaling.md).
• The one-hour soak passes: no memory growth, flat goroutines, no tick drift.
• 100 bots on the production host keep server tick p99 under 12.5 ms (a quarter of the tick budget).
• Owner Playtest: at least 3 real players plus 200 bots on the live server feels smooth.
• The walkthrough explains prediction, reconciliation and interest management with diagrams.