Networked Properties

Overview

Networked Properties are properties of a NetworkBehaviour derived class that define the networked State of its associated Network Object.

To define a Networked Property, simply add the [Networked] attribute to an auto-property of a NetworkBehaviour derived class.This instructs Fusion to automatically generate IL code which connects that properties getter and setter to the State memory buffer of the associated Network Object.

DO NOT implement these properties yourself - leave them as auto-properties. If you need any special property handling of your own you will need to wrap them in another property.

C#

public class PlayerBehaviour : NetworkBehaviour
{
  [Networked] public float Health { get; set; }
}

Typically changes to these states should be made in FixedUpdateNetwork() as part of Simulation. This ensures they will behave correctly with client prediction, and changes will be tick accurate when replicated.

NOTE: In Shared Mode there are cases where modifying Network Properties in other timing segments may be viable, such as Update() or FixedUpdate().

C#

public override void FixedUpdateNetwork()
{
    Health += Runner.DeltaTime * HealthRegen;
}

Allowed Types

The following types are supported by Fusion and can be [Networked]:

• Primitives
  • byte, sbyte
  • short, int, long
  • ushort, uint, ulong
  • float, double
  • bool (converted to int)
• Strings with a maximum Length set using the [Capacity] attribute (defaults to 16)
• Unity struct types (defined in ILWeaver.cs)
  • Vector2, Vector3, Vector4
  • Quaternion
  • Matrix4x4
  • Vector2Int, Vector3Int
  • BoundingSphere
  • Bounds
  • Rect
  • BoundsInt
  • RectInt
  • Color, Color32
• Enums
• System.Guid
• User Defined INetworkStructs
• Fusion Defined INetworkStructs
  • NetworkString<>
  • IFixedStorage<>
  • NetworkBool
  • Ptr
  • Angle
  • BitSet64, BitSet128, BitSet192, BitSet256
  • PlayerRefSet
  • NetworkId
  • NetworkButtons
  • NetworkRNG
  • NetworkObjectGuid
  • NetworkPrefabRef
  • NetworkObjectHeader
  • NetworkPrefabId
  • SceneRef
  • TickTimer
  • IFixedStorage (_2, _4, _8, _16, _32, _64, _128, _256, _512)
• Fusion Types
  • NetworkObject (serialized as NetworkId)
  • NetworkBehaviour (serialized as NetworkId and the NetworkBehaviour index)
  • PlayerRef (serialized as PlayerRef.PlayerId)
• Network Collections
  • NetworkArray<T> with a maximum Length set using the [Capacity] attribute (defaults to 1)
  • NetworkDictionary<K, V> with a maximum Count set using the [Capacity]
  • NetworkLinkedList<T> with a maximum Count set using the [Capacity] attribute.
  • NetworkString<_size> with a maximum Size set using the any of the predefined IFixedStorage types, which are named _X, where X is the size of storage struct _32 for example

Networking Fusion Object Types

NetworkObject and NetworkBehaviour references can be Networked Properties of a NetworkBehaviour. (Note: References are not valid in INetworkStruct).

Internally, these Networked NetworkObject and NetworkBehaviour references are converted to NetworkId and NetworkBehaviourId values.

See Networking Fusion Object Types

Setting Default Values

It is possible to set default values for [Networked] properties.

Common types

For most common types a simple assignment is sufficient.

C#

public class PlayerBehaviour : NetworkBehaviour
{
  [Networked] public float Health { get; set; } = 100;
  [Networked] public NetworkObject DefaultNetworkObject { get; set; } = GameObject.FindGameObjectWithTag("Foo").GetComponent<NetworkObject>();
}

Collections

Network Collections such as NetworkArray<T> , NetworkDictionary<K, V> , NetworkLinkedList<T> and NetworkString<_size> require a special syntax. Please refer to the page of the same name for more information.

Capacity

The [Capacity] attribute is used to define the maximum size of NetworkArray, NetworkDictionary, NetworkLinkedList, NetworkString and strings.

C#

public class MyNetworkBehaviour : NetworkBehaviour
{
  [Networked, Capacity(14)]
  string MyString { get; set; }

  [Networked, Capacity(8)]
  NetworkArray<byte> MyArray { get; }
}

Ref and Ptr

It is possible to set default values for references and pointers by using the appropriate constructors.

C#

[Networked] public ref Byte Prop => ref MakeRef<Byte>(123);
[Networked] public Byte* Prop => MakePtr<Byte>(123);

Change Detection

See Change Detection

Advanced Bool Handling

In game networking, it is often recommended to use an int instead of bool for use cases where a change of the value might go undetected (for example the bool flipped to true and then back to false before serialization, or the toggle was lost due to culling, data loss, shared mode squashing, player joining late etc).

One strategy for this is to use an int sign value to encode the bool state, and use the absolute value to store additional information such as how many times the value has changed, or when the value was last changed.

C#

public class MyNetworkBehaviour : NetworkBehaviour
{
  // This is the backing value for our virtual bool.
  [Networked] int _intToggle { get; set; }
  
    
  // This property will automatically encode the change count into the backing value,
  // while still acting like a normal bool.
  private bool CountToggle 
  {
    // This assumes 0 to mean false, <= can be used to make 0 indicate true.
    get => _intToggle > 0;
    // Every call to set increments the absolute value
    // and sets the sign to negative for false, positive for true.
    set =>
      _intToggle = _intToggle >= 0 ? 
        value ?   _intToggle + 1 : -(_intToggle + 1) :
        value ? -(_intToggle - 1):   _intToggle - 1;
  }

  private int toggleCount => _intToggle >= 0 ? _intToggle : -_intToggle;
}

C#

public class MyNetworkBehaviour : NetworkBehaviour
{
  // This is the backing value for our virtual bool.
  [Networked] int _intToggle { get; set; }

  // This property will automatically encode the current tick into the backing value,
  // while still acting like a normal bool.
  private bool TickToggle 
  {
    get => _intToggle > 0;
    set => _intToggle = value ? Runner.Tick : -Runner.Tick;
  }

  private Tick toggleLastChangedTick => _intToggle >= 0 ? _intToggle : -_intToggle;

}

Interpolation

See Snapshots and Interpolation

Generics

It is possible to create templated classes deriving from NetworkBehaviour. These can even contain [Networked] properties.

C#

// This is VALID
class ValidGenericClass_With_NonGenericProperty<T> : NetworkBehaviour {
    [Networked] public int Prop { get; set; }
}

However, it is NOT possible to have a generic [Networked] property of type <T>.

C#

// This is INVALID
class InValidGenericClass_With_GenericProperty<T> : NetworkBehaviour {
    [Networked] public T Prop { get; set; }
}

Back to top