Unity Serializer API

OTHER RESOURCES

Getting Started Guide

How Unity Serializer Works

Core Classes

LevelSerializer & SaveEntry

Member	Purpose
PlayerName : String	The name of the current player – this is used to have different save games for different players – you can leave it blank if you don’t want this functionality.
SerializationMode : CacheSerialization/SerializeWhenFree	There maybe times when you suspend serialization and this mode lets you decide whether to automatically save a current state when suspending (CacheSerialization) – this means that saving the game will revert to this state. Can be useful on phones which may not give you much choice about when to save
Checkpoint()	Save a check point for Resume
Resume()	Resumes from a previous checkpoint
CanResume : Boolean	Is there resumption info available
SaveGame(name)	Saves the game to PlayerPrefs – get them back by examining SavedGames[playerName]
IsDeserializing : Boolean	Is the level currently being deserialized. You might want to do something different in your code when this is happening.
SerializeLevel() : String	Stores the current game state in a string
LoadSavedLevel(data : String)	Loads the level back from a previously saved string
SavedGames[playerName] : List<SaveEntry>	Dictionary lookup on PlayerName from PlayerPrefs.  Provides a list of the saved games for the player. Each entry has:Name– The name used when saving the gameWhen– The date/time that the game was savedLevel– the name of the level that was savedData – the data stored for the levelCaption– a simple caption summarising the saved game Load() – call to load the saved game Delete() – call to delete this saved game
SuspendSerialization	Call if you are about to do something that cannot be serialized.  This maintains a counter so you can nest calls.
ResumeSerialization	Call when it is ok to start serializing again.  This maintains a counter so you can nest calls.
Event	When
Deserialized	Fired when a level has finished loading
GameSaved	Fired when a new game has been saved
SuspendingSerialization	Fired when serialization will actually suspend (it wasn’t previously suspended)
ResumingSerialization	Fired when serialization will actually resume (no pending suspendserialization calls exist).
Store(GameObject, ref bool)	Fired for each game object to decide whether it should be saved.

LevelLoader

Member	Purpose
Data : LevelSerializer.LevelData	The level data to be loaded
showGUI : Boolean	True (default) if the screen should turn white during loading
DontDelete : Boolean	True (default false) if objects not found in the saved data should be kept
Static Events
CreateGameObject	Allows cancellation of the instantiation of stored prefabs
OnDestroyObject	Allows cancellation of the destruction of scene objects
LoadData	Allows cancellation of the loading of all data for a GameObject
LoadComponent	Allows cancellation of the loading of a particular component for a game object
LoadedComponent	Triggered after each component is loaded

UnitySerializer

Only externally useful members are listed.

Member	Purpose
AddFinalAction(Action)	Adds an action to be run when serialization is complete
AddPrivateType(Type)	Adds a type that should have all of its private members stored
Deserialize<T>(byte[]) : T	Deserializes an object graph whose root element is of type T from a byte array
Deserialize<T>(Stream) : T	Deserializes an object graph whose root element is of type T from a .NET Stream
DeserializeFromFile<T>(string filename) : T	Deserializes an object graph whose root element is of type T from a file. The Application.persistentDataPath is prepended to the filename you provide.
DeserializeInto(byte[] data, object instance)	Deserializes a byte array into an existing instance
DeserializingObject : object	During serialization this is set to the current object being deserialized. Useful in advanced custom serializers.
IsChecksum : bool	Indicates if the current save operation is forming a checksum
Serialize(object) : byte[]	Serializes an object into a byte array
Serialize(object, bool verbose) : byte[]	Serializes an object with optional verbose typing to a byte array
Serialize(object, Stream)	Serializes an object into a .NET stream
SerializeForDeserializeInto(object) : byte[]	Serializes an object when you know you won’t be creating the object but using an existing instance. Very useful for Components in Unity. Skips custom serialization and reference code generation which is what you want when you are actually saving a Component or MonoBehaviour derivative.
SerializToFile(object, string filename)	Serializes an object to a file. The Application.persistentDataPath is prepended to the path you provide.
Static Events
Event	Purpose
CreateType(object, ObjectMappingEventArgs e)	Used to create a type when the system fails to create it internally (perhaps no default constructor). Set e.Instance equal to an newly instantiated object of the type passed in e.TypeToConstruct
CanSerialize(object) : bool	Return true or false depending on whether you want the object passed to be serialized. Advanced.
MapMissingType(object, TypeMappingEventArgs e)	Return a type to use in place of a type that cannot be found. it should be semantically similar. e.TypeName contains the type to map. e.UseType should be set to the type to use in its place.

Useful attributes and their associated interfaces

[Serializer(Type)], [SubTypeSerializer(Type)] and ISerializeObjectEx

Decorate a class with the Serializer or SubTypeSerializer attribute and implement ISerializeObjectEx to change how standard objects are saved and loaded. Do not use this for components. This is advanced functionality and is not normally necessary for types you write yourself.

You can choose to inherit from SerializerExtensionBase for some default functionality

Member	Purpose
Serialize(object target) : object[]	Your code should serialize the target object into an array of objects. You can call UnitySerializer.Serialize for individual elements if that helps.
Deserialize(object[] data, object instance) : object	Deserialize the data you previously stored and return the new object. You may be passed an instance if one already exists, or it will be null otherwise.
CanSerialize(Type targetType, object instance)	Return true if you can serialize the type/instance combination at this time, false otherwise.

[ComponentSerializerFor] and IComponentSerializer

You can provide custom component serialization using this attribute/interface combination. Components are always created by the system, but you will have the opportunity to populate the fields and properties.

Member	Purpose
Serialize(Component component) : byte[]	Your code should serialize the component into a byte array (possibly using UnitySerializer). You can inherit from ComponentSerializerExtensionBase which provides a helper method allowing you to return and object array instead of a byte array.
Deserialize(byte[] data, Component instance)	Deserialize the data you previously stored into the supplied instance. Inheriting from ComponentSerializerExtensionBase provides some type safety and the ability to use an object array.

Interfaces

You can implement some interfaces as part of the serialization process. In C# you do this by adding the interface to your class, eg:

public class YourScript : MonoBehaviour, IControlSerialization
{
     public bool ShouldSave()
    {
         return true; //Decide here
    }
}

In JavaScript you have to explicitly declare your class (which is not the normal Unity way but works fine)

class YourScript extends MonoBehaviour, IControlSerialization
{
      function ShouldSave() : boolean
      {
           return true; //Decide here
      }
}

IControlSerialization

Used to allow your behaviours to decide whether they should be saved or not. Useful for implementing “Room” state rather than saving the game.

Member	Purpose
ShouldSave : boolean	return true to enable the item to be saved