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 afterPreInitializeComponents
has been called).This means that any
AMorpheusActorComponent
added to theMorpheusActor
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:
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.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:
OnChanged
(Default) : Call the OnRep function whenever the property changes regardless of relevancy.Default option and that's how native Unreal
OnReps
are fired.
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 theOnRep
.
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:
Morpheus actors
Morpheus actor components
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
andAMorpheusActorComponent
.If the
Network Level
option only showsForeground
, 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 theReplication
drop-down toRepNotify
.
Last updated