Tier 2 · Networking

Pitfalls: networking

Preserved incident rules and verification for this topic.

Markdown version

Intent-only clients, relevancy, late join, persistence.

Generalized pitfalls from shipped and active projects. Index: the pitfalls page. All entries LOCKED evidence. Status: locked (empirical, seen in shipped/active projects).

  • CLIENTS-SEND-INTENT-ONLY — clients send input or intent, never durable state or outcomes; the server owns movement truth, combat, inventory, rewards and persistence. Check: every client->server message is an input or a request the server validates. See also OWNERSHIP-KEYED-ON-DURABLE-ID (the Netcode overview page). Status: locked (empirical, seen in shipped/active projects).
  • VISIBLE-IS-NOT-RELEVANT — a client-visible entity is not automatically client-relevant; interest management limits bandwidth and cheat exposure. Check: relevance is defined per entity type before high-volume entities ship. Status: locked (empirical, seen in shipped/active projects).
  • RELEVANCY-RADIUS-FITS-THE-FASTEST-MOVER — a relevancy radius sized for weapon range lets fast vehicles pop in late and close. Why: radius ignored closing speed. Check: radius >= (max closing speed x entry latency) plus margin, or pace region entry for fast movers. Status: locked (empirical, seen in shipped/active projects).
  • SCALE-SENDS-BY-IMPORTANCE — with many relevant players at high tick rate, send by importance/distance, not round-robin. Check: ghost/object importance scales with distance; a crowd test reports snapshot size. Status: locked (empirical, seen in shipped/active projects).
  • REWIND-EVERYTHING-YOU-CAN-HIT — lag compensation must rewind every hittable body (NPCs, animals, dummies) and its depth must cover the supported RTT. Check: a lag-comp test at the max supported RTT hits every target class. Status: locked (empirical, seen in shipped/active projects).
  • ONE-SHARED-FRAME-NOT-PER-PLAYER — do not mint coordinate frames/physics worlds per player position. Why: frame creation keyed on the requester. Check: frames are keyed by fixed spatial cells shared by all players. Status: locked (empirical, seen in shipped/active projects).
  • LATE-JOIN-REPLAY-IS-SCOPED-AND-PACED — a late joiner's world replay must be scoped by relevance and streamed, not dumped and throttled. Check: replay only relevant content; queue, never drop, initial-sync requests. See also LATE-JOIN-SNAPSHOT-STREAMS-PER-PIECE. Status: locked (empirical, seen in shipped/active projects).
  • NO-RELIABLE-RPC-FOR-HIGH-FREQUENCY-STATE — high-frequency state goes in replicated snapshots, not reliable RPCs. Check: RPCs are events; per-tick values are ghost fields/NetworkVariables. Status: locked (empirical, seen in shipped/active projects).
  • PREDICTION-STAYS-PENDING — client predictions stay explicitly pending until server confirmation. Check: predicted state is visually and logically distinct until confirmed. Status: locked (empirical, seen in shipped/active projects).
  • RECOMPILE-COPIED-NETCODE — never copy a system from an older netcode package version without recompiling its lifecycle and snapshot APIs against the current package. Check: copied netcode is diffed against the current package API, not just compiled. Status: locked (empirical, seen in shipped/active projects).
  • NETWORKED-OBJECTS-OUTLIVE-MENU-SCENES-ONLY-IF-PLACED-RIGHT — an object spawned while a menu scene is active dies when the client unloads that scene. Why: it was parented to/registered with the menu scene. Check: spawn session objects into a persistent scene or after the gameplay scene is active (DestroyWithScene false where appropriate). Status: locked (empirical, seen in shipped/active projects).
  • ONE-PREFAB-ONE-REGISTRATION-LIST — the same prefab in two network prefab lists unregisters it. Check: one source list per prefab; a validator flags duplicates. Status: locked (empirical, seen in shipped/active projects).
  • MULTIPLAYER-PLAYMODE-PACKAGE-CAN-BE-A-FACADE — verify the multiplayer play-mode package actually contains its runtime on your editor version. Check: confirm the package's assemblies/types exist before relying on it. Status: locked (empirical, seen in shipped/active projects).

Save data

Persistence rules and their incident evidence now live in Save data: durability and authority.

  • SERVER-AND-CLIENT-SHARE-ONE-PLACEMENT-PATH — when server and client both generate the same procedural content, they must run the same code path. Why: two implementations of "the same" math diverge. Check: one shared deterministic function (same compilation mode) or the server replicates the result; a parity test compares both outputs. Status: locked (empirical, seen in shipped/active projects).
  • WORLD-EVENTS-ARE-SEEN-BY-EVERYONE — a state change triggered by one player (felling, destroying, opening) must replicate to all observers, not play only on the actor's client. Why: the effect was client-local and the authoritative update rode a long cadence. Check: every world mutation has a replicated event or state change; test with a second client watching. Status: locked (empirical, seen in shipped/active projects).