🔄 Lesson 6.3: NetworkVariables & State Synchronization

Keeping State in Agreement

Persistent shared state — anything that "is true for a while" — must read the same on every machine: a player's health, the match score, whose turn it is, whether a gate is open. You could send these manually with messages, but you'd have to handle initial sync (a client joining mid-match needs the current values), change detection, and reliability yourself.

A NetworkVariable handles all of that. Declare one on a NetworkBehaviour, write it on the server, and Netcode replicates the value to every client — including late joiners, who receive the current value on spawn — and tells each client whenever it changes. It's the workhorse of "server writes, clients read" from Lesson 6.1.

Declaring a NetworkVariable

A NetworkVariable is a field on a NetworkBehaviour, constructed with an initial value and two permissions — who may read it and who may write it:

using Unity.Netcode;
using UnityEngine;

public class PlayerHealth : NetworkBehaviour
{
    // Everyone can READ; only the SERVER can WRITE (the authoritative default).
    public NetworkVariable<int> Health = new NetworkVariable<int>(
        100,
        NetworkVariableReadPermission.Everyone,
        NetworkVariableWritePermission.Server);
}

NetworkVariableReadPermission.Everyone lets all clients read the value (the usual choice — clients need to display it). NetworkVariableWritePermission.Server means only the server may set it, enforcing authority at the type level. There's also Owner write permission for owner-authoritative designs, but server write is the safe default — a client can't forge the value because it isn't allowed to write it.

Write, Replicate, React

The server writes .Value; every client's copy updates automatically. Here's the full picture:

// Server-side gameplay. Only the server may write, so guard it.
public void TakeDamage(int amount)
{
    if (!IsServer) return;
    Health.Value = Mathf.Max(0, Health.Value - amount);   // replicates to all clients
}

OnValueChanged

Clients don't poll the value — they subscribe to OnValueChanged, which fires with the previous and new value whenever it changes. Subscribe in OnNetworkSpawn and unsubscribe in OnNetworkDespawn (the Module 2 lesson on garbage-free code warned about leaked event subscriptions — the same discipline applies here):

public override void OnNetworkSpawn()
{
    Health.OnValueChanged += HandleHealthChanged;
    HandleHealthChanged(0, Health.Value);   // initialise UI to the current value
}

public override void OnNetworkDespawn()
{
    Health.OnValueChanged -= HandleHealthChanged;   // always unsubscribe
}

void HandleHealthChanged(int previous, int current)
{
    healthBar.fillAmount = current / 100f;
    if (current < previous) PlayHitFlash();
}

Because the callback carries both values, you can react to the delta — flash red when health drops, play a heal effect when it rises. This is the clean, event-driven way to keep visuals in step with networked state, on every machine including the host.

Supported Types

A NetworkVariable can hold value types that Netcode knows how to serialise: the numeric primitives, bool, Vector3/Quaternion/Color and other Unity structs, enums, and FixedString types (since managed string isn't allowed). For your own structs, implement INetworkSerializable so Netcode can pack them:

public struct PlayerStats : INetworkSerializable
{
    public int Kills;
    public FixedString32Bytes Name;   // not a managed string

    public void NetworkSerialize<T>(BufferSerializer<T> s) where T : IReaderWriter
    {
        s.SerializeValue(ref Kills);
        s.SerializeValue(ref Name);
    }
}
// then: public NetworkVariable<PlayerStats> Stats = new();

Keep NetworkVariables small and change them only when needed — every change is bandwidth. For a big, rarely-read blob, an RPC on demand (next lesson) is often better than a constantly-synced variable.

Syncing Transforms

You could put a position in a NetworkVariable and update it every frame, but movement is common enough that Netcode ships a component for it: NetworkTransform. Add it to a networked object and its position, rotation, and scale replicate automatically, with interpolation to smooth out network jitter.

By default NetworkTransform is server-authoritative — the server's transform is the truth and clients follow it (so a client moves its avatar by requesting movement via an RPC, and the server applies it). There's also a ClientNetworkTransform variant for owner-authoritative movement, used when low latency matters more than strict anti-cheat. For this course's authoritative model, server-authoritative NetworkTransform plus movement RPCs is the clean default — which sets up the next lesson perfectly.

NetworkVariable vs RPC

The two ways to move data are complementary, and choosing correctly keeps your netcode clean:

The tell: if a client joining mid-game needs to know it, it's state → NetworkVariable. If it's a fleeting notification that only matters at the moment, it's an event → RPC.

Hands-on Challenge

Summary

🚀 What's Next?

State flows server → clients. But how does a client ask the server to do something — fire, jump, pick up? And how does the server broadcast a one-off event? In Lesson 6.4: RPCs — Remote Procedure Calls we complete the picture with the universal [Rpc] attribute.