Have you ever thought that I just want to save a boolean using Unity PlayerPrefs? Or just wanted an easy way to see data saved in Unity, just to see if everything is ok or to change something? Or maybe you're tired of dealing with old scripts for saving files, deleting files, and so on in every project you work on. If yes, I feel you, and you know why I created Ped!
In short Persistence easy to delete, or just Ped, is a small library to easily handle persistence in Unity editor and abstract persistence flow in Unity projects.
Why do we have to settle for saving just float, int and string with PlayerPrefs? We don't have to. With Ped we can use Unity's PlayerPrefs to persistbool, byte, sbyte, char, decimal, double,float, int, uint, long, ulong, short, ushort, string and also object. Yeah, an entire object!! 😮
Ok, maybe would be better save objects as files, so to our happiness Ped also abstracts the logic to persist object as files, you just need to ask.
Ped also compresses data to save space and protect it, and uses a similar approach with all keys used, so your data can be well saved!! 😊
After install Ped... Ok, maybe it is important talk a little about how to install Ped. You can do this from Git following these steps:
-
Copying git url https://github.com/thisaislan/persistence-easy-to-delete.git
-
Click on
Window/Package Managerin Unity Editor -
Click on add package button
-
Select
Add package from git URL...
- Past the Ped url
- Press
Enteror clink on theAddbutton
Now, with Ped properly installed, you can start using it without further preparation! 😆
Okay you're probably wondering about data manipulation, fair enough, let's see a little bit about that.
Once the installation is complete, you will see two new folders inside of the Assets folder, Ped and Settings (in case these folders already exist, Ped will use the existing ones). Inside of the Settings folder you will see a file called PedSettings and inside of the Ped folder you can se a file called PedData:
PedSettings is a control center for actions of Ped. Here you can choose the data you want to use and define behaviors.
PedData is where data will be stored when the game is running in the editor. Through this file you can change any data, add new inputs, remove existing ones or just change their values.
(Don't worry, if you accidentally delete these files, Ped always creates new ones when they're gone. 😉)
Ok, Ok. Maybe it's time to show the code.
Let's say you just want to save a humble boolean using PlayerPrefs (yes, the same boolean I wanted to save), with Ped you just need to do this:
Ped.SetPlayerPrefs(booleanKey, yourBooleanValueHere);The same to string:
Ped.SetPlayerPrefs(stringKey, yourStringValueHere);And with Long:
Ped.SetPlayerPrefs(longKey, yourLongValueHere);ulong:
Ped.SetPlayerPrefs(uLongKey, yourULongValueHere);Ok, you got the idea! 😏
But just for a moment, for some reason that I don't know, we decided to save an entire object using PlayerPrefs. Okay, maybe now things get a little complicated. Are you prepared?
You need to do this:
Ped.SetPlayerPrefs(objectKey, yourObjectHere);So, as you can see, if you know how to save one thing using Ped, you can save anything. And if you (like me) prefer to save objects as files, just do the following:
Ped.SetFile(objectKey, yourObjectHere);Ped will save your data as a PlayerPrefs or file (depending on the method used) inferring and using the object's type.
To retrieve any value from Ped just use Get methods with correct key and type, for example if I want to retrieve my precious boolean saved as PlayerPrefs previously, I need to use this:
Ped.GetPlayerPrefs(booleanKey, (bool booleanRetrieved) =>
{
// Do something with the retrieved value
});To retrieve the object saved as file:
Ped.GetFile(objectKey, (ObjectType objectRetrieved) =>
{
// Do something with the retrieved value
});Now you might be thinking "what if I don't know if the save exists?"
In this case you can use:
Ped.HasPlayerPrefsKey<TypeOfTheData>(key, (bool result) =>
{
// Do something with the result
});or
Ped.HasFileKey<TypeOfTheData>(key, (bool result) => {
});Or if you're feeling really naughty, you could just try this 😈:
Ped.GetFile(ObjectType, (ObjectType objectRetrieved) =>
{
// Do something with the retrieved value
}, () => {
// Do something if the value does not exist
});Ped has some few methods and approaches designed to help you with PlayerPrefs and files. Below you can see all the public methods you will find on Ped.
| Feature | Description |
|---|---|
| Serialize | Compress and serialize a object |
| Deserialize | Decompress and deserialize a object |
| SetPlayerPrefs | Saves PlayerPrefs with a specific key, type and value |
| GetPlayerPrefs | Loads PlayerPrefs with a specific key and type |
| DeletePlayerPrefs | Deletes PlayerPrefs with a specific key and type |
| DeleteAllPlayerPrefs | Deletes all PlayerPrefs key and values by calling PlayerPrefs.DeleteAll() |
| HasPlayerPrefsKey | Returns true if the given key exists in PlayerPrefs, otherwise returns false |
| SavePlayerPrefs | Writes all modified preferences to disk by calling PlayerPrefs.Save() |
| SetFile | Saves file with a specific key, type and e value |
| GetFile | Loads file with a specific key and type |
| DeleteFile | Deletes file with a specific key and type |
| DeleteAllFiles | Deletes all files saved |
| HasFileKey | Checks if exists a file with a specific key and type |
| DeleteAll | Deletes all data, both files and PlayerPrefs |
Some methods, such as Gets and Sets, have flags to help you perform specific actions. For example with the code below it is possible to do a destructive get, that is, PlayerPrefs will be destroyed after obtaining it. 🎏
Ped.GetPlayerPrefs(booleanKey, actionIfHasResult, Ped.PlayerPrefsGetMode.Destructive);Every time you use a Set method of Ped in the Unity editor, the value will be saved in the PedData file being used. As in the image below:
Therefore, it is possible to change, add or remove any data whenever you need it, also in the middle of a run in the editor. You can change the value, key and even the type by the PedData, just be careful not to break your game... 😅
But don't worry, if you edit a field and want to check if everything is ok, just go to Tools/Ped/Validate PedData (or just use Shift+F11) and Ped will perform a validation on your data and let you know in the console if something wrong happened (we'll see more about validation later 😉).
You probably noticed the Avoid Changes option in the image, this flag allows us to use the data, see the changes when Unity is in play mode and reset the data to the same previous values when exit of play mode. Very useful when we don't want to lose a specific set of data but want to use it to test the game's behavior.
Perhaps another thing you noticed in the last image was the Info field. If you expand this field, you can see more information about the PedData file.
in possession of this information you can track how your game is using the data, if has a excessive numbers of Gets or Sets, or just now how many times you have used that file (maybe you're a little too attached to him 💗).
Let's say you're creating a game and in that game you can choose different characters, that characters can have different sets of items and different amounts of money. This means that every time you want to test a specific character with a specific set of items and a specific amount of money, you need to set all the data before starting a test, right? Good luck! 🕧
Maybe Ped can help you with that task, just create as many PedData as you need, fill each PedData with proper data, go to the PedSettings file and define the PedData file you want to use, and done, you have all set of data you need to test your game (may that is a nice moment to use the Avoid Changes flag).
Another cool part of this approach is that you can share your PedFiles with your team, so you only have to do it once. 😍
Tip: If your project uses git, stay smart with how you and your team are going to handle git for sharing the files.
Along with save booleans Ped was built thinking about an important aspect of development (at least for me), the democratization of development. If you're familiar with Unity, you probably you know how to find saved files, how to edit a json, and how to reset a PlayerPrefs. But if you're not familiar with these things, you might have trouble figuring out how to do these things and how to make sure the new data changes are correct.
So in this case, Ped works by creating an easy place to show your data saved in Unity (as shown before), but it also lets you run validation on your data whenever you want, just press Shift+F11 or Tools/Ped/Validate PedData. 😎
(As you can see Ped has some options and shortcuts, feel free to explore them. 😉)
Validation will be performed automatically every time Ped realizes that the data has changed or in the first run after opening Unity (you know, just in case). That option can be disabled in PedSettings just by uncheck the option Verify Data On Run Start
During validation, Ped will show all errors in the console, even if the error was in the Custom Serializer... Witch bring us to the next topic!
I know you saw that section in the PedSettings:
And yes, as the name suggests, you can drop in the Custom Serializer field a class to be used as the serializer class by Ped. That class needs to be:
- Public
- Not Static
- Cannot be inside a custom assembly
- Implements IPedSerializer interface
- Implements Serializer and Deserializer methods
- And it should only be one class in the file (inner classes can be used)
And now Ped is read to use the new serializer class even after the build (don't worry, Ped knows how to do this).
What!? Ho! Yeah! You are probably thinking about the field Custom Serializer Path, well it is indeed just the path to the file. 😁
Tip: If your project uses git, don't forget to push the changes in the PedSettings file to your team.
Yep, Ped always tries to create a PedData and a PedSettings if it doesn't find these files in the project.
This happens due to the pillar of democratization of development, which is why Ped always tries to help solve any problem that may cause some frustration in its use.
To be sincere, I have no plans to turn Ped into a huge tool, I think this tool can help with a specific task and it should be so. So at least for now I don't think about creating the new Odin or anything like that, lol.
Totally!! 😂But I strongly recommend you look up a little bit about PlayerPrefs, save files and ScriptableObject in Unity, just to know a little bit about these topics.
Maybe I was a bit swayed by the PlayerPrefs idea, where you need to say what kind of data you want to get (GetString, GetInt, GetFloat) and pass the correct key. To me this makes perfect sense, if you save a rock in the bank you can't get a diamond back 💎 (lol) so you need to know the key and type and Ped will take that into account.
That means if you pass the correct key and the incorrect type Ped won't find the data, also there will be no crash. Ped just will answer as no data was found with that key and type.
In fact, when you try to save any data with Ped at runtime, Ped will create a key by concatenating the key you passed and the type, creating a unique key. For example, the follow code:
Ped.SetPlayerPrefs("MyPreciousBool", true);The key resulting will be a hash of the string MyPreciousBool~System.Boolean.
That also means you can use the same key with different types and use the same key to save PlayerPrefs and Files without problems, although I really don't recommend that approach.
One more piece of information, if you use a key and type that already exists, the old value will be overwritten. ✏️
Probably. I believe...actually I now that there are some improvements that I can do yet, and probably some fixes in the future. So I think there will be some updates in the future
There are few things actually. But nothing critical I think. 😊
If you have something, just send to me! 😜
Please! 💛
Every time you run the application or access Tools/Ped, Ped checks if these files exist, otherwise new files will be created.
Because I wanted a silly presentation with a some images and I didn't want to put too many images in the projects of each person using Ped. So I kept the project lightly documented and created this new repository to show more about the project.
Because now it's possible to configure a custom serializer and I can't guarantee if the new serializer class has the same restrictions as the one used by the one used as default by Ped.
In addition, it is possible to see in the editor the result of the serialization in PedData, so it is easy to see any problems in the serialization.
Well, because you can use the standard shortcut to do this, Ctrl+d or Command+D. I don't think this feature will add much to the project (of course I could be wrong here, let me know now please 😶).
No way ❗ The only ScriptableObject that make it to the final build is PedSerializeSettings. This ScriptableObject is responsible for taking care of data from the custom serializer class, if it exists, and its use is internal to Ped.
No way ❗ The only ScriptableObject that make it to the final build is PedSerializeSettings. This ScriptableObject is responsible for taking care of data from the custom serializer class, if it exists, and its use is internal to Ped.
Because of pillar of democratization of development. Validation is a very important part of this process, whole team needs to feel free to change any data during development, and if for some reason someone accidentally mistypes something, Ped will help they next time that they try to run the project.
Of course, if the automatic validation for some reason takes too long, or is slowing down development, it is possible to disable this flag and relay the manual validation, just press Shift+F11 or Tools/Ped/Validate PedData when the data has changed.
Remembering that the automatic validation will only be performed when the data is changed manually and in the first run, otherwise Ped understands that there is no need for validation.
It is very important to ask people for help to avoid errors, using this approach it was necessary to define the custom serializer class in two places, in the code and in the editor for validation purposes. Realizing that this could lead to human errors, I removed the method and created a way to configure the custom serializer just by the editor.
(again I could be wrong here, let me know now please 😶).
Sincerely?! No 😕! The Custom Serializer field is a MonoScript, and I don't know why but sometimes when you set that file, although you can see the file in the editor and you can push that change using git, when you try to get that info back using git, this field is reset by Unity. Because that Ped saves the path to the file and set the Custom Serializer field if needed.
I recommend it. Of course that depends on how you and your team works, but maybe that is the best alternative to avoid endless conflict...:scream: And if you put PedData, or even better the Ped folder, in gitignore, you can always share the PedData files just by uploading the file another way.
So far, Ped has been tested on small and medium-sized mobile projects. I'm not sure if Ped will work well in a big project, for example, but I think so. If you have a big project and you've already tried Ped, please let me know.
The short answer is yes. In editor mode, Ped uses reflection when validation is running. At runtime, Ped will use reflection once when the project is opened if the project has a custom serializer class, otherwise not.
Because at some point I was informed that the old name is a pejorative word in French. I'm sorry about the problem with this new name, but I can't stand the idea of creating a tool with an offensive name, even if it's unintentional.
Easy, just pronounce the first "e" like the first "e" in "Education". 🆎
Pediː
Persistence easy to delete, I chose this name because its acronym creates a good pun in my first language. 😝
