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:
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.
A feature you can use with
NetCullDistanceSquaredinterest. For Actors within a ratio of the
NetCullDistanceSquareddistance to a game client’s player position, the game client receives updates at customized frequencies.
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
UPROPERTYthat 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
AlwaysInterested, you can turn off
NetCullDistanceSquared using the toggle in
NetCullDistanceSquared interest and cannot exist alone.
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).
In your game you have an Actor Blueprint called
PlayerCharacter, which represents players within your game. If you set
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’
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.
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.
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.
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’
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 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
The following table lists the possible constraints.
||Satisfied if any of its inner constraints are satisfied.|
||Satisfied if all of its inner constraints are satisfied.|
||Includes all Actors within a sphere centered on the specified point.|
||Includes all Actors within a cylinder centered on the specified point.|
||Includes all Actors within a bounding box centered on the specified point.|
||Includes all Actors within a sphere centered on the Actor that has
||Includes all Actors within a cylinder centered on the Actor that has
||Includes all Actors within a bounding box centered on the Actor that has
||Includes all Actors of a class or a derived class within a cylinder centered on the Actor that has
||Includes all Actors of a class. You can optionally include derived classes.|
||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: The Interest section of the details panel for
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
- all Actors of the class
Landmarkor derived from the class
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
UPROPERTY specifier for this.
You set up an
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.
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
UPROPERTY on, the
UPROPERTY no longer applies.
For example, you set up an
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