Networking Fusion Object Types

Overview

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

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

The ILWeaver generated Set method converts (wraps) the reference to its Id, and that Id is what is networked.

The ILWeaver generated Get method converts (unwraps) the Id to a reference using the Runner.TryGetObject() and Runner.TryGetBehaviour() methods.

C#

[Networked] public NetworkObject MyNetworkObject { get; set; }
[Networked] public CustomNetworkBehaviour MyNetworkBehaviour { get; set; }

While convenient, this automation does mean that:

• an explicit null value, and;
• a failure to unwrap

will both return a null value for Get - with no distinction between the two.

An alternative to using NetworkObject and NetworkBehaviour for properties, is to instead use NetworkId and NetworkBehaviourId values.

Explicitly syncing these references by Id, you can detect if a null value:

• indicates an explicit null (0), or;
• indicates an object (a value > 0), but that Object just does not exist locally currently (failed to unwrap).

NetworkId Usage Example

C#

using Fusion;

public class SyncNetworkObjectExample : NetworkBehaviour
{
  // NetworkId is backed by one int value.
  // A zero value (default) represents null.
  [Networked] public NetworkId SyncedNetworkObjectId { get; set; }

  private void SetObject(NetworkObject netObj)
  {
    SyncedNetworkObjectId = netObj != null ? netObj.Id : default;
  }

  bool TryResolve(out NetworkObject no)
  {
    // A default (0) value indicates an explicit null value.
    // Return true to represent successfully resolving this to null.
    if (SyncedNetworkObjectId == default)
    {
      no = null;
      return true;
    }

    // Find the object using the non-null id value.
    // Return true if the lookup was successful.
    // Return false and null if the NetworkObject could not be found on the local Runner.
    bool found = Runner.TryFindObject(SyncedNetworkObjectId, out var obj);
    no = obj;
    return found;
  }
}

NetworkBehaviourId Usage Example

C#

using Fusion;

public class SyncNetworkBehaviourExample : NetworkBehaviour
{
  // NetworkId is backed by two int values.
  // Object = NetworkObject.Id (value of 0 represents null/Invalid).
  // Behaviour = NetworkBehaviour index in GameObject hierarchy.
  [Networked] public NetworkBehaviourId SyncedNetworkBehaviourId { get; set; }

  private void SetBehaviour(NetworkBehaviour nb)
  {
    SyncedNetworkBehaviourId = nb != null ? nb.Id : default;
  }

  bool TryResolve(out NetworkBehaviour no)
  {
    // A default (0) value indicates an explicit null value.
    // Return true to represent successfully resolving this to null.
    if (SyncedNetworkBehaviourId == default)
    {
      no = null;
      return true;
    }

    // Find the NetworkBehaviour using the non-default id value.
    // Return true if the lookup was successful.
    // Return false and null if the NetworkObject could not be found on the local Runner.
    bool found = Runner.TryFindBehaviour(SyncedNetworkBehaviourId, out var obj);
    no = obj;
    return found;
  }
}