Easily save, load, version and manage your Godot game's data!

🤔 About

The Locker plugin is a framework created in Godot 4.3 meant to simplify the process of saving, loading and managing data in Godot projects.

This plugin has as one of its main goals being open for user customizations, allowing the use of different user defined strategies for accessing data.

✨ Features

Down below are listed the main features of this Plugin.

📪 Gathering and Distribution of data

The gathering and distribution of data is the main feature of this framework. This functionality refers to how this plugin is able to keep track of who needs access to the storage, and to handle how that access is realized.

For the implementation of this feature, two important concepts are used: StorageManagers and StorageAccessors. StorageAccessors are Nodes capable of handling the access of saved data, while StorageManagers are responsible for managing the StorageAccessors that need to access that data.

In order to be able to manipulate those StorageAccessors, an autoload called GlobalStorageManager is defined when the plugin is activated. This is a singleton capable of collecting and sending data to all active StorageAccessors in the scene.

🗃 Multiple Save Files

One of the features that this Plugin provides is the possibility of using multiple save files for storing data. That can be used to achieve systems similar to some games where data for different gameplays are stored in different save files, usually referred to as file 1, file 2, file 3 and etc.

The multiple save files system also makes it possible to store files with whatever name you'd like. You can even use stringified timestamps to store different save files at different times.

🔪 Separation in Partitions

Beyond allowing the separation of data in multiple save files, the Locker Plugin also allows the separation of data inside a save file in multiple partitions. This can be used to better organize the data or even to make the data accessing process quicker, when only the data of a few partitions is involved.

Partitions can be used, for example, to separate data from different players so that when the data of one player is needed, only its partition needs to be loaded.

⏰ Asynchronous operations

Another feature that this Plugin brings is the handling of file accessing operations as asynchronous functions. This allows the game to keep being responsive even if there are large amounts of data to load or save.

For the user convenience, handy signals are provided when the data manipulation initializes or finishes, so that actions can be taken at those times.

To facilitate the interaction with those asynchronous operations, the methods involved were defined as coroutines, so that you can use the await keyword in order to await their execution only when necessary.

📰 Save files versioning

The Locker Plugin also aims at facilitating the process of updating old save files to new versions of a game.

That's why StorageAccessors are composed by StorageAccessorVersions. These StorageAccessorVersions allow you to define different mechanisms to handle the data accessed across different versions of your save files, which can facilitate the process of updating the scheme of saved data in new game versions.

🔑 Customizable Access Strategies

One of the main objectives of this plugin is being open to customizations. That's why the AccessStrategy concept is implemented.

The AccessStrategy is a class that abstracts how data is written and read using this Plugin. This approach allows for new AccessStrategies to be easily implemented in the future, or even by users.

For the default usage of this Plugin, two built-in AccessStrategies are available: The JSONAccessStrategy and the EncryptedAccessStrategy.

🔧 Easy configuration

With all these features, the Plugin needed a place to allow quick configuration. For that, the Godot built-in ProjectSettings are used. That means that for quickly setting up your preferred configurations for this Plugin, you just need to go to the path "addons/locker" in your ProjectSettings and tweak the desired properties.

🔽 Installation

To download this Asset, you can use one of the following ways:

Godot Asset Library

Latest Stable Version

The Asset Library is the easiest way of downloading this project. The version you will encounter there is the latest stable one.

When downloading through the Asset Library, you can easily select what AccessStrategies you want to include or exclude from your project. That way, you don't have to download AccessStrategies that you aren't going to use.

Github Releases

Latest Stable Version

One of the ways of downloading this plugin is directly through Github Releases. There, you'll find the available stable versions. Just select the desired version and install it.

Itch.io

Latest Stable Version

This project is also available on Itch.io, if you prefer downloading from there. The version available there is also the latest stable one.

Github Development

Latest Unstable Version

If you want to download the latest unstable version, you can download it cloning the Github repository or downloading it directly from there.

---

After installing this Plugin, make sure to activate it in the Godot settings, so that it can automatically add its autoload to the project and work properly.

📚 Documentation & examples

Documentation for this Asset can be found directly in the code, written with GDScript Doc Comments, so that you can read them in the Godot Editor.

Some starter examples of core functionalities of the Plugin can be found in the examples folder in the root of this project on Github.

Guides and tutorials about how to use this framework will be/ are also available in the Github Wiki.

🧪 Testing

This project has unit tests (located in the test/unit folder) to validate its correct functionality. Those tests are written with the use of the GUT Plugin, by @bitwes, also available in the Godot Asset Library.

🤝 Contributions

If you like this project, consider supporting me on Ko-fi or on Github so I can keep on making content like this! :D

If you can't support me those ways, starring on Github or rating, commenting or adding to collections on Itch.io would go a long way :)

Other than that, here are some ways you can contribute to this project, so that we can improve it together:

• If you found a bug, feel free to Create an Issue pointing it out. The more informations the better. Also, including a Minimal Reproduction Project would go a long way;
• If you see an Issue that you think you can help with, give it a try! :)
• If you have an idea for a feature, you can also create an Issue.

📃 License

This framework is distributed under the MIT license, you can use it on your projects. Attribution is appreciated, but not necessary.

If you use this project and you'd like to, let me know commenting on Itch.io! I'd love to see what you can make with it :)

Credits

Framework created with ❤️ by @nadjiel

I hope this framework helps you with your project! :D