EzSaver

PRs Welcome License: MIT

A Flexible and Secure Saver for Unity Games, Enabling JSON Serialization and Secure File Storage.

View in DocFx

Features

  • Safe and secure file storage
  • Supports encryption(AES)
  • Custom-type JSON serialization
  • Supports file saving of various extensions
  • Includes a Menu window for various operations
  • Includes a Demo to help you quickly get started

Installation

Inside the Unity Editor using the Package Manager:

  • Click the (+) button in the Package Manager and select "Add package from Git URL" (requires Unity 2019.4 or later).
  • Paste the Git URL of this package into the input box: https://github.com/ebukaracer/EzSaver.git#upm
  • Click Add to install the package.
  • If your project uses Assembly Definitions, make sure to add a reference to this package under Assembly Definition References.

Dependencies

This package depends on Newtonsoft Json (v3.2.1). If it's not already available in your project, you can install it via the Unity Package Manager:

Setup

After installation, use the menu options in the following order:

  • Racer > EzSaver > Create EzSaverConfig? to create and initialize the required configuration file, necessary for the package to work.
  • Racer > EzSaver > Import Elements to import the prebuilt elements(prefabs) of this package, which will speed up your workflow(optional).
  • Racer > EzSaver > Add EzSaverManager Prefab to Scene to add the manager gameobject required for saving and loading.

Usage

In any of your scripts, you can perform the following operations:

Initialize a save-file:

using Racer.EzSaver.Utilities;  
using UnityEngine;  
  
public class UsageExample : MonoBehaviour
{
	public class Person  
	{  
	    public int Age { get; set; }  
	}

	private Person _person;
	private int _highscore;
	private EzSaverCore _ezSaverCore;
	
	private void Awake()    
	{  
	    // Initializes and sets up a save-file  
	    _ezSaverCore = EzSaverManager.Instance.GetSave("Save.txt");  
	      
	    // Alternatively, you can initialize it with a JSON string-literal  
	    // _ezSaverCore = EzSaverManager.Instance.GetSave(@"{""Highscore"": 1}", isJsonStringLiteral: true);
	
	    // Access previously saved content or use the type's default value  
	    _person = _ezSaverCore.Read("Person", new Person());  
	    _highscore = _ezSaverCore.Read("Highscore", _highscore);  
	}
}

Update save data:

public void AddScore(int amount)  
{
	_highscore += amount;  
	_person.Age = _highscore;
	
	// Store their changes temporarily
	_ezSaverCore  
	    .Write("Person", _person)  
	    .Write("Highscore", _highscore);
}

Save changes to save-file (📌):

// Find a suitable place to call Save() once.
private void OnDisable()  
{
	// Commit the overall changes to the initialized 'Save.txt' file
	_ezSaverCore.Save();
}

Clear save data:

_ezSaverCore  
    .Clear("Person", _person)  
    .Clear("Highscore", _highscore);

Delete save-file:

_ezSaverCore.DeleteFile();

Other Features

  • Automatic Save on Quit: Toggle autoSaveOnQuit in the EzSaverManager to automatically save changes when the application quits.
  • Save on Modification: Toggle saveOnModification to commit changes immediately after a write operation.
  • Security: Use the useSecurity parameter to enable encryption/decryption for save files.

Samples and Best Practices

  • Always generate new credentials for each project and back them up securely.
  • In the case of any updates to newer versions, use the menu option: Racer > EzSaver > Import Elements(Force)
  • Optionally import this package's demo from the package manager's Samples tab.
  • To remove this package completely(leaving no trace), navigate to: Racer > EzSaver > Remove package

FAQs

What platforms are supported?

Tested on Android, Windows, and WebGL (see Q2). Probably supported on macOS and iOS.

Will it really work for WebGL builds?

Partially. Since WebGL doesn't allow file system access, save-files cannot be stored traditionally. As a workaround, you can initialize save data as a string literal and use PlayerPrefs to store the final save state.

Is save data encrypted? How can I manage the keys?

Yes, encryption is supported and optional during initialization. The current encryption keys can be found in the Config Asset under:
Racer > EzSaver > Menu > Config Asset.

What could cause data loss?

Imagine this scenario: You deploy a project xyz using credentials abc (save-keys). Later, if you generate new credentials cba for the same project xyz, all previous save data tied to abc will be overwritten and lost. To prevent this, always back up your credentials and restore them when needed using the Config Asset.

Does that mean I should never change the current credentials?

Not necessarily! You can generate new credentials anytime during development. If potential data loss isn't a concern, feel free to proceed. Even if credential regeneration causes save data to be overwritten, the system automatically creates a backup of the original save file. This backup uses a naming pattern based on the original filename: For example, if your original save file is data.json, the backup will be saved as data-backup0.json. This gives you a way to recover the lost data if needed.

Can I modify the contents of the save file?

Absolutely — as long as encryption is disabled. Modifying an encrypted save file will cause decryption to fail, resulting in data loss. It’s recommended to only modify the plain JSON string when encryption is turned off.

Can different save files have different credentials within the same project?

Technically yes, but it’s risky and may lead to data corruption or loss. A safer approach is to generate and back up a unique set of credentials per project — for example:
Project A → abc,
Project B → xyz.
However, multiple projects can still share the same credentials if necessary.

What if I forget to save after making modifications?

If automatic saving is enabled (which it is by default), EzSaverManager.cs will handle this for you. Just so you know, automatic saving and on-the-go saving only work if you initialized from a file source. If initialized from a string literal, you'll need to define save trigger points manually.

How to Restore Lost/Overwritten Save Data

First, ensure Retain Backup File was toggled on in the Config Asset, then:

  • Locate the backup file:
    • Find the backup file (e.g., data-backup0.json) in the default save location.
  • Recover the original save:
    • Open the backup file.
    • Copy its contents and paste them into your original save file (e.g., overwrite e.g., data.json with the contents of data-backup0.json).
  • Restore the original credentials:
    • Open the Config Asset tool.
    • Choose Restore Credentials File.
    • From the file menu, select the credentials file that was originally used with your data.json save-file (prior to generating the new ones).
  • Apply changes:
    • After restoring the correct credentials for the save-data, the system will recognize and resume from the original saved state.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Edit this page