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 theNetworkBehaviour
index) - PlayerRef (serialized as
PlayerRef.PlayerId
)
- NetworkObject (serialized as
- 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 predefinedIFixedStorage
types, which are named_X
, where X is the size of storage struct_32
for example
- NetworkArray<T> with a maximum
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; }
}