Getting Started
After importing Easy Save from the Asset Store, you can immediately use Easy Save from your scripts and in PlayMaker.
For information on PlayMaker actions available, see the PlayMaker Actions Overview.
Basic saving and loading
Easy Save stores data as keys and values, much like a Dictionary.
- To save a value, use ES3.Save<Type>.
- To load a value, use ES3.Load<Type>.
For example, to save an integer to a key named myInteger and load it back again, you could do:
C#
|
1 2 3 4 5 |
// Save the integer 123 to a key named myInteger. ES3.Save<int>("myInteger", 123); // Load the integer back again. int myInteger = ES3.Load<int>("myInteger"); |
JS
|
1 2 3 4 5 |
// Save 123 to a key named myInteger. ES3.Save.<int>("myInteger", 123); // Load the integer back again. var myInteger : int = ES3.Load.<int>("myInteger"); |
If you’re unsure whether a key exists before loading, you can use ES3.KeyExists or specify the defaultValue parameter of the ES3.Load method.
C#
|
1 2 3 4 5 6 7 8 9 |
// If the key "myKey" does not exist, this will throw an error. myValue = ES3.Load<float>("myKey"); // This checks whether "myKey" exists before trying to load it. if(ES3.KeyExists("myKey")) myValue = ES3.Load<float>("myKey"); // If "myKey" doesn't exist, it returns our default value. myValue = ES3.Load<float>("myKey", 123f); |
JS
|
1 2 3 4 5 6 7 8 9 |
// If the key "myKey" does not exist, this will throw an error. myValue = ES3.Load.<float>("myKey"); // This checks whether "myKey" exists before trying to load it. if(ES3.KeyExists("myKey")) myValue = ES3.Load.<float>("myKey"); // This returns our default value of 123 if "myKey" does not exist. myValue = ES3.Load.<float>("myKey", 123f); |
To load a value into an existing object, use ES3.LoadInto.
C#
|
1 2 3 4 5 |
// Save the Transform of this object. ES3.Save<Transform>("myTransform", this.transform); // Load the value we just saved back into this Transform. ES3.LoadInto<Transform>("myTransform", this.transform); |
JS
|
1 2 3 4 5 |
// Save the Transform of this object. ES3.Save.<Transform>("myTransform", this.transform); // Load the value we just saved back into this Transform. ES3.LoadInto.<Transform>("myTransform", this.transform); |
Saving and loading arrays and collections
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.
For example, to save collections:
|
1 2 3 4 5 6 7 8 |
// Save an int array ES3.Save<int[]>("myArray", myArray); // Save a List of strings ES3.Save<List<string>>("myList", myList); // Save a Dictionary of string keys and Vector3 values ES3.Save<Dictionary<string, Vector3>>("myDictionary", myDictionary); |
And then to load them:
|
1 2 3 4 5 6 7 8 |
// Load the int array myArray = ES3.Load<int[]>("myArray"); // Load the List of strings myList = ES3.Load<List<string>>("myList"); // Load the Dictionary of string keys and Vector3 values myDictionary = ES3.Load<Dictionary<string, Vector3>>("myDictionary"); |
What can I save and load?
To see what types are supported, see our Supported Types guide.
When should I save and load?
You can save and load anywhere you can run code, but typically it makes sense to load in Unity’s Start() routine, and save in Unity’s OnApplicationQuit() routine.
As OnApplicationQuit() is not always called on mobile platforms, OnApplicationPause(bool paused) should be used on mobile platforms. As we want to save when the application pauses, you should only save when the paused parameter is true.
C#
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
public class SaveLoad : MonoBehaviour { void OnApplicationQuit() { // Save the position and rotation when the application quits. ES3.Save<Vector3>("myPosition", transform.position); ES3.Save<Quaternion>("myRotation", transform.rotation); } // Also save when the application pauses on mobile devices. void OnApplicationPause(bool paused) { if(paused) OnApplicationQuit(); } void Start() { // Load our position and rotation when this script loads. // Or return default values if there's no data to load. transform.position = ES3.Load<Vector3>("myPosition", Vector3.zero); transform.rotation = ES3.Load<Quaternion>("myRotation", Quaternion.identity); } } |
JS
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
public class SaveLoad extends MonoBehaviour { function void OnApplicationQuit() { // Save the position and rotation when the application quits. ES3.Save.<Vector3>("myPosition", transform.position); ES3.Save.<Quaternion>("myRotation", transform.rotation); } // Also save when the application pauses on mobile devices. function void OnApplicationPause(paused : bool) { if(paused) OnApplicationQuit(); } function void Start() { // Load our position and rotation when this script loads. // Or return default values if there's no data to load. transform.position = ES3.Load.<Vector3>("myPosition", Vector3.zero); transform.rotation = ES3.Load.<Quaternion>("myRotation", Quaternion.identity); } } |
You could also create a Save() and Load() method containing your save code, and link these to a save and load button.
More information on Unity’s event functions can be found in their Event Functions page.
Files, Paths and Locations
The filePath parameter of ES3 methods lets you specify the file in which the data is saved.
If you only specify a filename, this will point to a file in the default file location. You can check whether a file exists using the ES3.FileExists method.
The file will be automatically created if it does not exist, and if saving a key which already exists in the file, that key will be overwritten.
It’s even possible to save and load a file from a sub-directory in the default save location, or an absolute path. For detailed information see the Paths and Locations guide.
C#
|
1 2 3 4 5 6 7 8 9 10 11 |
// Save a value to the default file in the default save location. ES3.Save<int>("myKey", myValue); // Save a value to a file named "myFile.es3" in the default save location. ES3.Save<int>("myKey", myValue, "myFile.es3"); // Save a value to a file named "myFile.es3" in a sub-directory called "myFolder" in the default save location. ES3.Save<int>("myKey", myValue, "myFolder/myFile.es3"); // Save a value to a file named "myFile.es3" in an absolute folder. ES3.Save<int>("myKey", myValue, "C:/Users/User/Documents/myFile.es3); |
JS
|
1 2 3 4 5 6 7 8 9 10 11 |
// Save a value to the default file in the default save location. ES3.Save.<int>("myKey", myValue); // Save a value to a file named "myFile.es3" in the default save location. ES3.Save.<int>("myKey", myValue, "myFile.es3"); // Save a value to a file named "myFile.es3" in a sub-directory called "myFolder" in the default save location. ES3.Save.<int>("myKey", myValue, "myFolder/myFile.es3"); // Save a value to a file named "myFile.es3" in an absolute folder. ES3.Save.<int>("myKey", myValue, "C:/Users/User/Documents/myFile.es3"); |
Deleting
- Use ES3.DeleteKey to delete a key.
- Use ES3.DeleteFile to delete a file.
- Use ES3.DeleteDirectory to delete a directory.
C#
|
1 2 3 4 5 6 7 8 |
// Delete a key from a file. ES3.DeleteKey("myKey", "myFolder/myFile.es3"); // Delete an entire file. ES3.DeleteFile("myFolder/myFile.es3"); // Delete a directory and all of the files it contains. ES3.DeleteDirectory("myFolder/"); |
JS
|
1 2 3 4 5 6 7 8 |
// Delete a key from a file. ES3.DeleteKey("myKey", "myFolder/myFile.es3"); // Delete an entire file. ES3.DeleteFile("myFolder/myFile.es3"); // Delete a directory and all of the files it contains. ES3.DeleteDirectory("myFolder/"); |
Settings and Encryption
You can supply an ES3Settings object as a parameter to most methods to enable options such as encryption. See the ES3Settings page for more information on the options available.
C#
Save data using an ES3Settings object to specify settings.
|
1 2 3 4 5 6 7 8 9 |
// Create a new ES3Settings to enable encryption. var settings = new ES3Settings(ES3.EncryptionType.AES, "myPassword"); // Change the save location to PlayerPrefs. settings.saveLocation = ES3.Location.PlayerPrefs; // Use the ES3Settings object to encrypt data and save to PlayerPrefs. ES3.Save<Transform>("myTransform", this.transform, settings); // Use the ES3Settings object to load the data from PlayerPrefs and decrypt it. ES3.Load<Transform>("myTransform", this.transform, settings); |
JS
Save data using an ES3Settings object to specify settings.
|
1 2 3 4 5 6 7 8 9 |
// Create a new ES3Settings to enable encryption. var settings = new ES3Settings(ES3.EncryptionType.AES, "myPassword"); // Change the save location to PlayerPrefs. settings.saveLocation = ES3.Location.PlayerPrefs; // Use the ES3Settings object to encrypt data and save to PlayerPrefs. ES3.Save.<Transform>("myTransform", this.transform, settings); // Use the ES3Settings object to load the data from PlayerPrefs and decrypt it. ES3.Load.<Transform>("myTransform", this.transform, settings); |