Getting started

After importing Easy Save from the Asset Store, you can immediately use Easy Save from your scripts and from PlayMaker.

For information on saving and loading without code using Auto Save, see the Auto Save guide.

For information on PlayMaker actions available, see the PlayMaker Actions Overview.

If you use Assembly Definitions, see the Assembly Definition files section near the bottom of this page.

Easy Save stores data as keys and values, much like a Dictionary.

To save a value, use ES3.Save
To load a value, use ES3.Load

For example, to save an integer to a key named myInt and load it back again, you could do:

ES3.Save("myInt", 123);
myInt = ES3.Load<int>("myInt", defaultValue);

1 2	ES3.Save("myInt", 123); myInt = ES3.Load<int>("myInt", defaultValue);

If there’s no data to load, it will return the defaultValue.

If you don’t specify a defaultValue, you must ensure that there is data to load (for example using ES3.KeyExists):

if(ES3.KeyExists("myInt"))
    myInt = ES3.Load<int>("myInt");

1 2	if(ES3.KeyExists("myInt")) myInt = ES3.Load<int>("myInt");

To load a value into an existing reference, use ES3.LoadInto:

// Loads data directly into a Transform, rather than creating a new one.
ES3.LoadInto("myTransform", this.transform);

1 2	// Loads data directly into a Transform, rather than creating a new one. ES3.LoadInto("myTransform", this.transform);

Note that ES3.LoadInto only works for reference types, not primitive types (e.g. int, string) or value types (e.g. structs).

You save and load classes, Components and ScriptableObjects in the same way as you would save any other data. However, there are some important things to note:

A class’s field will be saved if it:
- Is public, or has a [SerializeField] attribute
- Is not const or readonly
- Does not have the [Obsolete] or [NonSerialized] attribute
- Is a supported type

UnityEngine.Object types are stored by reference and value.
- This means that if the instance you are loading already exists in a scene, it will load the data into that instance rather than creating a new one.

If a field of the class is a UnityEngine.Object type (e.g. Component, ScriptableObject, Texture2D, etc), it will be saved by reference.
- This means that if the instance does not exist in the scene, a new instance will not be created upon loading and the field will be set to null.
- If you wish to save them by value you should save them with a seperate ES3.Save call and load them before loading anything which references them.

GameObjects are saved and loaded like any other object. The following information about the GameObject will be saved:

This will save and load the following aspects of the GameObject:

layer, tag, name and hideFlags.
Components on the Natively-supported types list, or those which have been manually supported using an ES3Type or selected in an ES3GameObject Component.
All of the above for every child of the GameObject.

For information on Saving and Loading Prefab Instances and more detailed information on saving GameObjects, we recommend taking a look at the Saving and Loading GameObjects and Prefabs guide.

You can also save and load Arrays, Lists, Dictionaries, Queues, Stacks and HashSets in the same way as you would save and load any other data.

Array

ES3.Save("myArray", myArray);
myArray = ES3.Load("myArray", defaultValue);

1 2	ES3.Save("myArray", myArray); myArray = ES3.Load("myArray", defaultValue);

List

ES3.Save("myList", myList);
myList = ES3.Load("myList", defaultValue);

1 2	ES3.Save("myList", myList); myList = ES3.Load("myList", defaultValue);

Dictionary

ES3.Save("myDictionary", myDictionary);
myDictionary = ES3.Load("myDictionary", defaultValue);

1 2	ES3.Save("myDictionary", myDictionary); myDictionary = ES3.Load("myDictionary", defaultValue);

2D Array

ES3.Save("my2DArray", my2DArray);
my2DArray = ES3.Load("my2DArray", defaultValue);

1 2	ES3.Save("my2DArray", my2DArray); my2DArray = ES3.Load("my2DArray", defaultValue);

Queue

ES3.Save("myQueue", myQueue);
myQueue = ES3.Load("myQueue", defaultValue);

1 2	ES3.Save("myQueue", myQueue); myQueue = ES3.Load("myQueue", defaultValue);

HashSet

ES3.Save("myHashSet", myHashSet);
myHashSet = ES3.Load("myHashSet", defaultValue);

1 2	ES3.Save("myHashSet", myHashSet); myHashSet = ES3.Load("myHashSet", defaultValue);

Stack

ES3.Save("myStack", myStack);
myStack = ES3.Load("myStack", defaultValue);

1 2	ES3.Save("myStack", myStack); myStack = ES3.Load("myStack", defaultValue);

For most projects it makes sense to load in Start(), and save in OnApplicationQuit(), or OnApplicationPause(true) on mobile.

You can also use buttons to save and load.

By default save data is stored in Unity’s Application.persistentDataPath, the locations of which you can find in their documentation. You can open this path in the Editor by going to Tools > Easy Save 3 > Open Persistent Data Path.

The exception to this is WebGL, which stores data to PlayerPrefs, which in turn stores data to IndexedDB.

The filePath parameter lets you specify where data is saved. The file or folder will be automatically created if it does not exist.

This can be a filename, a relative path, or an absolute path. For more information, see the Paths and Locations guide.

Filename

// Save a value to a file in the default location.
ES3.Save("myKey", myValue, "myFile.es3");

1 2	// Save a value to a file in the default location. ES3.Save("myKey", myValue, "myFile.es3");

Relative path

// Save a file to a folder in the default save location.
ES3.Save("myKey", myValue, "myFolder/myFile.es3");

1 2	// Save a file to a folder in the default save location. ES3.Save("myKey", myValue, "myFolder/myFile.es3");

Absolute path

// Save a value to a file in an absolute folder.
ES3.Save("myKey", myValue, "C:/Users/User/Documents/myFile.es3);

1 2	// Save a value to a file in an absolute folder. ES3.Save("myKey", myValue, "C:/Users/User/Documents/myFile.es3);

Delete a key

ES3.DeleteKey("myKey", "myFolder/myFile.es3");

1	ES3.DeleteKey("myKey", "myFolder/myFile.es3");

Delete a file

ES3.DeleteFile("myFolder/myFile.es3");

1	ES3.DeleteFile("myFolder/myFile.es3");

Delete a directory

ES3.DeleteDirectory("myFolder/");

1	ES3.DeleteDirectory("myFolder/");

Change default settings by going to Window > Easy Save 3 > Settings.

Enable settings at runtime by providing an ES3Settings object as a parameter. See the ES3Settings page for more information.

Enable encryption

var settings = new ES3Settings(ES3.EncryptionType.AES, myPassword);
  
ES3.Save("key", data, settings);
ES3.Load("key", data, settings);

var settings = new ES3Settings(ES3.EncryptionType.AES, myPassword);

ES3.Save("key", data, settings);

ES3.Load("key", data, settings);

Enable compression

var settings = new ES3Settings(ES3.CompressionType.Gzip);
  
ES3.Save("key", data, settings);
ES3.Load("key", data, settings);

var settings = new ES3Settings(ES3.CompressionType.Gzip);

ES3.Save("key", data, settings);

ES3.Load("key", data, settings);

To see what types are supported, see our Supported Types guide.

As with all code, it is recommended that you handle errors. This can be performed using a try/catch block to catch exceptions, and display an appropriate message to the user when necessary. For example:

try
{
    ES3.Save("key", 123);
    ES3.Save("key2", 456);
}
catch(System.IO.IOException)
{
    DisplayMessageToUser("The file is open elsewhere or there was not enough storage space");
}
catch(System.Security.SecurityException)
{
    DisplayMessageToUser("You do not have the required permissions");
}
//etc

try

{

ES3.Save("key", 123);

ES3.Save("key2", 456);

}

catch(System.IO.IOException)

{

DisplayMessageToUser("The file is open elsewhere or there was not enough storage space");

}

catch(System.Security.SecurityException)

{

DisplayMessageToUser("You do not have the required permissions");

}

//etc

For more information on what types of error you may need to handle please see the Error Handling guide.

You can enable Easy Save’s assembly definition files by going to Tools > Easy Save 3 > Enable Assembly Definition Files.

If you want to access Easy Save 3 from an assembly, add the EasySave3 asmdef to the Assembly Definition References list of your assembly’s asmdef.

These are some important things to note which people sometimes get stuck on when saving and loading data in Unity:

You should only save data which needs to be saved and loaded. For example instead of saving an entire GameObject, you should only select the Components which need to be saved.
It’s not possible to load a reference to something which no longer exists. For example, if you create an object at runtime, an object with this reference ID will no longer exist when you quit the scene or exit the app. See the Saving and Loading References guide for information on how to handle this.
Some Components such as PlayerControllers or AI controllers might cache the position of objects, which means saving and loading that object’s Transform won’t have any effect on the position of the object. In this case it might be necessary to disable the Component which controls the position before loading, and re-enable it after loading.

We recommend taking a look at the following for more information:

Getting started

Basic saving and loading

Saving and loading classes, Components & ScriptableObjects

Saving and loading GameObjects and Prefabs

Saving and loading collections

Array

List

Dictionary

2D Array

Queue

HashSet

Stack

When to save and load

Where save data is stored

Changing the filename or path

Filename

Relative path

Absolute path

Deleting

Delete a key

Delete a file

Delete a directory

Changing settings

Enable encryption

Enable compression

What can be saved and loaded

Error handling

Assembly definition files

Important tips

Further Reading