Unity Networking Multiplayer

Unity Networking & Multiplayer

Retrieval Sources

All paths are relative to /media/artiq/FRESH_DRIVE/Books/Unity6/Documentation/en/. Re-verified on disk for this pass via find/grep over the full Manual/ (3,476 HTML files) and ScriptReference/ (35,594 HTML files) trees.

Re-verified negative finding — still true this pass: no NGO/Relay/Lobby API reference is mirrored locally. Specifically, find/grep across both Manual/ and ScriptReference/ for *NetworkBehaviour*, *NetworkObject*, *NetworkVariable*, *ServerRpc*, *ClientRpc*, *NetworkManager*, *NetworkTransform*, *relay*, *lobby*, Unity.NetCode.* (Entities API), and Unity.Networking.Transport.* (Transport API) as filenames return zero matches (the *network* filename search returns 260 hits, all UnityEngine.Networking.* (UnityWebRequest/PlayerConnection), Profiling.ProfilerArea.Network*, or unrelated iOS/XR/Physics API pages — not NGO). A content-level grep (not just filenames) across every Manual and ScriptReference file for NetworkBehaviour|NetworkObject|ServerRpc|ClientRpc turns up exactly two substantive hits, both release notes (WhatsNewUnity6.html, UpgradeGuideUnity63.html — rows 25–26 above), not API documentation. Bottom line: this doc mirror carries the package/platform/Building-Block layer (what exists, how to set it up, prerequisites, build targets) in real depth, but the NGO/Transport/Netcode-for-Entities scripting API and the Relay/Lobby service API live only at docs-multiplayer.unity3d.com and Unity Services docs — never fabricate specific method signatures as if sourced locally; label pretrained-knowledge API claims as such (done throughout Key Guidelines below) and confirm exact signatures in-editor via Package Manager > Netcode for GameObjects > API docs, or online, before shipping code from them.

Key Guidelines

NGO Core Concepts (pretrained knowledge — not locally documented, verify signatures in-editor/online)

NetworkObject is the unit of network identity: attach it to any prefab or scene GameObject that needs to be spawned, despawned, owned, or observed across the network. NetworkBehaviour is the networked equivalent of MonoBehaviour — it's where NetworkVariable<T> fields and RPC methods live, and it requires a NetworkObject on the same GameObject (or a parent) to function. A single NetworkObject can carry multiple NetworkBehaviours. Ownership (IsOwner, IsServer, IsClient, IsHost) determines who is allowed to write which networked state, and is the first thing to check in any callback whose behavior should differ between server and client.

using Unity.Netcode;

public class PlayerHealth : NetworkBehaviour
{
    // Server writes, everyone reads — the standard permission pairing for synced state.
    public NetworkVariable<int> Health = new NetworkVariable<int>(
        100,
        NetworkVariableReadPermission.Everyone,
        NetworkVariableWritePermission.Server);

    public override void OnNetworkSpawn()
    {
        Health.OnValueChanged += (oldValue, newValue) => UpdateHealthBar(newValue);
    }
}

RPCs move discrete, one-off events across the wire rather than continuous state: ServerRpc for client→server requests (e.g. "I want to fire"), ClientRpc for server→client notifications (e.g. "you were hit"). A ServerRpc method conventionally ends in the suffix ServerRpc and is decorated with [ServerRpc]; add RequireOwnership = false only when a non-owner client legitimately needs to call it.

[ServerRpc]
private void RequestFireServerRpc(Vector3 origin, Vector3 direction, ServerRpcParams rpcParams = default)
{
    // Server is authoritative: recompute the shot server-side, never trust origin/direction blindly
    // for damage — validate against last known server-side transform/cooldown before applying effects.
    if (!CanFire(rpcParams.Receive.SenderClientId)) return;
    ApplyShotServerSide(origin, direction);
    NotifyHitClientRpc(origin, direction);
}

[ClientRpc]
private void NotifyHitClientRpc(Vector3 origin, Vector3 direction)
{
    PlayMuzzleFlashAndTracer(origin, direction); // cosmetic only — safe to trust, it's server-sent
}

Spawn and despawn networked objects only through the network spawn flow — NetworkObject.Spawn() (server-only call, typically after Instantiate()) and NetworkObject.Despawn(). A bare Instantiate() with no follow-up Spawn() call produces a local-only GameObject with no network identity; clients never see it. Register every networked prefab in the NetworkManager's prefab list (Network Prefabs Lists asset in modern NGO) on every peer before it can be spawned at runtime — a missing registration throws or silently fails to spawn on the peers that lack it.

Server Authority & Security

Default to server-authoritative design for anything that affects fairness, persistence, or the game economy: movement validation, damage/hit registration, currency, inventory, matchmaking rank. Clients send intent (inputs, requested actions); the server computes the resulting state and is the only source of truth that gets replicated back out. This is what makes the design resistant to a modified client — an attacker can rewrite their own client freely, but every packet they send is just a request the server is free to reject or reinterpret. Pure client-authoritative movement (client owns and broadcasts its own transform) is simpler and lower-latency to build, and is a reasonable tradeoff for a couch-coop or non-competitive game, but is trivially cheatable (speed hacks, teleports) in anything competitive.

Never trust client-sent data for logic that must be fair or must persist. That means every ServerRpc body should treat its parameters as attacker-controlled input: reclamp values, revalidate cooldowns/state machines, and recompute outcomes server-side rather than accepting a client's claimed result.

[ServerRpc]
private void SubmitScoreServerRpc(int reportedDelta)
{
    // WRONG pattern (do not do this): Score.Value += reportedDelta;
    // Right pattern: derive the actual delta from server-tracked game state.
    int verifiedDelta = ComputeScoreDeltaFromServerState();
    Score.Value += verifiedDelta;
}

Set NetworkVariable read/write permissions deliberately at declaration time (NetworkVariableWritePermission.Server for anything security-sensitive) rather than discovering at runtime that a client could write to state it shouldn't touch — NGO enforces the permission you declared, but a permissive default chosen out of laziness is a real vulnerability, not a hypothetical one. A listen-server host runs both the server and a local client in the same process; guard server-only branches with IsServer (not just "am I the host's player") so the host doesn't get an unfair, client-invisible advantage from code that silently skips validation for itself.

Relay & NAT Traversal

Relay solves NAT traversal: most players sit behind a home router or CGNAT that makes their machine unreachable from the public internet, so direct peer connections routinely fail. Relay is a Unity-hosted cloud service that all connecting peers dial out to (an outbound connection, which almost every NAT/firewall permits), and it forwards traffic between them — no port-forwarding, no public IP, no UPnP configuration required from the player. In an NGO project, Relay is plugged in as the underlying connection for Unity Transport: the transport's relay server data (host/client join data, obtained from the Relay service after allocating/joining a relay session) is set on the UnityTransport component before NetworkManager.StartHost()/StartClient() is called.

// Pretrained-knowledge sketch of the allocate → set relay data → start host flow.
// Verify exact Relay SDK method names/signatures online — not in this local doc mirror.
var allocation = await RelayService.Instance.CreateAllocationAsync(maxConnections: 8);
string joinCode = await RelayService.Instance.GetJoinCodeAsync(allocation.AllocationId);

var relayServerData = new RelayServerData(allocation, "dtls"); // "dtls" or "udp" connection type
NetworkManager.Singleton.GetComponent<UnityTransport>().SetRelayServerData(relayServerData);
NetworkManager.Singleton.StartHost();

A join code is the short human-shareable string players exchange to find each other's Relay allocation; joining clients call the Relay join-by-code API to fetch their own RelayServerData, then start as a client rather than a host. Relay adds one extra network hop of latency versus a direct connection or a co-located dedicated server, which is the tradeoff for guaranteed connectivity.

Lobby / Sessions & Matchmaking

Lobby (or, in the local doc mirror's terms, the Multiplayer Sessions Building Block) solves discovery, not gameplay sync: it lets players create a session with metadata (name, game mode, player count, public/private), browse or query for open sessions, and join one — all before any Relay/NGO connection exists. Per Manual/building-blocks-multiplayer-sessions.html, the pattern locally documented covers create/join via the Multiplayer Services SDK, a Quick Join API (join any matching open session without browsing), a Session Browsing API (list-and-pick), and JoinCode-based direct sharing — and it explicitly integrates with NGO/Netcode-for-Entities/Unity Transport once a session is chosen, meaning the session layer's job ends where the connection layer's job begins. Per Manual/WhatsNewUnity6.html, the Multiplayer Services package's session system can back three different topologies: peer-to-peer (P2P), Dedicated Game Server, and Distributed Authority sessions — the app picks which at session-creation time via SessionType.

Matchmaker (Matchmaker Session Building Block) is a step earlier still: instead of a human browsing a session list, players submit into a queue and a rule-based matching service groups them automatically (skill, region, mode). Per Manual/building-blocks-multiplayer-matchmaking.html, queue configuration is authored as an asset in the Unity project and deployed to Unity's cloud services so it's live for Play Mode testing; once the Matchmaker groups a set of players by its rules, the app is responsible for turning that group into an actual connected session (again typically via NGO).

// Sketch — Sessions SDK shape, not verified against a locally-mirrored API reference.
var sessionOptions = new SessionOptions
{
    MaxPlayers = 8,
    IsPrivate = false
}.WithRelayNetwork(); // ties the session to a Relay-backed NGO connection under the hood

ISession session = await MultiplayerService.Instance.CreateSessionAsync(sessionOptions);
string joinCode = session.Code; // share this out-of-band, or let others Quick Join/browse instead

Host vs Dedicated Server

A listen-server host is a player's own client process that also runs the authoritative server logic in the same build — simplest to ship (one build, one process, no separate infra), but the host's machine and connection quality become a single point of failure/lag for every other player, and if the host quits, the session typically ends unless host migration is implemented. A dedicated server is a separate headless process, running nobody's local player camera/input, whose only job is to be authoritative; players connect to it purely as clients. This is what the local dedicated-server-* doc tree (rows 15–24) covers in real depth: the Dedicated Server build target is a sub-target of the Desktop platforms (Linux/macOS/Windows) purpose-built to cut CPU, memory, and disk versus a normal player build, by stripping rendering- and audio-only code paths that a headless process never needs.

Automatic optimizations the Dedicated Server target applies (per Manual/dedicated-server-optimizations.html): the Audio Subsystem is deactivated outright, lighting-related threads are removed, several PlayerLoop callbacks are disabled, and GPU-only assets are stripped from the build. Building one requires installing the platform-specific "Dedicated Server Build Support" module via Unity Hub (e.g. "Linux Dedicated Server Build Support"), then using File > Build Profiles > Add Build Profile to pick the server sub-target, Switch Profile, and Build (Manual/dedicated-server-build.html, Manual/dedicated-server-requirements.html). AssetBundles get the same treatment by setting subtarget = StandaloneBuildSubtarget.Server on BuildAssetBundlesParameters (Manual/dedicated-server-assetbundles.html). Don't confuse this with plain desktop headless mode (-batchmode -nographics command-line flags on an ordinary Desktop build) — headless mode skips graphics device init but applies none of the Dedicated Server target's memory/CPU stripping, and can't be selected from Editor Build Settings (Manual/desktop-headless-mode.html).

Per Manual/WhatsNewUnity6.html, Unity 6.0 also introduced Multiplayer roles, a content-stripping system letting one project build cleanly into either a Client or Server role: Content Selection (choose which GameObjects/Components exist per role), Automatic Selection (auto-remove component types per role), and Safety Checks (warn about null-reference risk from role-based stripping) — this is what lets a single project ship both a player build and a dedicated-server build without maintaining two codebases.

Important currency note (Manual/UpgradeGuideUnity63.html, verified locally): Multiplay Hosting is deprecated as of Unity 6.3 — no longer supported in the Editor or at runtime; the hosted service itself keeps running only through March 31, 2026, after which it shuts down entirely, and the default Multiplayer Services package (2.0.0) has already dropped Multiplay-Hosting-specific functionality. Any new dedicated-server-hosting design should target a different hosting path (self-managed infrastructure, or whatever successor service Unity documents online) rather than Multiplay Hosting.

WebGL Networking Constraints

Per Manual/webgl-networking.html (full local page content), Web/WebGL builds support networking in exactly two ways: UnityWebRequest, and the Unity Netcode networking package. UnityWebRequest on Web is implemented via the browser's JavaScript Fetch API, which means it inherits full browser security restrictions — same-origin policy and CORS. A request to any origin other than the one hosting the Unity content fails unless that origin's server sends the right Access-Control-Allow-* response headers; a missing/misconfigured CORS header surfaces as a browser-console error ("Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource..."), not a Unity-side exception. Never block synchronously on a UnityWebRequest (while(!www.isDone) {}) — browsers disallow blocking the main thread on a network transfer; use a coroutine with yield return www.SendWebRequest(); instead.

The more fundamental constraint: browsers do not allow direct access to raw TCP or UDP sockets, for any code, for any reason — this is a browser sandbox rule, not a Unity limitation, and it's why Unity Transport's normal UDP-based NGO connection simply cannot run inside a WebGL build unmodified. The documented fix is to route through the Unity Netcode networking package's Web-compatible transport path (WebSocket-based under the hood, since WebSockets are one of the few socket-like primitives browsers do expose) rather than attempting a raw UDP relay/host connection from a WebGL client. The page further points to the WebSocket Protocol and WebRTC specs as background reading for anyone building a custom Web-compatible transport.

#if UNITY_WEBGL && !UNITY_EDITOR
    // WebGL clients cannot open raw UDP sockets — ensure the transport config
    // actually resolves to a WebSocket-capable path before calling StartClient(),
    // and never assume the same UnityTransport settings that work on Desktop/Console
    // will connect from a WebGL build without verification.
#endif

Common Mistakes

Quick Reference

Advanced Notes

Client-server vs. peer-to-peer, chosen deliberately. Client-server (whether via a listen-server host or a true dedicated server) centralizes authority in one place, which is what makes anti-cheat, persistence, and debugging tractable: there is exactly one process whose state is ever "true," every other participant is a client reporting intent and rendering a replica. The cost is infrastructure — someone has to run that authoritative process, whether that's a player's own machine (host, free but unreliable/exploitable) or a real server (dedicated, costs money/ops but reliable and secure). Peer-to-peer removes that infrastructure cost — every participant talks directly to every other participant, with no single owned "truth" — but pays for it twice over: NAT traversal is harder because every pair of peers needs a working path (not just each peer to one server), and security is harder because there's no natural place to put validation — any peer asserting authority over some piece of state is exactly as trustworthy (or untrustworthy) as a modified client would be in a client-server design. This is why most real NGO projects that use P2P at all restrict it to non-competitive or cosmetic-stakes games, or layer a lightweight arbitration scheme (e.g. Distributed Authority, where ownership of specific objects is handed to whichever peer is best positioned to own them, with the platform/service still mediating who's allowed to claim what) on top rather than running fully trustless P2P. Unity's own Multiplayer Services package (per Manual/WhatsNewUnity6.html, verified locally) treats all three — P2P, Dedicated Game Server, and Distributed Authority — as first-class session types precisely because the right choice is genuinely per-project, trading off cost, latency, cheat-resistance, and ops burden differently each time.

Where the full NGO/Relay/Lobby docs actually live, since they aren't local:

• Netcode for GameObjects (concepts, full API reference, tutorials, samples): docs-multiplayer.unity3d.com — "About Netcode for GameObjects (Unity Multiplayer Networking)" is the entry point this local doc set's own webgl-networking.html page links out to.
• Unity Relay, Unity Lobby, Multiplayer Services SDK (session/matchmaking APIs, Distributed Authority setup): Unity Gaming Services documentation at docs.unity.com (Multiplayer Services section) and the Unity Dashboard's own in-product docs/reference for each service.
• Unity Transport low-level API (NetworkDriver, NetworkConnection, pipeline stages): also docs-multiplayer.unity3d.com, under the Transport section — not mirrored in this Manual/ScriptReference download despite the package landing page existing locally.
• In-editor fallback when offline: Package Manager > select the installed Netcode for GameObjects / Unity Transport / Multiplayer Services package > "View documentation" opens the bundled offline API docs shipped inside the package itself, which do contain full scripting API detail even though this local Documentation/en mirror does not.
• Release-note-level ground truth for exact current-version behavior changes: this local mirror's own Manual/WhatsNewUnity6.html and Manual/UpgradeGuideUnity63.html are surprisingly reliable for recent NGO/Multiplayer-Services/Multiplayer-Tools changes (see Retrieval Sources rows 25–26) even though they aren't structured as API references — check them before asserting how a specific NGO version behaves.