Multiplayer Game Architecture

Multiplayer Game Architecture

Build the multiplayer contract before writing netcode. The output is a reviewable multiplayer-contract.json, not a framework recommendation disguised as architecture. Topology, authority, replication, transport, session lifecycle, security, and tests must agree with one another.

When to use this skill

Use it to:

• design or review a new multiplayer game's networking model;
• retrofit multiplayer into an existing game without mixing client and server truth;
• choose authority and replication per state domain;
• compare browser or engine transports against actual delivery needs;
• define lobby, allocation, join, reconnect, late-join, finish, and shutdown behavior;
• investigate desync, prediction error, cheating, host migration, or network instability;
• turn vague goals such as "make it multiplayer" into an executable contract and test matrix.

Do not use it for local couch multiplayer, generic game mechanics, visual UI, build logs, frame-time profiling, or cloud deployment by itself. Route concrete Unity APIs to unity-technologies-skills, Three.js/browser gameplay to web-game-development, red builds to game-build-log-triage, release automation to game-ci-cd-pipeline, service tests to backend-testing, and production telemetry to monitoring-observability.

Instructions

1. Freeze the session envelope

Inspect the existing repository and record:

• player count range, pace, session length, and join model;
• casual, cooperative, ranked, or adversarial fairness needs;
• target platforms, regions, and browser or console constraints;
• simulation ownership, persistence, hidden information, and existing backend services;
• late join, reconnect, spectator, host migration, and protocol-version expectations.

Ask only for blockers. If answers are unavailable, state assumptions explicitly instead of silently choosing a stack.

2. Choose topology before transport

Pick one primary model and explain the trust boundary:

• Dedicated authoritative server: use when fairness, persistence, hidden state, or independent match continuity outweighs hosting cost.
• Listen server: use for trusted or low-stakes sessions only after defining host advantage, host loss, migration, and cheat risk.
• Relay-assisted peer: use when direct reachability or privacy needs a relay, but do not confuse encrypted transport with authoritative gameplay.
• Deterministic lockstep: use only when the simulation can stay deterministic across target platforms and the wait-for-input tradeoff fits the game.
• Asynchronous service: use for turn, command, or state-transition games that do not need a continuous real-time simulation.

Do not choose WebSocket, WebRTC, WebTransport, UDP, or a vendor SDK until this decision is stable. Transport is a delivery mechanism, not an authority model.

3. Write an authority matrix

For every gameplay-critical domain, name the writer, allowed client intent, and authority validation. Cover at least movement, combat or actions, inventory, economy, match state, and hidden information when they exist.

Clients may own presentation, local input collection, and speculative visuals. They must not author trusted outcomes merely because their connection is encrypted. Avoid sending hidden state that a client should never know.

4. Select the replication model per data class

Choose only the mechanisms the game needs:

• turn or command replication for discrete state transitions;
• authoritative state snapshots or deltas for non-deterministic real-time worlds;
• input lockstep for deterministic simulations;
• local prediction plus server reconciliation for latency-sensitive owned movement;
• interpolation for remote entities and replaceable visual state;
• bounded lag compensation only for mechanics whose fairness policy permits rewind;
• relevance, priority, and interest management when every client does not need every entity.

Never copy an engine's default tick or snapshot rate into the contract. Record a proposed value only with a mechanics-based budget, profiling evidence, and a measurement plan.

5. Choose channels and fallbacks

For browser games, verify the current target-browser matrix before choosing:

• WebSocket is broadly supported and simple for bidirectional client-server traffic, but the classic browser API has no backpressure;
• RTCDataChannel provides encrypted peer data channels and configurable delivery, but still needs signaling and does not solve gameplay authority;
• WebTransport provides HTTP/3 streams and datagrams, but requires HTTPS/server support and a compatibility decision for older targets.

Map each message class to reliability, ordering, freshness, size, and overflow behavior. Use separate logical channels where reliable bulk traffic would block time-sensitive state. Define fallback and resync behavior rather than assuming the network is healthy.

6. Define lifecycle and security together

Specify queue or invite, match formation, server allocation, authentication, join, ready, play, reconnect, finish, persistence, and shutdown as explicit states. Keep matchmaking, server allocation, and game simulation as separate responsibilities.

For every inbound message, define schema validation, identity, authorization, sequence or nonce handling, rate and size limits, and state-machine legality. Browser WebSocket work also needs TLS, origin allowlisting, session expiry, per-message authorization, backpressure, bounded queues, and content-safe logging.

Never provision servers, enable a paid matchmaking service, deploy, publish, or use live credentials without separate approval.

7. Make failure observable and testable

Define metrics and correlation fields before implementation. Include join success, round-trip and server-step distributions, queue depth, dropped or rejected messages, prediction corrections, desyncs, reconnect outcomes, and protocol-version failures as applicable.

Test at least one clean and one impaired network condition. Add latency, jitter, loss, reordering, duplication, bandwidth pressure, disconnect, reconnect, server pause, and version mismatch only where the chosen transport can exhibit them. Test two real clients or processes, not two local objects sharing state. Derive acceptance thresholds from the game's mechanics and target population instead of using universal numbers.

Read references/verification-matrix.md for the full evidence checklist.

8. Write and validate the contract

From this skill directory, start with references/contract-example.json, replace every example value, and run:

python3 scripts/validate-contract.py multiplayer-contract.json
python3 scripts/validate-contract.py --self-test

The validator checks structure, authority coverage, product-specific tick rationale, competitive peer-risk acceptance, security controls, clean and impaired test cases, and unresolved placeholders. It is read-only and dependency-free.

Return this routing packet:

### Multiplayer architecture packet
- Primary topology: <model and reason>
- Authority risk: <highest-risk state domain>
- Replication: <model per data class>
- Transport: <primary, fallback, and compatibility evidence>
- Lifecycle gap: <largest unresolved transition>
- Verification: <contract path, validator result, and missing evidence>
- Next owner: <implementation or route-out skill>

Examples

Ranked real-time action game

Choose dedicated authority, send client intent rather than outcomes, predict only owned latency-sensitive movement, reconcile to server sequence numbers, interpolate remote state, and test correction behavior under measured impairment. Do not accept peer authority just because it is cheaper.

Four-player turn-based co-op

Prefer a command/state-transition model. Reliable ordered delivery may be enough; prediction and lag compensation add complexity without player value. Make commands idempotent, define reconnect snapshots, and keep hidden hands on the authority.

Existing Unity prototype

Write the engine-neutral contract here, then route concrete transport, RPC, NetworkObject, Multiplayer Services, or Dedicated Server work to unity-technologies-skills. Do not let an SDK selection replace the authority matrix.

Best practices

1. Decide per-domain authority before selecting transport, SDK, or hosting.
2. Derive budgets from project evidence and verify process separation plus adverse networks.
3. Keep hidden state and secrets on the authority, and approve live or paid actions separately.

References

• references/candidate-audit.md: exact-name survey of the ten pictured candidates and selection rationale.
• references/architecture-decisions.md: topology, replication, transport, lifecycle, and authority decision tables.
• references/verification-matrix.md: impairment, security, lifecycle, and evidence checks.
• references/contract-example.json: complete contract accepted by the validator.
• references/source-notes.md: claim-to-source ledger using current first-party and primary references.
• scripts/validate-contract.py: Python 3.9+ contract validator and self-test.