Interest Management

Overview

Interest Management is a set of data culling features, which restrict data replication of specific Network Objects and Network Behaviours from the Server to specific Player Clients. This culling is useful for reduction of network traffic, as well as restricting player access to data (such as team only information).

There are two main data culling mechanisms:

Object Interest: Restricts NetworkObject updates from Server to specific PlayerRefs.
Behaviour Interest: Restricts NetworkBehaviour updates from Server to specific PlayerRefs.

Object Interest

Object Interest is a per Network Object setting that indicates how Player interest in that Object should be determined. Players without interest in this Network Object will not receive any updates (Networked Properties as well as RPCs) for this Object from the Server peer.

There are three NetworkObject.ObjectInterest options:

Area Of Interest: Players with an AOI region which overlaps this Network Object's position in 2d/3d space will be interested in this object.
Global: All Players receive updates for this Network Object.
Explicit: Only Players explicitly flagged using SetPlayerAlwaysInterested() will be interested in this Network Object.

IInterestEnter / IInterestExit Callbacks

InterestEnter(PlayerRef player) and InterestExit(PlayerRef player) are called on registered components of a Network Object that implement the IInterestEnter and IInterestExit interfaces, whenever the Local Player gains or loses interest in that Object. Interest can be gained/lost by an Object entering/exiting one of a Player's Area Of Interest regions, or by the Server explicitly setting SetPlayerAlwaysInterested().

These callbacks are also triggered on the Server when in a Server/Client Mode (Dedicated Server/Host). This can be useful for selectively disabling aspects of a Network Object on the Server if it currently out of interest for all player (For example, an NPC may want to disable animations when no Player is interested).

This callback only triggers on clients for interest changes related to the Local Player. Non-Host Players are NOT aware of other Players interest in Objects.

IInterestEnter and IInterestExit implementations in a NetworkBehaviour will automatically be found by the Network Object, however any non NetworkBehaviour derived components with these interfaces need to be manually registered with the NetworkRunner.

IMPORTANT: IInterestEnter will NOT be called when the Object is Spawned on clients, as Player interest is implied by Spawned() happening. You may want to call your InterestEnter() specific handling in Spawned().

IMPORTANT: IInterestExit will NOT be called when the Object is Despawned on clients. You may want to call your InterestEnter() specific handling in Despawned().

Area Of Interest

When this Object Interest mode is selected on a NetworkObject, The Server Peer (including the Shared Mode Server when using Shared Mode)The Cloud will use each Client Player’s defined Area Of Interest (AOI) regions to determine if the Network Object is of interest to that player. Player AOI regions are specified by calling the Runner.AddPlayerAreaOfInterest() method.

IMPORTANT: The Replication Features field in the Network Project Config (NPC) must be set to Scheduling and Interest Management for Area Of Interest handling to be enabled.

Enable Interest Management in NetworkProjectConfig.

Clients may have multiple regions defined (for example if the player is operating a remote camera), except when using shared mode. If a Network Object is inside one or more of a Player’s AOI regions, that Player will be interested and will receive server updates for that NetworkObject from the server.

IMPORTANT: In shared mode, adding a new Area of Interest for a player with AddPlayerAreaOfInterest() will delete the previously active one. Shared mode supports only a single Area of Interest per player.

NetworkTRSP Requirement

The Area Of Interest system uses the position value of the NetworkTRSP class to determine an Object's position. For any Network Object to participate in the AOI handling, it must have a NetworkTRSP derived class on the same GameObject as the NetworkObject component.

More info on NetworkTRSP here.

These Fusion's components derive from NetworkTRSP and are AOI compatible:

NetworkTransform
NetworkRigidbody3D (Unity Physics Addon)
NetworkRigidbody2D (Unity Physics Addon)
NetworkCharacterControllerPrototype
The Advanced KCC Add-on

AddPlayerAreaOfInterest Usage

public class SetAreaOfInterest : NetworkBehaviour
{
  public float Extents = 32f;

  public override void FixedUpdateNetwork()
  {
    if (Runner.IsServer)
    {
      var controller = Object.InputAuthority;
      // Set the controlling players area of interest region around this object
      if (!controller.IsNone)
      {
        Runner.AddPlayerAreaOfInterest(controller, transform.position, Extents);
      }
    }
  }
}

NOTE: Object.SetPlayerAlwaysInterested() can be used in addition to AOI to force player interest in objects, even if they are outside of their AOI range.

AreaOfInterestOverride

See AreaOfInterestOverride in NetworkTransform.

AreaOfInterestOverride may be set on a Main NetworkTRSP to indicate that another Network Object's TRSP data should be used by the Server to determine Player interest in aNetworkObject'.

public void ChangeAOIOverride(NetworkObject proxyObject) 
{
  // Any NetworkTRSP derived component (such as NetworkTransform) 
  // on the root of an NetworkObject is referred to as the Main TRSP,
  // This main NetworkTRSP component is used to determine AOI for the NetworkObject.
  var mainTRSP = Object.GetComponent<NetworkTRSP>();
  
  // Setting AreaOfInterestOverride on the main NetworkTRSP tells Fusion to use the
  // Area Of Interest results of different NetworkObject to determine this Object's Interest.
  // Setting this to 'null' disables the override.
  Object.GetComponent<NetworkTRSP>().SetAreaOfInterestOverride(proxyObject);
}

Global

This NetworkObject is always of interest to all pPayers. This effectively disables Object culling for this Network Object, and all Players will receive Server updates for this NetworkObject.

Explicit

This Network Object is not of interest to any Player, UNLESS Player interest is specifically added with Runner.SetPlayerAlwaysInterested(). Only Players with explicit interest will receive Server updates for this Network Object.

public class MakeAlwaysInterested : NetworkBehaviour, IPlayerJoined
{
  void IPlayerJoined.PlayerJoined(PlayerRef player)
  {
    if (Runner.IsServer)
    {
      Object.SetPlayerAlwaysInterested(player, true);
      // or
      // Runner.SetPlayerAlwaysInterested(player, Object, true);
    }
  }
}

RPCs and Object Interest

Object Interest will also affect delivery of any non-static RPCs, as these are bound to an instance of a NetworkObject. The RpcInvokeInfo return value may be used on the server to detect and handle failures to send due to a Player not having interest in the NetworkObject instance the RPC is associated with.

[Rpc]
public RpcInvokeInfo RpcFoo()
{
  return default;
}

public override void FixedUpdateNetwork()
{
  if (Object.HasStateAuthority)
  {
    var info = RpcFoo();
    int culledCount = info.SendResult.CulledReceivers.Length;
    if (culledCount > 0)
    {
      //Handling for a target peer being culled from send
      Debug.LogWarning($"{culledCount} receivers culled, possibly due to no Object Interest.");
    }
  }
}

Behaviour Interest

The Server Peer in Server Modes (Dedicated/Host/Single Player) can limit replication of all Networked Properties (State) of a Network Behaviour to only specific Players.

The ReplicateTo(PlayerRef player) method can be overriden with a custom implementation to selectively return true or false for different players.

NOTE: This is only applicable to Server Mode and Host Mode (NOT Shared Mode). and ReplicateTo() is only valid on the Server peer, as the Server is the only State Authority in Server Mode.

NOTE: Object Interest is determined before Behaviour Interest. If a Network Object is out of a Player's interest, then no Network Behaviour on that Object will be getting replicated to that Player.

NOTE: Behaviour Interest only affects Networked Properties (Properties with the [Networked] attribute), and does not affect replication of Remote Procedure Calls (RPCs).

Usage

using Fusion;

public class InterestManagementSampleCode : NetworkBehaviour
{
  // Because this NetworkBehaviour is restricted to even players by the ReplicateTo() override
  // Only clients with an even LocalPlayer value will get updates for this value.
  // For odd-numvered players this value will remain zero.
  [Networked]
  int secretNumberOnlyEvenPlayersShouldKnow { get; set;}
  
  // NOTE: This method is only ever called on the Server in Server Mode
  // and is not applicable to Shared Mode
  protected override bool ReplicateTo(PlayerRef player) 
  {
      // Only replicate this behaviours state to Players with even numbered PlayerIDs
      return player.PlayerId % 2 == 0;
  }
}

Overview
Object Interest

IInterestEnter / IInterestExit Callbacks
Area Of Interest
Global
Explicit
RPCs and Object Interest

Behaviour Interest

Usage