Saving a Character
Of all the Character properties, only ID and the emotes list remain unimplemented. Both of these will be covered in this step.
So far, we can visualize all of our character choices being aggregated in the inspector for the Character component. However, all of those changes are still lost when we stop the game. To persist these changes, we need to store the data we see in the inspector to the file system.
Remember that our 3-part process started with modeling the data structure we want to save, followed by implementing the structure in C# objects, and finishes by storing a JSON representation to the file system. We will add additional functions to our Character class that will handle JSON and file system operations.
Return to Character.cs and add these JSON helper moethods:
// Methods
public string ToJson() {
return JsonUtility.ToJson(this);
}
public void LoadFromJson(string json) {
JsonUtility.FromJsonOverwrite(json, this);
}
ToJson converts an instance of our Character C# object into a JSON string. LoadFromJson goes the opposite direction and accepts a JSON representation of a character and converts it back to an instance of our C# object. ToJson will be used when we want to save data, while LoadFromJson will be used when we want to restore data from a save file.
When saving to the file system, you have reliable access permissions to a specific folder located at the persistent data path 🔗. (It may be worth reviewing this link to see the latest information on where Unity games will store persistent data on your device.) You also have some freedom to organize directories and files within this persistent data path. For security reasons, many modern platforms do not give you free reign throughout the entire file system, which is why we rely on access to this particular folder.
The persistent data path differs across operating systems, and different platforms also use different slashes (\ or /) when addressing folders. Because of this inconsistency, we must avoid hardcoding file addresses in our code. Instead, we use Unity's helper methods and environment properties to compose addresses that are reliable across different gaming platforms.
static string GenerateDirectoryPath() {
return Application.persistentDataPath + Path.DirectorySeparatorChar + "Characters";
}
static string GenerateFilePath(int charId) {
return GenerateDirectoryPath() + Path.DirectorySeparatorChar + charId + ".json";
}
These two helper methods reliably generate cross-platform addresses for accessing our game's save folder and save files. Notice in this code that we do not hardcode any particular folder and instead rely upon Unity's application and path configuration. You can also see that these functions are written as "static" because we do not require a particular Character instance to utilize them, unlike our JSON helper functions which only make sense within the context of a Character instance.
On my personal device, this code generates file addresses such as ~/Library/Application Support/DefaultCompany/VG3_SantosRobert/Characters/1.json, but because my platform may differ from yours, your own save directory may be drastically different. (You will see debugging code to help you find your save files in an upcoming code snippet.)
Our game will utilize a separate file for each character stored in the "Characters" directory. To avoid naming collisions, the filename will be based on a unique incrementing ID.
// Generate new id
int FindUnusedId() {
int result = 1;
// Check if file/id exists
while(File.Exists(GenerateFilePath(result))) {
result++;
}
return result;
}
In the FindUnusedId function, we start with file ID #1 and increment, checking for used filenames until we find an unused number to use as both the ID and filename.
public void SaveToFile() {
// New characters need an id and filename
if(id <= 0) {
id = FindUnusedId();
}
string path = GenerateFilePath(id);
string directory = Path.GetDirectoryName(path);
if(!Directory.Exists(path) && directory != null) {
Directory.CreateDirectory(directory);
}
StreamWriter sw = new StreamWriter(path);
sw.Write(ToJson());
sw.Close();
// print("Saved to " + path); // Debugging
}
Saving to the filesystem takes a few steps. First, we determine if we are making a new save file, or updating an existing character. Because the id property is an integer, it initializes to 0 by default for new characters. This means, we can rely on id 0 being the indicator for requiring a new save file, while all other positive ids mean a save file for that character already exists. (Lines 50 to 53)
Whether we have generated a new id or are using an existing id, we next assemble a save file address based on the id. We check that the save directory actually exists and create that directory too if necessary. In many file management functions, you cannot create a file if its parent directory does not already exist first. (Lines 55 to 60)
Finally, we utilize a class known as the StreamWriter to create our new JSON text file and write our data into it. It is important to clean-up after your file access, so other processes can have their turn editing a file, which is why you should "Close()" out your file operation. Notice that I have also provided debugging code at Line 66. I recommend you uncomment this line, so that the game will tell you where to find your save file in order for you to check your work. (Lines 62-66)
With all our Character save helper functions in place, we need UI button logic that will collect our emotes and trigger our save function.
public void Save() {
character.emotes = menuEmoteBuilder.GetEmotes();
character.SaveToFile();
}
Let's double-check our work. (Be sure to uncomment the debugging code in Character.cs, Line 66 mentioned prior.) Start the game. Customize your character and don't forget to create a few emotes too. Return to the main character creator menu. Click the "Save" button.
Upon clicking save, you should be able to inspect your Character gameObject and verify that all inspector fields have populated including Id and Emotes. The Console log should also tell you where to find your save file.
Locate the save file on your hard drive. (You may have to reveal hidden files as appropriate for your operating system.) Opening your save file should reveal JSON data, but it is probably difficult to read. We frequently save data without any spaces or formatting to avoid wasting storage.
{"id":1,"playerName":"My Character","model":2,"color":{"r":0.11372549086809159,"g":0.5647059082984924,"b":1.0,"a":1.0},"emotes":[{"frameIndex":0,"iconIndex":1},{"frameIndex":5,"iconIndex":5},{"frameIndex":6,"iconIndex":7}]}
You can reformat the JSON by hand following traditional code indentation rules to make the JSON easier to read. You might also have a text editor with the feature or use an online JSON formatter tool.
{
"id": 1,
"playerName": "My Character",
"model": 2,
"color": {
"r": 0.11372549086809158,
"g": 0.5647059082984924,
"b": 1,
"a": 1
},
"emotes": [
{
"frameIndex": 0,
"iconIndex": 1
},
{
"frameIndex": 5,
"iconIndex": 5
},
{
"frameIndex": 6,
"iconIndex": 7
}
]
}
Compare your JSON data to the Character inspector values. They should all match. In the inspector, you will see the enum value name for the model, while the matching integer is used in JSON instead. Unity's inspector also portrays RGB color values ranging from 0 to 255, but in JSON, the values range from 0 to 1. You should still have equivalent values for all properties despite the different representations.
To avoid polluting your console with unnecessary messages, you should comment Character.cs, Line 66 again now that we are done debugging.
While we can confirm that our save data is persisting to the file system, restarting the game still resets us to a default character. In order to continue using our characters after the game restarts, we must also implement loading functionality which we will explore in the upcoming tutorial.
