Net Relevancy Levels

Previously known as: Network Levels

Overview

Each replicated property on an AMorpheusActor belongs to one of three net relevancy levels (Foreground, Midground or Background) as defined by the user.

Seeing an AMorpheusActor at a specific net relevancy level means you can see all replicated properties belonging to that net relevancy level and below. For example, if a client is seeing an AMorpheusActor in the midground, it will see all the actor's background and midground properties. This means that every client will see all background properties for every AMorpheusActor in the world at all times.

Each client decides actors' net relevancy levels according to a prioritization algorithm. The net relevancy levels are filled in order, so that the highest priority actors are in the foreground, the next are in the midground, and the remainder are in the background. The number of actors allowed in foreground and midground is customisable: see Net Relevancy Levels.

By default, the algorithm prioritizes all actors based on their distance from the client's authoritative Morpheus pawn, but there are some exceptions. For these, see Forcing/prioritizing an entity into the foreground and Modifying the "client origin" for network prioritization.

You can specify the MinimumNetworkLevel of an AMorpheusActor type. The AMorpheusActor will be forced into at least this net relevancy level at all times.

Below is a breakdown of each net relevancy level, its behavior, limitations and examples.

Foreground

All foreground properties are replicated at 60Hz.

Foreground properties can use most types supported by standard Unreal replication: see Supported types.

Multicast RPCs are only received for actors in the foreground net relevancy level.

Depending on the game, each client will likely be able to see on the order of 50-100 actors in the foreground. Foreground properties cost much less bandwidth than midground & background ones. You should only move a property out of foreground if you definitely need it to be more widely visible.

Typical foreground properties include:

• The player's name.

• The player's current chat status.

• A list of the player's teammates.

The server sees every actor in the foreground net relevancy level, but only receives foreground property updates at 30Hz due to its limited tick rate to 30 FPS.

Midground

All midground properties are replicated at 30 Hz.

Background properties can only use a narrow set of types: see Supported types.

Multicast RPCs are not received for actors in the midground net relevancy level.

Depending on the game, each client will likely be able to see on the order of 500-1000 actors in the midground.

Typical midground properties include:

• A higher fidelity quantised position of the actor.

• The quantised rotation of the actor.

• The colour index of each player's hat.

Background

All background properties are replicated at 6 Hz.

Background properties can only use a narrow set of types: see Supported types.

Multicast RPCs are not received for actors in the background net relevancy level.

Because every client sees all background properties in the world, you have to be careful what you mark as a background property. Adding background properties which frequently change value can incur a large bandwidth cost to your game. Additionally, processing a large number of OnReps in a single tick in BP can impact client performance. You should only mark a property as being in the background if it is absolutely essential that it is visible on all clients.

Typical background properties include:

• A low fidelity quantised position of the actor.

• An index determining which player character the actor is.

• The current emote index of each player.

Net Relevancy Groups

Each Net Relevancy Group has its own net relevancy prioritization config and identified by a Group Id

Each AMorpheusActor can be assigned to only one Net Relevancy Group Id at a time.

The AMorpheusActor will be prioritized according to its current Net Relevancy Group config.

We currently have the following Net Relevancy Groups to choose from:

1. AlwaysForeground : All AMorpheusActors belonging to this group will always be in the Foreground net relevancy level regardless of their distance to the player.

2. ProximityBased : AMorpheusActors belonging to this group will be prioritized according to their distance to the player and respect the NumInForeground and NumInMidground configurations specified for that group.

3. CustomGroup : Intended for Advanced users. Explained further in Custom Net Relevancy Groups.

Assigning MorpheusActors to Net Relevancy Groups

You can assign AMorpheusActor to a net relevancy group from its Blueprint class details panel:

MorpheusActor Details Panel

You can also change the assigned Group Id for a AMorpheusActor during runtime via blueprints using this blueprint function:

NOTE: When selecting or configuring net relevancy groups for your Morpheus Actors, make sure to check against their Minimum Net Relevancy Level. If this level is too high, the net relevancy transitions will get blocked.

Customizing Net Relevancy Groups

Modifying the number in a given net relevancy level for a given group

The number of entities in a given net relevancy level can be modified in 2 ways:

Via Live Config:

• To modify the number of players in the foreground level, use PlayerClient.Networking.NumInForeground (in the game config)

• To modify the number of players in the midground, use PlayerClient.Networking.NumInMidground (in the game config)

• The remaining entities will be placed in the background.

• Note that this will only apply to the ProximityBased group Id.

NOTE: Updating the live config will apply to all users.

Via Blueprints

In the MorpheusClientConnection class there is the function SetConfigForNetRelevancyGroupId which can be used to change the number of actors in Foreground and in Midground for the Proximity Based net relevancy group during runtime.

NOTE: Calling this method will only apply locally. If you want to update the number for everyone, you will need to either call the method on all machines, or go via the live config approach.

Custom Net Relevancy Groups

NOTE: Only available in ODK v11 onwards

Like the ProximityBased net relevancy group, you can set the config for CustomGroup types. Each custom group is indicated by a CustomGroupName. By default, these will also use proximity based prioritization, but you can manually set the net relevancy of entities in the group using Overriding net relevancy priority

Custom groups are configured in your project settings: Project Settings -> Morpheus Platform -> Morpheus Net Relevancy:

Overriding net relevancy priority

NOTE: Only available in ODK v11 onwards

If you want to manually set the priority of your Morpheus Actors, e.g. wanting one to always be at the max network level wherever possible, or to implement your own system for prioritizing actors in Custom Net Relevancy Groups, you can do so.

SetNetRelevancyPriorityOverride lets you manually set the priority value for a target Morpheus Actor. This will trump the normal proximity priority calculations. 0 is the highest priority value, and increasing values will be prioritized lower - i.e. entities with lower values will be chosen in favour to be in the Foreground network level if possible.

This only applies to entities in the ProximityBased group, or a Custom group.

Forcing/prioritizing an entity into the foreground

If you want a particular entity to be preferred by the prioritization system regardless of position

This is used e.g. by our "presenters": if you have a VIP player in your game that you want everyone to see at the highest fidelity, you can set it to be prioritized.

There are two ways of achieving this:

• Via the SetIsForcedIntoForeground method on a morpheus actor:

  • (This will mean that the actor is prioritized on the local machine, and so will trump non-prioritized actors, regardless of position)

    

NOTE: The forced prioritization here does not override the cap of entities in the foreground level. If you have e.g. max 30 entities in your foreground, and have 50 prioritized, it won't put all 50 in your foreground. 30 is still the max.

NOTE: This is effectively the same as calling SetNetRelevancyPriorityOverride with value 0 (the highest priority)

Modifying the "client origin" for network prioritization

The client connection uses a "Client Origin Actor" to determine the client's centre for distance related priority calculations. By default this is the authoritative pawn that the client is controlling, but it can be modified.

E.g. if you want to make a "sniper" feature, where you focus in on a distant location, you would want the most high fidelity networked actors to be around your zoomed in location, not your actor's current position.

This client origin actor can be live-updated, by calling the PushClientOriginActor method, providing a new actor to use as the origin location. This makes the new actor trump the default as the origin for the prioritization logic. Once you are done, and want to go back to the default prioritization, call RemoveClientOriginActor, to stop considering your new actor, and return to using the previously set one.

(If you want the client origin to be at a fixed or relative location, the simplest approach would be to spawn an invisible actor, and use it as the Client Origin Actor).

Minimum Net Relevancy Level

As well as configuring the net relevancy group, and so configuring the eligible net relevancy levels that a Morpheus Actor can enter, we also configure the minimum, via the MinimumNetRelevancyLevel field.

This affects the checkout timing of the entity. If you have it set to Background, the entity will be created when it's in the Background level. At that time, any Midground or Foreground properties won't be set. If you are expecting them on MorpheusBeginPlay, bugs could ensue. If you know you only want your entities in a group to be at a particular network level or above, set the MinimumNetRelevancyLevel field, and they will only be checked out once they have all the properties at that level.