NetworkVariable

The NetworkVariable class simplifies the synchronization of additional data within a NetworkBehaviour, allowing for seamless communication of data across a networked environment.

The SDK provides a NetworkVariable<T> class that supports unmanaged types, including common structures like Unity’s Vector and Quaternion types. This implementation covers most typical use cases. For handling more complex or custom data structures, please refer to the Extending section below.

To use NetworkVariable, declare an instance in your class as either public or with the SerializeField attribute. Once the client is connected, any updates to the Value property will be automatically synchronized across all users.

Additionally, the class provides an event, OnValueChanged, which is triggered whenever the value changes. You can subscribe to this event to react to value updates.

using ImmerseSDK.Multiplayer.Networking;
using ImmerseSDK.Multiplayer.Networking.Components;
using UnityEngine;

public class ExampleNetworkBehaviour : NetworkBehaviour
{
    [SerializeField] private NetworkVariable<int> _privateInteger;

    public NetworkVariable<Vector3> PublicVector3;
}

The NetworkVariable class offers several advanced options for more control.

You can control which users are allowed to modify and broadcast changes to the NetworkVariable object by setting the SendPermission property. The available permissions are:

public NetworkVariable<int> Example = new NetworkVariable<int>() { Permission = NetworkVariable.SendPermission.Owner };

Changing the Permission value at runtime will not automatically synchronize to all users.

Each NetworkVariable instance is automatically assigned a unique ID to identify it within the network. If you prefer to assign a custom ID, use the NetworkVariableFieldId attribute when declaring the NetworkVariable object, passing the desired field ID as a parameter.

[NetworkVariableFieldId(123)] public NetworkVariable<int> Example;

For scenarios that require more than a basic unmanaged type, you can extend the NetworkVariable class to handle any data type that can be serialized into a byte array. The example below demonstrates a simple implementation using a float value:

using System;
using ImmerseSDK.Multiplayer.Networking;

public class ExampleNetworkVariable : NetworkVariable
{
    /// <summary>
    /// Privately stored value. Do not alter externally to retain order of process
    /// </summary>
    private float _value;

    /// <summary>
    /// Public accessor to set and get the value
    /// </summary>
    public float Value
    {
        get => _value;
        set => SetValue(value);
    }

    /// <summary>
    /// Serializes the value before calling 'SendPayload' with the resulting byte array
    /// </summary>
    private void SetValue(float value)
    {
        var payload = BitConverter.GetBytes(value);
        SendPayload(payload);
    }
    
    /// <summary>
    /// Called when an update is received. Deserializes the payload and updates '_value'
    /// </summary>
    public override void ApplyPayload(byte[] payload)
    {
        var value = BitConverter.ToSingle(payload);
        _value = value;
    }
}