Actor Relevancy

Unreal Engine levels can be very large. At any time, a player might only see a small fraction of the total number of actors in a level. Most of the actors are not visible or audible, nor do they have a significant effect on the current player. The set of actors the server determines are capable of affecting a client in any significant way are considered relevant for this client. The set of relevant actors is determined on a per-client, or, in networking terms, a per-connection basis. Unreal Engine only replicates actors to a client if they are relevant for that client.

The following image comparison showcase a contrived example that uses distance-based relevancy. The primary actor (in the middle of the frame) is set to have replicated actors remain relevant if they are within 300 centimeters (3 meters). In the before image, the secondary actor is within 300 cm, and is relevant. This means that the secondary actor is replicated to the primary actor’s connection and is visible. In the after image, the secondary actor has traveled beyond 300 cm from the primary actor; therefore, the actor is no longer relevant to the primary actor, is not replicated to the primary actor’s connection, and is not visible.

Dynamically spawned, replicated actors are destroyed on the client when they are no longer relevant. This is why the secondary actor is no longer visible to the primary actor in this case.

Obtain an Actor’s Relevancy

The network driver determines whether an actor is relevant for a particular connection with a call to AActor::IsNetRelevantFor. This is handled automatically by the network driver.

Make an Actor Relevant

You can force any actor to be relevant by calling AActor::ForceNetRelevant in your AActor-derived class.

Override Actor Relevancy

You can customize actor relevancy by overriding the virtual function AActor::IsNetRelevantFor in your AActor-derived class.

Use caution when overriding AActor::IsNetRelevantFor. This may have unintended consequences if you are not familiar with Unreal Engine's replication system.

How Relevancy is Determined

The virtual function AActor::IsNetRelevantFor implements several tests to determine the set of actors that are relevant to a connection.

Parameters

AActor::IsNetRelevantFor uses three parameters to determine whether the calling actor object is relevant:

Relevancy Logic

For a given actor and connection, the following tests are performed:

• If at least one of the following conditions hold, then the current actor is relevant for this connection:
  • The current actor is always relevant.
  • The current actor is owned by the current connection’s Pawn.
  • The current actor is owned by the current connection’s Player Controller.
  • The current actor is the current connection’s Pawn.
  • The current connection’s Pawn is the instigator of some action, such as noise or damage.
• If the following conditions hold, then the replication system uses the current actor’s owner’s relevancy to determine whether it is relevant for this connection:
  • The current actor has an owner.
  • The current actor is set to use its owner’s net relevancy.
• If the following conditions hold, then the current actor is not relevant for this connection:
  • The current actor is only relevant to its owner.
  • The current actor does not have an owner.
  • The current actor’s owner is not relevant.
• If the following condition holds, then the system uses the current actor’s base relevancy to determine whether it is relevant for this connection:
  • The current actor is attached to the skeleton of another actor.
• If the following conditions hold, then the current actor is not relevant for this connection:
  • The current actor is hidden.
  • The current actor does not have a root component or the root component does not have collision enabled.

  If the current actor has no root component, then AActor::IsNetRelevantFor logs a warning and asks if the actor should be always relevant.

• If the following conditions hold, then the current actor is relevant for this connection:
  • The Game Network Manager (AGameNetworkManager) is set to use distance-based relevancy.
  • The current actor is within the relevancy distance.

This relevancy logic is for the base AActor class. Other AActor-derived classes may contain different network relevancy logic. For example, the APawn and APlayerController classes override AActor::IsNetRelevantFor. Therefore, they have different conditions for relevancy. See Pawn.cpp and PlayerController.cpp for more information.

Customize Relevancy Settings

You can customize network relevancy settings for your AActor-derived class in the Replication section of the Unreal Editor Details Panel or in C++.

Relevancy Reference

The following tables provide functions and properties pertaining to actor relevancy that can be found in the AActor class:

Functions

Properties