This article describes a pattern to serialize prefabs or any complex data. Doing so allows us to store data to disk or send it over a network to either a game server or another game client. This article pairs well with the previous article on saving and loading data, so I recommend you read that one first if you haven’t already.<\/p>\n\n\n\n
We need a stable way to store and retrieve game objects using a simple reference. Doing so allows us to save the state of our world using a minimal amount of data. How? We store the data in a standard prefab or scriptable object in the project and reference it with an id, rather than keeping the entire structure in our saved state. Additionally, we can store any values that differ from the original, like health and position.<\/p>\n\n\n\n
At this point, you might be asking, “Hey, isn’t this what the Addressables package does?” There is some overlap; however, I’ve been using this pattern since before Addressables existed and continue to use it. Sometimes I even use both in the same project. Addressables is a more complex system focused on finding your assets no matter where they’re stored. This article describes a simple implementation of a pattern that you could execute in many ways, including using the Addressables system.<\/p>\n\n\n\n
We’ll create a registry to hold all the objects we need to serialize. In the simplest case, this is a Scriptable Object that contains a list of Descriptors, which is a type we’ll define. A Descriptor will also be a Scriptable Object that holds an id and references some data, such as a prefab. Then whenever we need to load a prefab from the Registry, we ask it to find the Descriptor with a given id and instantiate a new instance from the prefab reference.<\/p>\n\n\n\n
By the way, I used to use this pattern to create a homebrew version of nested prefabs and prefab variants. A Descriptor can contain as much data as we need, so it’s possible to reference a prefab and store a bunch of override data. Then when you instantiate the prefab, you immediately assign all the overridden data. As it turns out, this is precisely how nested prefabs work.<\/p>\n\n\n\n
We’ll start by defining a A Here’s the If you’re not familiar, the Editor calls When it comes to storing the GUID, there’s an easy way and a hard way. The easy way is to store a string that represents the GUID. That looks like this.<\/p>\n\n\n\n You could simplify it further by removing it altogether and just using a string field. Unfortunately, there are performance repercussions. Comparing two strings is relatively slow, and manipulating strings leads to memory allocations. That said, I’ve done it this way in production code, and it’s usually acceptable. If you want to do it the “right” way (just kidding, there is no right<\/strong> way, only the way that best suits your needs), then you need to store the GUID as four With this, we can convert from a string representation to four We could stop there, but wouldn’t it be nice to prevent users from modifying the GUID in the Inspector? We’ll do that and display the id as the original hex string simultaneously using a custom Property drawers are a mechanism to control how a given type displays in the Inspector. We’ll use it to display the GUID as a label rather than a list of editable numbers. Create a new file, The attribute The Here, we’re using Now that we’re ready to serialize some Scriptable Objects let’s build our Asset Registry.<\/p>\n\n\n\n Fortunately, the Registry type is relatively simple. It’s a Scriptable Object with a List of There’s not much else to say here, so let’s put it all into practice.<\/p>\n\n\n\n Everything beyond this point is project-specific, but I’ll demonstrate how everything connects with an example. Let’s say we have an As you can see, there’s very little code because the base classes contain all the complexity. Now you can create a Registry and Descriptors for each of your prefabs from the Assets > Create menu. By the way, adding the I used a simplified version of the So before I wrap up, I wanted to mention a few uses for this pattern. The most obvious, of course, is to save the state of the dynamic objects in your scene, as I showed in the example. In the past, I’ve also used this pattern to create a level editor tool. At their core, these two things are essentially the same. A level editor is a tool to spawn prefabs, manipulate them, and store them to disk.<\/p>\n\n\n\n Another less obvious use is to store ability loadouts to use in an RPG, for example. Scriptable objects can contain code as well as data. Let’s say we define a Now we can subclass this to create new abilities that contain all the necessary code and data. As a result, we can save a character’s ability loadout as a list of ids that link back to their corresponding Scriptable Object.<\/p>\n\n\n\n Ok, I’m almost done, but here’s one last tip before I go\u2014this one is for those of you who are using the Addressables system. It’s not apparent, but you can load addressable assets by their GUID as well as their address. It’s so unclear that I’m worried this functionality may disappear one day, but it works for now. What this means is if you’re using Addressables, you can forego the Ok, I’ve prattled on long enough; I’m outta here.<\/p>\n\n\n\n Explore the example project <\/strong>here on Github<\/strong><\/a>. If you like my work, <\/strong>join my mailing list<\/strong><\/a> to be notified when I write a new post.<\/strong><\/p>\n","protected":false},"excerpt":{"rendered":" This article describes a pattern to serialize prefabs or any complex data. Doing so allows us to store data to disk or send it over a network to either a game server or another game client. This article pairs well with the previous article on saving and loading data, so I recommend you read that […]<\/p>\n","protected":false},"author":1,"featured_media":516,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[28,1],"tags":[30,8,49,29,5],"class_list":["post-514","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-architecture","category-unity-programming","tag-architecture","tag-game-development","tag-persistent-data","tag-scriptable-objects","tag-unity"],"_links":{"self":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts\/514","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/comments?post=514"}],"version-history":[{"count":18,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts\/514\/revisions"}],"predecessor-version":[{"id":638,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts\/514\/revisions\/638"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/media\/516"}],"wp:attachment":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/media?parent=514"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/categories?post=514"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/tags?post=514"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}SerializableScriptableObject<\/code> type, the base class for our Descriptors.<\/p>\n\n\n\nSerializable Scriptable Object<\/h2>\n\n\n\n
SerializableScriptableObject<\/code> is a Scriptable Object that automatically saves its GUID. Speaking of, GUID stands for Global Unique Identifier. It’s also sometimes called a UUID for Universal Unique Identifier. The Unity Editor maintains an Asset Database that assigns a GUID to every asset in the project and uses it to reference assets in scenes, prefabs, etc. Usually, the Asset Database and corresponding GUIDs are only available in the Editor, but we will store those ids to make them always available. Incidentally, you may notice that the Asset Database and GUID system sounds similar to what we’re building, and you’re right. We’re essentially re-implementing this functionality at runtime.<\/p>\n\n\n\nSerializableScriptableObject<\/code> class.<\/p>\n\n\n\nusing UnityEngine;\n#if UNITY_EDITOR\nusing UnityEditor;\n#endif\n\npublic class SerializableScriptableObject : ScriptableObject\n{\n [SerializeField] Guid _guid;\n public Guid Guid => _guid;\n\n#if UNITY_EDITOR\n void OnValidate()\n {\n var path = AssetDatabase.GetAssetPath(this);\n _guid = new Guid(AssetDatabase.AssetPathToGUID(path));\n }\n#endif\n}<\/code><\/pre>\n\n\n\nOnValidate<\/code> whenever a value changes in the Inspector or when recompiles your scripts. So this is the perfect opportunity to save the GUID from the Asset Database. I’m sure you’re curious about the Guid<\/code> type, so let’s do that next.<\/p>\n\n\n\nGUID Type<\/h2>\n\n\n\n
[System.Serializable]\npublic struct Guid\n{\n public string guid;\n}<\/code><\/pre>\n\n\n\nuints<\/code>. That version looks like this.<\/p>\n\n\n\nusing System;\nusing System.IO;\nusing UnityEngine;\n\n[Serializable]\npublic struct Guid : IEquatable<Guid>\n{\n [SerializeField, HideInInspector] uint m_Value0;\n [SerializeField, HideInInspector] uint m_Value1;\n [SerializeField, HideInInspector] uint m_Value2;\n [SerializeField, HideInInspector] uint m_Value3;\n\n public uint Value0 => m_Value0;\n public uint Value1 => m_Value1;\n public uint Value2 => m_Value2;\n public uint Value3 => m_Value3;\n\n public Guid(uint val0, uint val1, uint val2, uint val3)\n {\n m_Value0 = val0;\n m_Value1 = val1;\n m_Value2 = val2;\n m_Value3 = val3;\n }\n\n public Guid(string hexString)\n {\n m_Value0 = 0U;\n m_Value1 = 0U;\n m_Value2 = 0U;\n m_Value3 = 0U;\n TryParse(hexString, out this);\n }\n\n public string ToHexString()\n {\n return $\"{m_Value0:X8}{m_Value1:X8}{m_Value2:X8}{m_Value3:X8}\";\n }\n\n static void TryParse(string hexString, out Guid guid)\n {\n guid.m_Value0 = Convert.ToUInt32(hexString.Substring(0, 8), 16);\n guid.m_Value1 = Convert.ToUInt32(hexString.Substring(8, 8), 16);\n guid.m_Value2 = Convert.ToUInt32(hexString.Substring(16, 8), 16);\n guid.m_Value3 = Convert.ToUInt32(hexString.Substring(24, 8), 16);\n }\n \n public static bool operator ==(Guid x, Guid y) => x.m_Value0 == y.m_Value0 && x.m_Value1 == y.m_Value1 && x.m_Value2 == y.m_Value2 && x.m_Value3 == y.m_Value3;\n public static bool operator !=(Guid x, Guid y) => !(x == y);\n public bool Equals(Guid other) => this == other;\n public override bool Equals(object obj) => obj != null && obj is Guid && Equals((Guid) obj);\n public override int GetHashCode() => (((int) m_Value0 * 397 ^ (int) m_Value1) * 397 ^ (int) m_Value2) * 397 ^ (int) m_Value3;\n}\n\n#region BinaryReader and BinaryWriter Extensions\npublic static class BinaryReaderExtensions\n{\n public static Guid ReadGuid(this BinaryReader reader)\n {\n return new Guid(reader.ReadUInt32(), reader.ReadUInt32(), reader.ReadUInt32(), reader.ReadUInt32());\n }\n}\n\npublic static class BinaryWriterExtensions\n{\n public static void Write(this BinaryWriter writer, Guid guid)\n {\n writer.Write(guid.Value0);\n writer.Write(guid.Value1);\n writer.Write(guid.Value2);\n writer.Write(guid.Value3);\n }\n}\n#endregion<\/code><\/pre>\n\n\n\nuints<\/code> and back. Converting back and forth is essential because the Asset Database API feeds us the id as a string. There are also extensions to BinaryReader and BinaryWriter to support serialization through those APIs. Using JSON serialization through JsonUtility<\/code> works by default because the uint<\/code> fields are serializable.<\/p>\n\n\n\nPropertyDrawer<\/code>.<\/p>\n\n\n\nGUID Property Drawer<\/h2>\n\n\n\n
GuidDrawer.cs<\/code>, inside any folder called Editor and add this code.<\/p>\n\n\n\nusing UnityEditor;\nusing UnityEngine;\n\n[CustomPropertyDrawer(typeof(Guid))]\npublic class GuidDrawer : PropertyDrawer\n{\n public override void OnGUI(Rect position, SerializedProperty property, GUIContent label)\n {\n EditorGUI.BeginProperty(position, label, property);\n\n var value0 = property.FindPropertyRelative(\"m_Value0\");\n var value1 = property.FindPropertyRelative(\"m_Value1\");\n var value2 = property.FindPropertyRelative(\"m_Value2\");\n var value3 = property.FindPropertyRelative(\"m_Value3\");\n\n position = EditorGUI.PrefixLabel(position, GUIUtility.GetControlID(FocusType.Passive), label);\n EditorGUI.SelectableLabel(position,\n $\"{(uint) value0.intValue:X8} \n {(uint) value1.intValue:X8} \n {(uint) value2.intValue:X8} \n {(uint) value3.intValue:X8}\");\n\n EditorGUI.EndProperty();\n }\n}<\/code><\/pre>\n\n\n\nCustomPropertyDrawer<\/code> specifies which property types to override. In our case, the type is Guid<\/code>. Then, override OnGUI<\/code>, and magically every time the Inspector encounters a Guid<\/code> it’ll run this OnGUI<\/code> method.<\/p>\n\n\n\nSerializedProperty<\/code> is a generic class that wraps the associated property, our Guid<\/code>. Working with Serialized Properties is a bit cumbersome, but that’s life. We usually use FindPropertyRelative<\/code> to find each field by its name, but we can make it a bit safer through the power of nameof<\/code>. With nameof<\/code> we can store the names of fields to constants, which means if the names get refactored, our code won’t break (thanks for the tip Aiden). Let me show you what I mean. Add these fields to the Guid<\/code> type.<\/p>\n\n\n\npublic struct Guid : IEquatable<Guid>\n{\n #if UNITY_EDITOR\n public const string VALUE0_FIELDNAME = nameof(m_Value0);\n public const string VALUE1_FIELDNAME = nameof(m_Value1);\n public const string VALUE2_FIELDNAME = nameof(m_Value2);\n public const string VALUE3_FIELDNAME = nameof(m_Value3);<\/strong>\n #endif\n. \n.\n.<\/code><\/pre>\n\n\n\nnameof<\/code> to store the name of the value fields in a string. Now modify the property drawer to use these strings instead.<\/p>\n\n\n\npublic override void OnGUI(Rect position, SerializedProperty property, GUIContent label)\n{\n EditorGUI.BeginProperty(position, label, property);\n var value0 = property.FindPropertyRelative(Guid.VALUE0_FIELDNAME<\/strong>);\n var value1 = property.FindPropertyRelative(Guid.VALUE1_FIELDNAME<\/strong>);\n var value2 = property.FindPropertyRelative(Guid.VALUE2_FIELDNAME<\/strong>);\n var value3 = property.FindPropertyRelative(Guid.VALUE3_FIELDNAME<\/strong>);\n.\n.\n.<\/code><\/pre>\n\n\n\nThe Registry Type<\/h2>\n\n\n\n
SerializableScriptableObjects<\/code>.<\/p>\n\n\n\nusing System.Collections.Generic;\nusing UnityEngine;\n\npublic abstract class Registry<T> : ScriptableObject where T : SerializableScriptableObject\n{\n [SerializeField] protected List<T> _descriptors = new List<T>();\n\n public T FindByGuid(Guid guid)\n {\n foreach (var desc in _descriptors)\n {\n if (desc.Guid == guid)\n {\n return desc;\n }\n }\n\n return null;\n }\n}<\/code><\/pre>\n\n\n\nPutting it together with Entities<\/h2>\n\n\n\n
Entity<\/code> component attached to all the dynamic objects in our game. To save and load entities, we need an EntityDescriptor<\/code> and an EntityRegistry<\/code>. The Descriptor has an id and references a prefab. The Registry holds a list of Descriptors. Here’s the associated code.<\/p>\n\n\n\n\/\/EntityRegistry.cs\nusing UnityEngine;\n\n[CreateAssetMenu]\npublic class EntityRegistry : Registry<EntityDescriptor>\n{\n}<\/code><\/pre>\n\n\n\n\/\/EntityDescriptor.cs\nusing UnityEngine;\n\n[CreateAssetMenu]\npublic class EntityDescriptor : SerializableScriptableObject\n{\n public Entity EntityPrefab;\n}<\/code><\/pre>\n\n\n\n\/\/Entity.cs\nusing UnityEngine;\n\npublic class Entity : MonoBehaviour\n{\n public EntityDescriptor Descriptor;\n}<\/code><\/pre>\n\n\n\nCreateAssetMenu<\/code> attribute to a ScriptableObject type automatically adds a menu item to create the stated object in the Create menu.<\/p>\n\n\n\nSaveManager<\/code> from the previous article to create a little test scene, which you can find in the GitHub repository linked at the end. This scene contains a bunch of entities spread around. On save, I grab all the entities in the scene and save their Guid<\/code> and position to a binary file on disk. Then on load, I read all the ids and positions from the file, look up each prefab in the Registry and instantiate the associated prefab at its saved position.<\/p>\n\n\n\nExciting Opportunities<\/h2>\n\n\n\n
SerializableScriptableObject<\/code> type to represent an ability like this:<\/p>\n\n\n\npublic abstract class Ability : SerializableScriptableObject\n{\n public abstract void Execute();\n}<\/code><\/pre>\n\n\n\nRegistry<\/code> entirely and use Addressables.LoadAssetAsync()<\/code> to load your assets. What’s more, since you’re loading by GUID instead of a string address, you can freely reorganize your project’s folder structure without your asset addresses going stale.<\/p>\n\n\n\n