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.
All of the above for every child of the GameObject.

For information on Saving and Loading Prefab Instances, see the Saving and Loading Prefab Instances 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.

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

Further Reading