# Replicated Properties

In Morpheus as in Unreal, the basic unit of replication is the [property](https://docs.unrealengine.com/5.3/en-US/unreal-engine-uproperties/). 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](#how-to-define-properties) section below.

### Replication semantics <a href="#morpheusactorproperties-propertyreplicationsemantics" id="morpheusactorproperties-propertyreplicationsemantics"></a>

The following semantics apply for **all** properties in **any** [network level](https://docs.msquared.io/creation/unreal-development/getting-started/networking/network-levels):

* 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:](https://dev.epicgames.com/documentation/en-us/unreal-engine/property-replication-in-unreal-engine?application_version=5.4)

> 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 <a href="#morpheusactorproperties-clientauthority" id="morpheusactorproperties-clientauthority"></a>

In Morpheus, every replicated property belongs to one of three network levels (Foreground, Midground or Background). See [Network Levels](https://docs.msquared.io/creation/unreal-development/getting-started/networking/network-levels) for details.

#### Client authority <a href="#morpheusactorproperties-clientauthority" id="morpheusactorproperties-clientauthority"></a>

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](https://docs.msquared.io/creation/unreal-development/getting-started/networking#networking-spawninganddestroying).\
**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 <a href="#morpheusactorproperties-repnotify" id="morpheusactorproperties-repnotify"></a>

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 <a href="#morpheusactorproperties-owneronly" id="morpheusactorproperties-owneronly"></a>

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

#### Authority Only <a href="#morpheusactorproperties-owneronly" id="morpheusactorproperties-owneronly"></a>

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.

{% hint style="info" %}
`OnReps` would also be triggered as a result of the `Default Value` option in `Value on Relevancy Lost` depending on the `RepNotify Condition`
{% endhint %}

### Supported types <a href="#morpheusactorproperties-propertymeta" id="morpheusactorproperties-propertymeta"></a>

#### 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
* [Stably named objects](https://dev.epicgames.com/documentation/en-us/unreal-engine/replicate-actor-properties-in-unreal-engine#stablynamedobjects)

#### 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.

{% hint style="info" %}
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.
{% endhint %}

### 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**.

<figure><img src="https://1456550285-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoWTlPaoHd1McSakqMigu%2Fuploads%2Fgit-blob-c068f9764044d211040f9ab09ac1e99c405bf224%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

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](#morpheusactorproperties-propertymeta) above).
* Create a `RepNotify` function for a property by setting the `Replication` drop-down to `RepNotify`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.msquared.io/creation/unreal-development/getting-started/networking/replicated-properties.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.