Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/insality/defold-saver
Defold Save File Manager
https://github.com/insality/defold-saver
defold defold-extension defold-library defold-module lua save-manager
Last synced: about 2 months ago
JSON representation
Defold Save File Manager
- Host: GitHub
- URL: https://github.com/insality/defold-saver
- Owner: Insality
- License: mit
- Created: 2024-07-31T19:36:06.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-10-30T18:06:44.000Z (about 2 months ago)
- Last Synced: 2024-11-02T05:02:21.067Z (about 2 months ago)
- Topics: defold, defold-extension, defold-library, defold-module, lua, save-manager
- Language: Lua
- Homepage:
- Size: 807 KB
- Stars: 21
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/Insality/defold-saver/tags)
[](https://github.com/Insality/defold-saver/actions)
[](https://codecov.io/gh/Insality/defold-saver)
[](https://github.com/sponsors/insality) [](https://ko-fi.com/insality) [](https://www.buymeacoffee.com/insality)
# Saver
**Saver** - is a library for saving and loading save data in **Defold** projects. It provides a simple API for saving and loading save data, as well as support for migrations and simple key-value storage. The library supports saving and loading data in JSON, Lua, or binary format, and can save and load files to and from the file system.
## Features
- **Save and Load Game State**: Save and load data with a simple API.
- **File Management**: Save and load data to and from files.
- **Auto-Save**: Automatically save data at regular intervals.
- **Migrations**: Apply migrations to data when the migration version changed.
- **Storage**: Store key-value pairs in the save data.
- **Format support**: Save and load data in JSON, Lua or binary format.
## Setup
### [Dependency](https://www.defold.com/manuals/libraries/)
Open your `game.project` file and add the following line to the dependencies field under the project section:
**[Saver](https://github.com/Insality/defold-saver/archive/refs/tags/2.zip)**
```
https://github.com/Insality/defold-saver/archive/refs/tags/2.zip
```
After that, select `Project ▸ Fetch Libraries` to update [library dependencies]((https://defold.com/manuals/libraries/#setting-up-library-dependencies)). This happens automatically whenever you open a project so you will only need to do this if the dependencies change without re-opening the project.
### Library Size
> **Note:** The library size is calculated based on the build report per platform
| Platform | Library Size |
| ---------------- | ------------ |
| HTML5 | **5.23 KB** |
| Desktop / Mobile | **8.68 KB** |
### Configuration [optional]
You should configure the module in the `game.project` file:
```ini
[saver]
save_name = game.json
autosave_timer = 3
saver_key = saver
storage_key = storage
```
This configuration section for `game.project` defines various settings:
- **save_name**: The name of the save file. Default is `game.json`.
- **autosave_timer**: The time interval in seconds between auto-saves. Default is `3`.
- **saver_key**: The key in the save data table that contains the Saver state. Default is `saver`.
- **storage_key**: The key in the save data table that contains the Storage state. Default is `storage`.
### Core Concepts
Defold Saver uses the following core concepts:
- **Auto-Save**: Automatically save data at regular intervals. It used as a default save method. This allows you to specify the data you want to keep in the save file and the library will handle the rest.
- **Save State**: A Save state contains a set of table references in the save file. You can bind multiple save states. Bindings is done by the `saver.bind_save_state(id, table_reference)` function. When you bind the table to save state and previous data was saved, the save data will override values in your reference table. So usually you should bind the default table from module or your game data on game loader step.
- **Migration**: Migrations are used to update the save data if required. Migration is a just list of functions that will be applied to the save data if the migration version in save is less than the migrations count. You can set migrations by `saver.set_migrations` function before `saver.init` and apply them by `saver.apply_migrations` function after.
- **Storage**: Storage is a simple key-value storage that can be utilized in many ways and you don't want to make a separate save state for it. You can set and get values by `storage.set` and `storage.get` functions.
## Basic Usage
```lua
local saver = require("saver.saver")
local game_data = {
score = 0,
level = 1,
}
function init(self)
saver.init()
saver.bind_save_state("game", game_data)
-- Now we can change game_data content and it will be saved automatically via autosave
game_data.score = game_data.score + 1
-- Or you can save it manually by saver.save_game_state() if you want to save it immediately
saver.save_game_state()
end
```
## API Reference
### Quick API Reference
```lua
local saver = require("saver.saver")
saver.init()
saver.bind_save_state(table_key_id, table_reference)
saver.save_game_state([save_name])
saver.load_game_state([save_name])
saver.set_game_state(game_state)
saver.get_game_state()
saver.delete_game_state([save_name])
saver.save_file_by_path(data, absolute_file_path)
saver.load_file_by_path(absolute_file_path)
saver.delete_file_by_path(absolute_file_path)
saver.save_file_by_name(data, file_name)
saver.load_file_by_name(file_name)
saver.delete_file_by_name(file_name)
saver.set_autosave_timer(seconds)
saver.get_save_path(file_name)
saver.get_save_version()
saver.set_migrations(migration_list)
saver.apply_migrations()
saver.set_logger(logger)
saver.get_current_game_project_folder()
saver.before_save_callback = function() "Called before saver saves data" end
local storage = require("saver.storage")
storage.set(id, value)
storage.get(id, [default_value])
storage.get_number(id, [default_value])
storage.get_string(id, [default_value])
storage.get_boolean(id, [default_value])
```
### API Reference
Read the [API Reference](API_REFERENCE.md) file to see the full API documentation for the module.
## Use Cases
Read the [Use Cases](USE_CASES.md) file to see several examples of how to use the this module in your Defold game development projects.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Issues and Suggestions
For any issues, questions, or suggestions, please [create an issue](https://github.com/Insality/defold-saver/issues).
## 👏 Contributors
## Changelog
### **V1**
- Initial release
### **V2**
- Update docs, missing API for saver.delete_* functions
- Fix error with `get_current_game_project_folder` while using in HTML5 builds
- Add `saver.before_save_callback` callback for custom save logic. Can be used to prepare/update data before saving, like transfing from real-time data to save data
## ❤️ Support project ❤️
Your donation helps me stay engaged in creating valuable projects for **Defold**. If you appreciate what I'm doing, please consider supporting me!
[](https://github.com/sponsors/insality) [](https://ko-fi.com/insality) [](https://www.buymeacoffee.com/insality)