# SaveKit for Godot

A library for saving and loading game state in Godot 4, with pluggable save file formats and a focus on ease of use.

Key features:

- **Easy to get started.** Add nodes to the `saveable` group, then use `SaveManager.save_game()` and `SaveManager.load_game()`.
- **Saves nodes and resources.** Built-in resources, like textures and packed scenes, are saved as references, while data from nodes and custom `SaveKitResource` subclasses is saved in its entirety. This avoids the code injection risks of Godot's `ResourceLoader`, while supporting complex data.
- **JSON and binary serialization built-in**, or implement your own custom save file format by extending `SaveKitSerializer` and `SaveKitDeserializer`.
- **Automatic by default, manual when you need it.** Reflection picks up exported properties for saving/loading automatically, or you can implement custom `save_to_dict` and `load_from_dict` methods for full control.

## Getting started

1. Enable the plugin in **Project > Project Settings > Plugins**. This also installs a `SaveManager` autoload.
2. Add all the nodes you want saved to the `saveable` group.
3. Call one method to save, another to load:

```gdscript
# Save to disk under user://save_games/MyGame/Slot 1.json
SaveManager.save_game(PackedStringArray(["MyGame", "Slot 1"]))

# Load it back later
SaveManager.load_game(PackedStringArray(["MyGame", "Slot 1"]))
```

This will iterate through nodes in the `saveable` group, serialize each node's exported properties, and write the file into `user://save_games/`. Then the reverse is done on load—creating or freeing nodes as needed so the scene tree matches the save file.

There are also other methods offering finer-grained control over the save/load process:

```gdscript
func save_scene_tree_in_memory() -> PackedByteArray
func save_scene_tree_to_disk(absolute_path: String) -> Error

func load_scene_tree_from_memory(data: PackedByteArray) -> bool
func load_scene_tree_from_file(absolute_path: String) -> Error
```

## Saving nodes

By default, SaveKit uses reflection to save all `@export` and `@export_storage` properties whose values differ from their defaults. For a lot of nodes, this is all you need:

```gdscript
extends CharacterBody2D

@export var health: int = 100
@export var player_name: String = ""
@export_storage var checkpoint: Vector2
```

When you need additional control, implement `save_to_dict` and `load_from_dict`:

```gdscript
extends RigidBody2D

func save_to_dict(s: SaveKitSerializer) -> Dictionary:
    return {
        "transform": s.encode_var(transform),
        "linear_velocity": s.encode_var(linear_velocity),
    }

func load_from_dict(s: SaveKitDeserializer, data: Dictionary) -> void:
    var t: Transform2D = s.decode_var(data["transform"], TYPE_TRANSFORM2D)
    PhysicsServer2D.body_set_state(get_rid(), PhysicsServer2D.BODY_STATE_TRANSFORM, t)

    linear_velocity = s.decode_var(data["linear_velocity"], TYPE_VECTOR2)
```

You can also mix the two approaches by calling `serializer.default_save_to_dict()` and `deserializer.default_load_from_dict()` from your implementation.

### Node instantiation

If a saved node isn't in the scene tree at load time, SaveKit will instantiate it from the `scene_file_path` it was saved with and parent it where it belongs. Conversely, nodes in the `saveable` group that *aren't* in the save data are freed, so the scene tree always matches the save file after loading.

## Saving resources

For resources that represent persisted data—e.g., inventories, quest state, per-entity stat blocks—extend `SaveKitResource` rather than plain `Resource`:

```gdscript
class_name Inventory
extends SaveKitResource

@export var gold: int = 0
@export var items: Array[Item]
```

Any `SaveKitResource` referenced from a saved node is serialized automatically, and deduplicated. Like nodes, `SaveKitResource` uses reflection over exported properties by default, but you can always implement `save_to_dict` and `load_from_dict` for custom behavior.

Note that plain `Resource` references (textures, scenes, and other things baked into the PCK) are saved as path/UID references. SaveKit will only ever load such resources from within the `res://` filesystem, avoiding the risk of code injection from user-provided resource files.

## Lifecycle hooks

There are a variety of signals and methods to hook into the saving and loading process—`before_save`, `after_save`, `before_load`, `after_load`, etc. See the `SaveManager` API documentation for more details.

## Save file formats

SaveKit includes two built-in file formats:

- **JSON** (`json_serializer.gd`, `json_deserializer.gd`) — human-readable, easy to diff and debug.
- **Binary** (`binary_serializer.gd`, `binary_deserializer.gd`) — compact, obfuscated.

JSON, the default, is recommended in most cases. File size is rarely a concern, and making saves human-readable is more friendly to your players.

You can also implement a custom file format by extending `SaveKitSerializer` and `SaveKitDeserializer` and implementing the abstract methods.

Assign `SaveManager.serializer_script` and `SaveManager.deserializer_script` to switch between formats or use your own:

```gdscript
SaveManager.serializer_script = preload("res://addons/savekit/binary_serializer.gd")
SaveManager.deserializer_script = preload("res://addons/savekit/binary_deserializer.gd")
SaveManager.save_file_extension = ".sav"
```

## Learn more

The [included demo](demo/) has a small interactive scene that is fully saveable, and includes a live view into the JSON file format.

All public classes (`SaveManager`, `SaveKitSerializer`, `SaveKitDeserializer`, `SaveKitResource`) have documentation comments that work with Godot's built-in help. Browse them from the editor for the full API reference.

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.