Install The Godot Addon And Save Your First Slot

Godot integrations should start with the PersistlyGameSaves addon facade. Keep scenes focused on gameplay data and put cloud-save behavior behind one small save service.

Install The Addon

Download the addon repository:

https://github.com/Persistly/persistly-sdk-godot

Copy the addon into your project:

res://addons/persistly

Enable it from Godot project settings, then preload the facade:

const PersistlyGameSaves = preload("res://addons/persistly/persistly_game_saves.gd")

Configure The SDK

Create and configure the facade once:

var persistly := PersistlyGameSaves.new()

func _ready() -> void:
    persistly.configure({
        "runtime_key": "ps_test_replace_me"
    })

Use stage runtime keys while building. Switch to production runtime keys only for release exports.

Load Before Gameplay

Load the default save before applying scene data:

var loaded := persistly.load_data()
var data = loaded.get("data", {})

if typeof(data) == TYPE_DICTIONARY and not data.is_empty():
    start_game_from_state(data)
else:
    start_new_game()

Validate dictionaries before applying them to nodes.

Save The First Game State

Save stable data, not node instances:

persistly.save_data({
    "schemaVersion": 1,
    "level": 1,
    "coins": 50,
    "checkpoint": "forest-gate",
})

save_data is the local-first write for one-save games. It protects player progress before network sync.

Sync At Safe Moments

Force sync while testing:

var sync := persistly.force_sync_data()

For normal play, call sync on controlled events such as checkpoint, pause menu, or reconnect:

func on_checkpoint_reached(checkpoint_id: String) -> void:
    persistly.save_data({
        "schemaVersion": 1,
        "level": player.level,
        "coins": player.coins,
        "checkpoint": checkpoint_id,
    })

    persistly.force_sync_data()

Multiple Slots

Use one slot key per slot or manual save:

persistly.save_slot("warrior", warrior_state, {
    "slotInfo": {
        "characterName": "Borin",
        "className": "Warrior",
        "level": 12,
    }
})

persistly.save_slot("mage", mage_state, {
    "slotInfo": {
        "characterName": "Ayla",
        "className": "Mage",
        "level": 9,
    }
})

var slots := persistly.list_slot_data()

Keep real gameplay data in the data dictionary. Keep slot names, class labels, level previews, and last-played timestamps in slotInfo.

What To Test Next

• Run the game, save, restart, and load again.
• Disable network and confirm local save still works.
• Re-enable network and call force_sync.
• Add a second slot.
• Add conflict recovery before cross-device release testing.