Game client interest management

The GDK uses interest to control the information that game clients receive about the world around them.

Game clients need information about Actors that they don’t own (see the Unreal documentation on owning connections) to help them to correctly manipulate the Actors that they do own, and to render the SpatialOS world. Interest enables game clients to receive the relevant information.

You can define your game client’s interest in three ways, which you can use alongside each other:

  • NetCullDistanceSquared
    A property defined on an Actor's class. For any instance of an Actor of that class or a derived class, game clients whose players are within the distance specified receive updates about the Actor.
    • NetCullDistanceFrequency
      A feature you can use with NetCullDistanceSquared interest. For Actors within a ratio of the NetCullDistanceSquared distance to a game client’s player position, the game client receives updates at customized frequencies.
  • ActorInterestComponent
    An Unreal Actor component that you add to an Actor that a game client might own. This includes the game client's PlayerController, the Pawn that the PlayerController is possessing, and any Actor that the possessed Pawn owns.

    Within this component, you provide a list of queries that express the Actors that you want the game client to receive updates about. This is a more granular way of setting up interest than NetCullDistanceSquared.
  • AlwaysInterested
    A UPROPERTY that you add to an Actor that a game client might own. It refers to a specific Actor that you want the game client to always receive updates about.

All three ways of defining interest can coexist. However, if you've specified all the interest in your game with ActorInterestComponent and AlwaysInterested, you can turn off NetCullDistanceSquared using the toggle in ActorInterestComponent. NetCullDistanceFrequency enhances NetCullDistanceSquared interest and cannot exist alone.

NetCullDistanceSquared

NetCullDistanceSquared is a property on an Actor class that defines a distance. Game clients whose players are within this distance of an Actor of this class receive updates about the Actor. By default, this distance is 150 meters for all Actor classes.

To change an Actor class’s NetCullDistanceSquared value, open the Actor class's Blueprint and go to the Class Defaults tab. Net Cull Distance Squared is in the Replication section:

Image: Net Cull Distance Squared is in the Replication section of the Class Defaults tab

You need to convert your chosen number of meters into centimeters, square it, and then enter the resulting value. For example, to set a distance of 150 meters, you need to enter 225000000 (like in the screenshot above).

Example

In your game you have an Actor Blueprint called PlayerCharacter, which represents players within your game. If you set PlayerCharacter's NetCullDistanceSquared to 200 meters, then all game clients will receive updates about all PlayerCharacters that are within 200 meters of their own player.

If you also have an Actor Blueprint called Vehicle, and you set its NetCullDistanceSquared to 400 meters, then game clients will receive updates about all Vehicles within 400 meters of their player.

Image: A game client receives updates about Characters and vehicles that are close enough to its player, according to the Characters’ and vehicles’ NetCullDistanceSquared.

Note: In native Unreal, the NetCullDistanceSquared check works differently. Game clients whose player camera managers are within the specified distance receive updates about the Actor. See the Unreal Documentation for more information.

NetCullDistanceFrequency

By default, game clients receive updates at full frequency about all Actors that have NetCullDistanceSquared set up. Full frequency, measured in Hertz, means the SpatialOS Runtime doesn’t throttle any updates. This can cause significant and unnecessary bandwidth load and CPU overhead. For example, a game client might unnecessarily receive updates about an enemy that is 200m away from its player at the same frequency as an enemy that is two meters away.

In order to minimize bandwidth load and CPU overhead, the GDK for Unreal provides a NetCullDistanceFrequency setting that applies to all game clients in the game world. NetCullDistanceFrequency is an array of key-value pairs that define update frequencies and distance ratios with respect to an Actor's Net Cull Distance (NCD) value. For optimum performance, game clients should receive updates about Actors that are closer to their players at a higher frequency than Actors that are further away.

To enable NetCullDistanceFrequency, go to Settings > Project Settings > Runtime Settings > Interest and make sure the Enable Net Cull Distance Interest check box is selected. Then select the Enable Net Cull Distance Frequency check box.

Image: Enable Net Cull Distance Frequency is in the Interest section of the Runtime Settings.

Full Frequency Net Cull Distance Ratio is the ratio of an Actor's NCD in which the Actor updates at full frequency. For instance, if an Actor’s NCD value is 150 meters, and the ratio is set to 0.5, then if the Actor is within (150m * 0.5 = 75m) of a game client's player, the game client receives updates about the Actor at full frequency. The default value for Full Frequency Net Cull Distance Ratio is 1.0 which means that all Actors update at full frequency at all distances up to their NCD value. To start making use of NetCullDistanceFrequency, you must set the Full Frequency Net Cull Distance Ratio to less than 1.0.

Example

The following screenshot shows the setup for three NetCullDistanceFrequency values on three equally spaced concentric rings fanning out from a game client’s player position to the edge of any Actor’s NCD value.

Image: Set up Interest Range Frequency Pairs for all Actors in your game.

Setting the Full Frequency Net Cull Distance Ratio to 0.33 means that game clients receive updates at full frequency about any Actors positioned up to a third of their NCD from the game client’s player.

The two Interest Range Frequency Pairs create two more concentric rings, further away from the player, with lower update frequencies.

In the diagram below, you can see how this works in practice. The example has two Actors, each with a different NCD value. You can see that the Interest Range Frequency Pairs apply in the same way to each NCD value.

Note: the diagram is not to scale.

Image: A game client receives updates about Characters and Volcanoes that are close enough to its player, according to the Characters’ and Volcanoes’ NetCullDistanceFrequency settings.

Remember: frequency ratios remain the same for all Actor classes, because you define them for game clients. You set the NCD per Actor class.

ActorInterestComponent

ActorInterestComponent is an Unreal Actor component that you add to an Actor. It contains:

  • a list of queries
  • a toggle for NetCullDistanceSquared (on by default)

You can only add one ActorInterestComponent to an Actor.

When a game client owns an Actor with the component ActorInterestComponent, the interest queries within this component control the information that the game client receives.

Each query within an ActorInterestComponent can consist of:

  • a single constraint
  • multiple constraints that you combine using UOrConstraints and UAndConstraints

The following table lists the possible constraints.

Constraint Description
UOrConstraint Satisfied if any of its inner constraints are satisfied.
UAndConstraint Satisfied if all of its inner constraints are satisfied.
USphereConstraint Includes all Actors within a sphere centered on the specified point.
UCylinderConstraint Includes all Actors within a cylinder centered on the specified point.
UBoxConstraint Includes all Actors within a bounding box centered on the specified point.
URelativeSphereConstraint Includes all Actors within a sphere centered on the Actor that has ActorInterestComponent.
URelativeCylinderConstraint Includes all Actors within a cylinder centered on the Actor that has ActorInterestComponent.
URelativeBoxConstraint Includes all Actors within a bounding box centered on the Actor that has ActorInterestComponent.
UCheckoutRadiusConstraint Includes all Actors of a class or a derived class within a cylinder centered on the Actor that has ActorInterestComponent.
UActorClassConstraint Includes all Actors of a class. You can optionally include derived classes.
UComponentClassConstraint Includes all Actors with an Unreal Actor component of a specified class. You can optionally include derived classes.

For more information, see the interest constraints header file.

To attach this component to an Actor, open the Actor's Blueprint and, on the Components tab, select Add Component. Actor Interest is in the SpatialGDK section:

Image: Attach Actor Interest to an Actor

Example

Image: The Interest section of the details panel for ActorInterestComponent

In the screenshot above, ActorInterestComponent has two queries, so the game client receives updates about:

  • all Pawns within 200 meters of the Actor that has ActorInterestComponent
  • all Actors of the class Landmark or derived from the class Landmark

AlwaysInterested

You might want a game client to always receive updates about some specific Actors, regardless of the positions of the player and of these Actors. For example, you might want the game client to always receive updates about an important landmark, or about other members of the player’s team. You can use the AlwaysInterested UPROPERTY specifier for this.

An AlwaysInterested UPROPERTY must:

  • be an object reference (either an AActor or UObject)
  • have a Replicated or Handover specifier

You set up an AlwaysInterested UPROPERTY on a game client’s PlayerController, or on any other Actor that the game client might own, and then you specify the Actor that you want the game client to always receive updates about.

Example

For example, you might want a game client to always receive updates about a team base:

UPROPERTY(Replicated, AlwaysInterested) 
 AActor* TeamBase

If TeamBase is a valid Actor reference, then the game client receives updates about that Actor, regardless of TeamBase’s position in the game world.

Note: if the game client loses ownership of the Actor that you set up the AlwaysInterested UPROPERTY on, the UPROPERTY no longer applies.

For example, you set up an AlwaysInterested UPROPERTY on a weapon, with a reference to the TeamBase. The game client owns the weapon only while its Pawn is holding the weapon. When the Pawn puts the weapon down, the game client stops receiving updates about the TeamBase.


2020-07-29 NetCullDistanceFrequency section added with editorial review.
2019-07-31 Page added with editorial review.

Updated about a year ago


Game client interest management


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.