Morpheus Array
This feature is currently in Beta.
Introduction
This document covers when and how to use a UMorpheusArray
in Blueprints and the current limitations it has.
Morpheus Array
A UMorpheusArray
is a generic replicated container that can be used to efficiently replicate array updates.
UMorpheusArray
is only replicated in Foreground and supports any type that a replicated TArray supports.
When to use a Morpheus Array vs normal Arrays?
A Morpheus Array
is preferred to be used when:
You expect your array to contain 1000s of elements with frequent changes.
You need to know when a specific index has been updated in the array.
An example use case can be when you want to keep track of some data for each actor in the game and that data can change during runtime. (e.g Super Emotes)
Using a Morpheus Array in Blueprints
In order to start using a Morpheus Array
in Blueprints you do the following:
Open your Blueprint that derives from either a
MorpheusActor
or aMorpheusActorComponent
Add a variable to your Blueprint and give it the type
Morpheus Array
In the variable Details Panel on the right, select the
Morpheus Array Inner Type
to be your desired type of thatMorpheus Array
variable.
Don't forget to set the
Morpheus Array
variable to beReplicated
Now drag and drop the variable into the BP graph to start using your
Morpheus Array
using theMorpheus Array
specific nodes shown under theMorpheus Array
category.
Example Blueprint Usages
Since UMorpheusArray
is a replicated type it also supports rep notifies and they do fire even if a single element was updated.
But additionally UMorpheusArray
has a couple of helper functions that you can use in the OnRep to know the exact replication changes that we received.
UMorpheusArray::OnRepUpdatedIndices()
which returns an array of the indices that have been updated by the last replication event.UMorpheusArray::OnRepDeletedIndices()
which returns an array of the indices that have been deleted by the last replication event.
With these functions, users can be aware of the changes that happened to the array, rather than having to figure out any changes manually
Example usage:
On About to Apply Update Delegate
Morpheus Arrays has a delegate OnAboutToApplyUpdate
that is fired before the OnRep
. This delegate can be used to react to incoming element updates/deletions before they are applied to the Morpheus Array
itself and losing the old values.
See example below:
Notice that the delegate gets called with Keys
instead of Indices
so you will need to use GetIndexFromKey
to retrieve the about to be updated/deleted index in the Morpheus Array.
There is also another helper function GetKeyOfIndex
that retrieves the Key of a given index.
Keys vs Indices
A Key
in a Morpheus Array is a unique identifier for a Morpheus Array element.
Since elements in the Morpheus Array can get added or removed the Index
becomes insufficient to represent the element as it could now be pointing to a different element.
Every Key
is mapped to an Index
in the array and whenever an Index
is removed, its Key
will also get removed but the remaining keys will still point to the same elements despite having their indices changed.
An update to an element doesn't affect the Key
nor the Index
of that element.
Limitations
AMorpheusActors
that own aUMorpheusArray
and aren’t in Foreground will still need to checkout the whole array once they enter Foreground. In which case, aUMorpheusArray
will not be replicated efficiently.Using the
Get
node and theToArray
nodes in Blueprints will currently return copies of the values inside theUMorpheusArray
so bear in that in mind if performance is a concern.Debugging a
UMorpheusArray
may not be trivial as the data is stored internally as a raw byte buffer so you might need to write extra code to view the contents of theUMorpheusArray
while debugging it.
Last updated