How to use custom versioning

Development Asset Creation
, , ,
1

The UE serialization system seems to have support for versioning of user classes, through things like FCustomVersionRegistration and FArchive::CustomVer(). However, these classes don’t seem to be used in UE4 itself (The apparently Epic-specific UE4Ver() is used instead), so it’s not really clear how to use them.

My assumption is that one creates a global FCustomVersionRegistration instance per class that may need to be versioned, constructed with a literal GUID, the current version of the class (consecutive integers from 1), and the name of the class. When the class changes in a way that the normal UPROPERTY versioning can’t handle, the developer increments the version number for that class. In the Serialize() method when loading, the developer checks GetVersion() on the FArchive (passing in the same GUID as was used to construct the FCustomVersionRegistration instance), and if it’s below the current version, executes code to update the object.

Are there bits I’m missing/mistaken about?

2

Paper2D seems to contain a usable example.

Your explanation sounds correct, except for where to perform the upgrade. In Paper2D, upgrade code is run in PostLoad, after querying the custom version:

void UPaperFlipbookComponent::PostLoad()
{
	Super::PostLoad();

	const int32 PaperVer = GetLinkerCustomVersion(FPaperCustomVersion::GUID);

	if (PaperVer < FPaperCustomVersion::ConvertPaperFlipbookComponentToBeMeshComponent)
	{
		if (Material_DEPRECATED != nullptr)
		{
			SetMaterial(0, Material_DEPRECATED);
		}
	}
}
3

Aha! interesting. It’s pretty weird that it doesn’t seem to be asking the archive at all about its custom version. I’ll need to look into this more, apparently.