Storage And Replication - anticto/Mutable-Documentation GitHub Wiki

Overview

As explained in the Basic Concepts page, Customizable Object assets contain all the data to generate all possible combinations of an object. One single combination is represented by a CustomizableObjectInstance asset, which contains only a reference to a CustomizableObject and the values for each of the parameters it exposes.

There are 2 use cases for this data:

  • Persistent storage: for example to store in disk when an instance is created in the editor for a fixed NPC, or in-game, when a player customizes its character and the game wants to save it for another session.

  • Transient usage: for instance if you want to transmit it through the network from a client to the server or to other clients.

The requirements are slightly different on each case.

Persistent Storage

In this case, you need the instance parameters to be valid even if the CustomizableObject changes (it is extended, patched or updated) from session to session. For this reason you need this data to be as portable as possible.

If the CustomizableObject changes it may be one of the following:

  • A new parameter is added. In which case, not having it would set it to the default value in the CustomizableObject, which should be set to something reasonable.
  • A parameter is removed. No problem here, only some useless data to be removed.
  • A parameter changes name. The CustomizableObject parameters have a UID that can be used to be able to adapt data in this case.
  • The values of an enum parameter change. This is similar to a parameter change, since there are UIDs for each of the possible values that can be used to match the new object.

Most projects choose to implement their own data structures and storage to implement this description, and they feed it to CustomizableObjectInstances from game code, but for in-editor creation the CustomizableObjectInstance asset handles the parameters in this way.

Transient usage

In this case, you want the data to be as small as possible. If the CustomizableObject is not going to change, you can use the Compat Descriptor. This assumes that the number of parameters and their order is not going to change. Also, default parameters values will not be serialized.

This is important, because it allows the description to be more than 100x smaller in some cases. If you have 100 players and each of them may find each other, there are 10,000 potential transmissions happening, without even accounting for in-game changes of instances. If the description is 1KB instead of 100KB, you can save a lot on bandwidth each game.

void FCustomizableObjectInstanceDescriptor::SaveDescriptor(FArchive& Ar, bool bUseCompactDescriptor)