unity-networking

Unity Networking and Multiplayer

Overview

Reference for implementing multiplayer systems and backend services in Unity. Covers the major networking frameworks, authority models, common multiplayer patterns, and Unity Gaming Services integration.

Networking Framework Comparison

Framework	Type	Best For	License
Netcode for GameObjects (NGO)	Client-hosted / Dedicated	Unity-native projects, UGS integration	Free (Unity)
Mirror	Client-hosted / Dedicated	Open-source alternative, mature ecosystem	MIT
Photon PUN 2	Cloud-hosted	Quick prototyping, room-based games	Free tier + paid
Photon Fusion 2	Cloud/Self-hosted	Competitive games, tick-based simulation	Free tier + paid
Fish-Net	Client-hosted / Dedicated	Performance-critical, Mirror alternative	MIT

Netcode for GameObjects (NGO)

Setup

1. Install via Package Manager: com.unity.netcode.gameobjects
2. Add NetworkManager to a scene GameObject
3. Select transport (Unity Transport is default)
4. Mark networked prefabs with NetworkObject component
5. Register prefabs in NetworkManager's prefab list

Core Components

Component	Purpose
NetworkManager	Manages connections, spawning, scene management
NetworkObject	Required on all networked GameObjects
NetworkBehaviour	Base class for networked scripts (replaces MonoBehaviour)
NetworkVariable<T>	Synchronized variable with ownership/permissions
NetworkTransform	Automatic position/rotation sync
NetworkAnimator	Automatic Animator parameter sync

RPCs (Remote Procedure Calls)

public class PlayerCombat : NetworkBehaviour
{
    NetworkVariable<int> _health = new(100,
        NetworkVariableReadPermission.Everyone,
        NetworkVariableWritePermission.Server);

    [ServerRpc]
    void AttackServerRpc(ulong targetId)
    {
        // Runs on server - validate and apply damage
        if (!IsServer) return;
        var target = NetworkManager.SpawnManager.SpawnedObjects[targetId];
        target.GetComponent<PlayerCombat>().TakeDamage(10);
    }

    [ClientRpc]
    void PlayHitEffectClientRpc(Vector3 position)
    {
        // Runs on all clients - visual feedback only
        Instantiate(hitVFX, position, Quaternion.identity);
    }

    void TakeDamage(int amount)
    {
        _health.Value -= amount;
        PlayHitEffectClientRpc(transform.position);
    }
}

RPC Type	Direction	Use For
[ServerRpc]	Client -> Server	Player actions, requests
[ClientRpc]	Server -> All Clients	VFX, sound, UI updates
[ClientRpc(SendTo.Owner)]	Server -> Owner Client	Owner-specific feedback

NetworkVariable Permissions

// Server-writable (default) - authoritative state
NetworkVariable<int> score = new(0, writePerm: NetworkVariableWritePermission.Server);

// Owner-writable - client-authoritative (use sparingly)
NetworkVariable<Vector3> cursorPos = new(writePerm: NetworkVariableWritePermission.Owner);

Use OnValueChanged callback for UI reactions:

_health.OnValueChanged += (oldVal, newVal) => healthBar.value = newVal;

Authority Models

Model	Description	When to Use
Server-Authoritative	Server validates all actions, clients are thin	Competitive, anti-cheat critical
Client-Authoritative	Clients own their state, server relays	Cooperative, trust-based
Client Prediction + Server Reconciliation	Client predicts locally, server corrects	FPS, fast-paced action
Relay / Listen Server	One player hosts, others connect via relay	Casual, small lobbies

Server-Authoritative Flow

Client: Press "Attack" -> Send ServerRpc(targetId)
Server: Validate range/cooldown -> Apply damage -> Update NetworkVariable
Server: Send ClientRpc for VFX
All Clients: Play hit effect

Never trust client data. Validate positions, cooldowns, ammunition, and line-of-sight on the server.

Common Multiplayer Patterns

Lobby System

1. Player authenticates (UGS Auth / custom)
2. Player creates or joins lobby (UGS Lobby / custom)
3. Lobby fills -> host starts game
4. Relay allocation for NAT traversal (UGS Relay)
5. All players connect to relay
6. NetworkManager starts host/client

Spawn and Despawn

// Server-side spawning
var instance = Instantiate(prefab, spawnPoint, Quaternion.identity);
instance.GetComponent<NetworkObject>().SpawnWithOwnership(clientId);

// Server-side despawning
networkObject.Despawn(); // Removes from all clients

Scene Management

Use NetworkManager.SceneManager.LoadScene("GameScene", LoadSceneMode.Single) for synchronized scene loading. Only the server/host should call this.

REST API and WebSocket Integration

REST API (UnityWebRequest)

async Awaitable<T> GetAsync<T>(string url)
{
    using var request = UnityWebRequest.Get(url);
    request.SetRequestHeader("Authorization", $"Bearer {token}");
    await request.SendWebRequest();
    if (request.result != UnityWebRequest.Result.Success)
        throw new Exception(request.error);
    return JsonUtility.FromJson<T>(request.downloadHandler.text);
}

Use JsonUtility for simple types or Newtonsoft.Json (com.unity.nuget.newtonsoft-json) for complex serialization. Always use using with UnityWebRequest to prevent memory leaks.

WebSocket (NativeWebSocket / WebSocketSharp)

For real-time non-game communication (chat, notifications), use a WebSocket library. NativeWebSocket works across platforms including WebGL.

Unity Gaming Services (UGS)

Service	Package	Purpose
Authentication	com.unity.services.authentication	Anonymous/platform sign-in
Lobby	com.unity.services.lobby	Room creation, matchmaking
Relay	com.unity.services.relay	NAT traversal for P2P
Cloud Save	com.unity.services.cloudsave	Server-side player data
Leaderboards	com.unity.services.leaderboards	Ranked scoreboards
Economy	com.unity.services.economy	Virtual currencies, purchases
Analytics	com.unity.services.analytics	Player behavior tracking
Matchmaker	com.unity.services.matchmaker	Skill-based matchmaking

Initialize UGS before using any service:

await UnityServices.InitializeAsync();
await AuthenticationService.Instance.SignInAnonymouslyAsync();

Firebase and PlayFab

Use Firebase for indie/mobile projects needing Realtime Database, Cloud Functions, and FCM push notifications. Use PlayFab for LiveOps-heavy games needing player segmentation, A/B testing, and automated rule processing. Both provide Unity SDKs via their respective download pages.

Additional Resources

Reference Files

• references/netcode-advanced.md -- Client prediction and reconciliation implementation, interest management, network LOD, bandwidth optimization, custom serialization, transport layer configuration
• references/backend-services.md -- Detailed UGS setup walkthroughs, Firebase/PlayFab integration patterns, REST API architecture, authentication flows, leaderboard and economy implementation