Replicated Properties

In Morpheus as in Unreal, the basic unit of replication is the property. Properties are marked for replication the same way as in Unreal, but Morpheus can only replicate properties belonging to classes based on AMorpheusActor and AMorpheusActorComponent.

This page will detail the concepts introduced with replicated Morpheus properties, before demonstrating how to implement them in the How to define properties section below.

Replication semantics

The following semantics apply for all properties in any network level:

  • Replicated properties are registered once the MorpheusActor has spawned at the Server (specifically after PreInitializeComponents has been called).

    • This means that any AMorpheusActorComponent added to the MorpheusActor afterwards will not be registered and hence its properties will NOT be replicated.

  • Other than that, property replication in Morpheus follows Unreal semantics:

Property replication is reliable. This means that the property of the client version of the Actor will eventually reflect the value on the authority, but the client will not necessarily receive notification of every individual change that happens to a property at the authority. For example, if an integer property rapidly changes its value from 100 to 200, and then to 300, the client will eventually receive an update with the value of 300, but there is no guarantee that the client will know about the change to 200.

Features

Network Relevancy level

In Morpheus, every replicated property belongs to one of three network levels (Foreground, Midground or Background). See Network Levels for details.

Client authority

In standard Unreal networking, only the server can update replicated properties. If a client wants to change a replicated property, it must send an RPC to the server instructing it to do so.

In Morpheus, however, you can define client authoritative properties. This means that the client which is authoritative over the entity can directly change the replicated property, and the new value will be sent to the server and other clients.

This allows you to avoid the server becoming the bottleneck for certain systems where it is appropriate. Properties belonging to any network level can be marked as client authoritative.

The server still receives a 4Hz view of all client authoritative properties, which it can use to validate that the client is behaving appropriately. It would be up to the user to perform validation of client authoritative properties on the server, and one potential response to a client behaving inappropriately is kicking the client.

NOTE: For Client Authoritative properties to work, the actor must be spawned with Client Authority. For information on how to do this, see Spawning. NOTE: Once a property is defined as client authoritative, the server no longer has authority over the property and modifications made by the server will not be replicated.

RepNotify

Morpheus supports RepNotify functions with the same behaviour as native Unreal. That is, when a property update is received and if the received value is different to the local value, then the RepNotify function will be called. If the received value is equal to the local value, then the function is not called.

Note that RepNotify execution is ordered across sub-objects; an Actor's RepNotify function will always be executed before those of its components.

Owner Only

You can mark a foreground server-authoritative property as Owner only, which means it will only be replicated to the authoritative client.

Authority Only

You can mark a UMorpheusActorComponent with the AuthorityOnly meta tag, which means this component will be only available at the authoritative client. Other non-authoritative clients will just destroy this AuthorityOnly component. However, this won't prevent the component properties from being replicated to the non-authoritative clients by default and hence you would need to also add OwnerOnly tag to the server-authoritative properties of that component to save networking replication costs.

Update Fast in Midground

You can mark a background property as Update Fast in Midground. This is a performance trade-off. Normally, a background property will be updated at 2Hz, regardless of whether the property's owning actor is in background, midground or foreground. If you enable this feature, then when the property's actor is in midground or foreground, the client will receive updates at 10Hz (the same rate as for a midground or foreground property).

In other words, you get the best of both worlds: the property is available for every actor in the scene, yet is highly responsive for higher-priority actors. The downside is increased server load: it's equivalent to adding another midground property to your actor.

Value on Relevancy Lost

A replicated property can lose relevancy when its owner MorpheusActor moves to a lower Network Relevancy Level. E.g. A MorpheusActor moves from Foreground to Midground while it has a replicated property that's defined with a Foreground Network Relevancy Level will cause that property to become irrelevant. When this happens, you can specify which value this property will take. The available options are:

  1. Last Value Received (Default): When actor's relevancy level drops below this property's level and the property stops receiving updates, leave its value unchanged.

  2. Default Value: When actor's relevancy level drops below this property's level and the property stops receiving updates, reset it to its default value.

RepNotify Condition

In Morpheus, you can control when should the OnRep of a property be fired. The available options are:

  1. OnChanged (Default) : Call the OnRep function whenever the property changes regardless of relevancy.

    • Default option and that's how native Unreal OnReps are fired.

  2. OnChangedWhileRelevant: Call the OnRep function when the property changes, but only while the property is relevant. Network Relevancy changes will not trigger the OnRep function.

    • A use case for this new option is when you only want the OnRep to only be triggered for live updates to your property. Initial values and value changes that occured while the property wasn't relevant will not trigger the OnRep.

  3. Always: Call the OnRep function whenever the value is received from the network or updated on relevancy lost. Reagardless of whether the value has changed. (Only available in Foreground)

    • A use case for this is if the property represents an action that the actor has done and you want to call the OnRep each time that action has been performed regardless if it's the same action.

OnReps would also be triggered as a result of the Default Value option in Value on Relevancy Lost depending on the RepNotify Condition

Supported types

Foreground

Foreground properties can use the same types as standard Unreal networking, with one exception. Object references must be references to:

Midground and background

Midground and background properties are more limited. They can only use the following types:

  • Bools

  • Integers

  • References to Morpheus actors and Morpheus actor components

  • Structs comprising any of the above

    • They can be nested

  • Floats & doubles

Floats and doubles are a special case: Morpheus compresses them lossily on replication. You need to specify your required level of precision in the property's Details panel. (For instance, a property with a Precision When Replicated of 0.01 will only replicate to an accuracy of two decimal places.) This requirement means that non-foreground structs can't contain floats or doubles.

Morpheus compression works best when your properties' deltas are between 0 - 255 hence it's recommended to quantize your values such they occupy that range if possible specially if these properties are expected to change frequently and you don't care about precision.

How to define properties

Properties are marked for replication through the Details panel in the Blueprint Editor. This is also how you turn on all of the above features.

By default, properties aren't replicated. Mark them for replication using the Replication dropdown. The default replicated property is foreground and server authoritative.

Note that:

  • Morpheus replication settings are only available within classes based on AMorpheusActor and AMorpheusActorComponent.

  • If the Network Level option only shows Foreground, the property you are attempting to replicate is only compatible with the Foreground network level (see Supported types above).

  • Create a RepNotify function for a property by setting the Replication drop-down to RepNotify.

Last updated