NetworkBehaviour and NetworkVariable

Add one NetworkIdentity to the root GameObject of each networked entity. Add one or more NetworkBehaviour components to the root or its children.

Use IsServer, IsClient, and IsOwner to inspect the process and client owner. Use HasAuthority to check whether the current worker controls the entity. Use IsGhost to check whether the worker holds a non-authoritative copy.

This page covers identities, behavior components, lifecycle methods, and replicated fields. See RPCs and worker messages for remote calls. See Prediction and reconciliation for predicted movement.

NetworkIdentity

Add NetworkIdentity to mark a GameObject as a networked entity. Put one identity on the root. Nebula associates each NetworkBehaviour on the root and its children with that identity.

Behaviours contains the NetworkBehaviour components in GetComponentsInChildren order. Nebula uses each component's position in this array as its network index. Use the same prefab and component order in every process.

An identity synchronizes initial placement and container changes. Add NetworkTransform for ongoing movement and NetworkRigidbody for worker-simulated physics. Use Identity.Motion.Velocity for the velocity reported by the authority.

NetworkIdentity also records a per-tick state history on workers for lag-compensated hit tests (StateAt). See Lag compensation.

NetworkBehaviour

Derive a component from NetworkBehaviour when it must inspect its role, replicate fields, or send RPCs. Add NetworkIdentity to the same GameObject or a parent.

public sealed class PlayerController : PredictedBehaviour<PlayerInput>
{
    public NetworkVariable<string> PlayerName = new NetworkVariable<string>("");
    public NetworkVariable<float> Health = new NetworkVariable<float>(MaxHealth);
    public NetworkVariable<bool> IsDead = new NetworkVariable<bool>(false);

    public override void OnNetworkSpawn()
    {
        _inputYaw = transform.eulerAngles.y;
    }
}

Role flags

A process is either a worker (server) or a client, never both. The flags on a behavior combine the process role with the identity's state:

What each process sees for one entity:

Check IsOwner only for client ownership. On a worker, check HasAuthority and read OwnerClientId. A server-driven entity has OwnerClientId == 0 and no owning client.

Convenience accessors on the behavior forward to the identity: NetId, IsSpawned, OwnerClientId, Container and Identity itself.

Lifecycle hooks

All hooks are virtual with empty defaults.

Expect this order on the worker that spawns an entity:

1. OnContainerChanged(null, spawnContainer)
2. OnNetworkSpawn
3. OnGainedAuthority
4. NetworkTick on each tick

During a cross-worker handover, the previous worker calls OnContainerChanged, WriteHandoverState, and OnLostAuthority. The new worker calls OnContainerChanged, ReadHandoverState, and OnGainedAuthority, then begins calling NetworkTick. When the authoritative worker despawns the entity, each process calls OnNetworkDespawn before removing its copy.

Two more pairs of hooks exist for state that is not a NetworkVariable: WriteHandoverState / ReadHandoverState for state only the next simulating worker needs, and WriteSyncState / ReadSyncState for per-tick delta channels. Both are described in /docs/guides/physics-and-handover-state.

Ghost semantics

A ghost is a non-authoritative copy of an entity on another worker. Nebula creates one near a container boundary so the next worker has the entity's state before a handover. On a ghost:

• HasAuthority is false and IsGhost is true.
• NetworkTick is not called. The pose is driven by the neighbor's GhostState stream through an interpolator, one tick behind the simulation tick; any Rigidbody is set kinematic.
• NetworkVariable values arrive through GhostVars and raise OnValueChanged; writes are refused.
• The ghost's colliders are real, so raycasts and overlaps on the authoritative worker hit it. That is how a hitscan resolves against a victim simulated elsewhere.
• RemoteTick(double renderTick) is called once per tick before physics syncs, so interpolating behaviors can present their buffers.

OnNetworkSpawn runs on a ghost exactly as it does everywhere else, so gate authority-only setup on HasAuthority or put it in OnGainedAuthority. A ghost may later become authoritative (handover in) and an authoritative entity may become a ghost (handover out) any number of times without being respawned.

NetworkVariable<T>

NetworkVariable<T> is a replicated field. Declare it as a field on a NetworkBehaviour, optionally with an initial value, and Nebula discovers it.

public NetworkVariable<float> Health = new NetworkVariable<float>(100f);
public NetworkVariable<int> Kills;   // null fields are created for you with default(T)

Writing and reading

Only the authoritative worker may assign Value. Assignments from a client or a ghost are logged as a warning and ignored:

NetworkVariable on PlayerController written without authority (netId 281474976710657); ignored

The check applies once the entity is spawned. Before that (in a constructor or Awake, or on a prefab you are configuring before Spawn) any process may set the initial value.

Assigning the current value makes no change. Assigning a different value marks the entity's variables as dirty and immediately raises OnValueChanged(previous, current) on the authoritative worker.

At the end of the tick, the worker sends all variables for that entity to the gateway and each worker that holds a ghost. Receiving copies apply the values and raise OnValueChanged for values that differ. A spawn or authority-transfer message also includes the current values.

[AuthorityRpc]
private void TakeDamage(float amount)
{
    if (!HasAuthority || IsDead.Value) return;
    Health.Value = Mathf.Max(0f, Health.Value - amount);
    if (Health.Value <= 0f) IsDead.Value = true;
}

Subscribe to OnValueChanged on any copy for presentation (a health bar on other clients, a tint on a ghost):

Health.OnValueChanged += (previous, current) => _bar.fillAmount = current / MaxHealth;

NetworkVariable<T> converts implicitly to T, so float hp = Health; works. Assignment still goes through Value.

Discovery

When an identity starts, Nebula finds every public or private field whose type derives from NetworkVariableBase. It checks the concrete behavior class and each base class up to NetworkBehaviour.

Nebula assigns each field a numeric index based on declaration order. It also creates an instance for a field that is null. Follow these rules to keep the indices consistent:

• Declare variables as fields, not properties.
• Keep the same class and the same field order on every process (the same assembly on client and worker guarantees this).
• Adding or removing a variable changes every index after it. Network messages do not include the field name.

Supported value types

T must be something NetworkSerialization knows: the primitives, string, Vector2, Vector3, Quaternion, Color, byte[], any enum, anything implementing INetworkSerializable, or a type registered with NetworkSerialization.Register<T>. The exact list and how to extend it are in /docs/guides/serialization.

Equality uses EqualityComparer<T>.Default, so a struct T needs a sensible Equals (or IEquatable<T>) for the no-op check and OnValueChanged filtering to work; without one, every assignment counts as a change.

What travels on the wire

Nebula does not send a per-variable delta. When any NetworkVariable on an entity changes, it sends every variable on that entity in discovery order. Receivers still raise OnValueChanged only for values that differ.

For a collection that changes a few entries at a time, such as an inventory, use a NetworkMap: it sends only the entries that change, and it is not part of the variable block.

Every client that holds the entity receives its variables. For state only some clients may see, such as a player's inventory, use the sync channel with a sync audience instead.

Use NetworkVariable for state that changes occasionally, such as health, a display name, or a target. Put per-tick values in a NetworkTransform, predicted state, or a custom sync component.

Related