https://github.com/youssof20/savestate
Atomic save system for Godot 4 - .bak backups, schema migration, and Saveable node groups. Free Lite tier. Pro version with encryption, async, and editor tooling on itch.io.
https://github.com/youssof20/savestate
game-development gdscript godot godot-4 godot-addon godot-plugin indie-game-dev mit-license open-source save-system
Last synced: 2 months ago
JSON representation
Atomic save system for Godot 4 - .bak backups, schema migration, and Saveable node groups. Free Lite tier. Pro version with encryption, async, and editor tooling on itch.io.
- Host: GitHub
- URL: https://github.com/youssof20/savestate
- Owner: youssof20
- License: mit
- Created: 2026-04-02T05:28:30.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T05:55:41.000Z (2 months ago)
- Last Synced: 2026-04-07T12:02:27.653Z (2 months ago)
- Topics: game-development, gdscript, godot, godot-4, godot-addon, godot-plugin, indie-game-dev, mit-license, open-source, save-system
- Language: GDScript
- Homepage:
- Size: 165 KB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# SaveState Lite
[](#godot-version-support)
[](LICENSE)
Godot 4 addon: **atomic** save files, rolling **`.bak`** backups, **schema versioning** with forward merge, and one **`SaveManager`** autoload for key–value data and named slots — without building a custom format from scratch.
**Docs:** [Quick start](QUICKSTART.md) · [Full API](docs/API.md) · [Architecture & threading](docs/ARCHITECTURE.md) · [Migration (incl. `migration_required`)](docs/MIGRATION.md) · [Starter sample](samples/minimal-demo/README.md)
**v1.2:** typed `register_key` (with optional Save Browser color hints), `register_editor_hint`, debounced `mark_dirty`, `set_schema_migrations`, JSON export, `SaveComponent` / `CollectionLink` / `SaveStatePickupVacuum`, slot import/export helpers, Save Browser color picker + `SaveStateUnixDisplay`, `save_menu_lite.tscn`, and Pro `templates/save_menu_pro.tscn`.
---
## Why this exists
Godot projects often start with ad-hoc `FileAccess` writes. That becomes painful fast: torn writes after crashes, no backup story, and no clean way to evolve save data when you add fields. SaveState Lite centralizes **atomic commits** (write to temp → validate → rename), **optional `.bak`**, and a **single schema number** with merge-from-defaults for older files.
**Technical challenges baked in:** careful ordering with temp files and rename for atomicity; keeping async Pro saves safe by **snapshotting on the main thread** before `WorkerThreadPool` I/O (see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)); and editor/plugin ordering so Lite loads before Pro when both are enabled.
See [CHANGELOG.md](CHANGELOG.md) — each version lists **Lite** (this repo) and **Pro** ([itch.io](https://chuumberry.itch.io/savestate-pro)) separately.
---
## Installation
The **repository root** is not a Godot project (there is no `project.godot` there). Either open **`samples/minimal-demo`** after you copy the addon into it (see that folder’s README), or copy **`addons/savestate/`** into **your** game project’s `addons/` folder.
1. Copy the `addons/savestate/` folder into your Godot project (merge with `addons/`).
2. **Project → Project Settings → Plugins** → enable **SaveState (Lite)**.
3. The **SaveManager** autoload is registered (`res://addons/savestate/save_manager.gd`).
**SaveState Pro** (paid, separate from this repo) requires both Lite and the Pro plugin folder in your project. See [itch.io](https://chuumberry.itch.io/savestate-pro).
**GitHub Releases** attach **`savestate-lite-.zip`** (drop-in `addons/savestate/`). Pushing a new tag `v*` triggers Actions to open the release and upload the zip. To **create or refresh** releases for existing tags (notes + zip), run **`tools/publish_github_releases.ps1`** from the repo root with **`GITHUB_TOKEN`** set to a PAT with repo **Contents** read/write (see the script header).
---
## Quick start
```gdscript
SaveManager.set_value(&"player_gold", 250)
SaveManager.persist()
```
```gdscript
var player_gold := int(SaveManager.get_value(&"player_gold", 0))
```
```gdscript
SaveManager.save_to_slot_sync(&"slot_1", {"player_health": 100})
var data := SaveManager.load_from_slot_sync(&"slot_1")
```
More patterns: **[QUICKSTART.md](QUICKSTART.md)**. Full method list: **[docs/API.md](docs/API.md)**.
---
## Saving nodes (Lite)
Lite does not ship a `Saveable` node in this repo. Nodes in group `savestate_saveable` that implement **`get_storage_key`**, **`collect_snapshot`**, and **`apply_snapshot`** participate in `persist_including_saveables()` / `load_from_slot_and_apply_saveables()`. The **Saveable** node and inspector tooling ship with **SaveState Pro**: [SaveState Pro on itch.io](https://chuumberry.itch.io/savestate-pro).
---
## Pro version
Pro swaps the autoload for `pro_manager.gd`, adds async save/load, optional AES-256 + HMAC, thumbnails, **Save Browser** dock extras, Saveable inspector, and Quick Setup menu entries. Details: [https://chuumberry.itch.io/savestate-pro](https://chuumberry.itch.io/savestate-pro)
---
## Godot version support
Godot **4.3**, **4.4**, **4.5**, and **4.6** are tested and supported. The addons use stable 4.x APIs (`DirAccess.remove_absolute`, `FileAccess.get_modified_time`, `Time.get_datetime_string_from_unix_time`, `ColorPickerButton`, etc.) as documented for those versions; Lite and Pro `plugin.cfg` files note this range.
---
## License
Lite is MIT licensed. Use it in any project, commercial or otherwise, with no attribution required.