Godot Game Scenarios

Use the Godot addon through real game lifecycle flows.

These examples map the JavaScript reference concepts to GDScript method names and Godot lifecycle points.

Concept Parity

Same Persistly model, Godot method names.

Account, slot, accountData, conflict, and cleanup behavior match JavaScript and Unity. Only the API style changes.

Boot Godot scenes from local slots first; cloud sync should not block loading unless the game requires a fresh check.

Signed-in restore uses your backend to store accountId plus accountSessionToken, then configure restores that session.

refresh_slot pulls the named cloud slot after account attach without exposing internal save identifiers to normal game code.

AccountData holds shared state across all slots: bundles, shared inventory, settings, and validated currency balances.

clear_local_account is local logout. delete_slot and delete_account are permanent erasure flows.

Cross-Device Restore

Restore a signed-in player, then refresh the named slot.

Persistly does not recover anonymous local saves by email alone. Your trusted backend stores the Persistly account session after first sync.

GDSCRIPT

# Device A: after sign-in and first successful sync.
persistly.force_sync_data({ "bypassCooldown": true })

var session := persistly.get_account_session({ "includeToken": true })
my_backend.save_persistly_link(user_id, session["accountId"], session["accountSessionToken"])

# Device B: same player signs in later.
var link := my_backend.get_persistly_link(user_id)

var persistly := PersistlyGameSaves.new()
persistly.configure({
  "runtime_key": "ps_test_...",
  "playerRef": user_id,
  "accountId": link["accountId"],
  "accountSessionToken": link["accountSessionToken"],
})

persistly.refresh_data()
var loaded := persistly.load_data()

Shared Account State

Use accountData for state shared across all slots.

Use this for bundles, shared inventory, settings, and display balances after trusted purchase validation.

Account Data

Patch shared state, inspect it locally, then sync the account.

patch_account_data shallow-merges top-level keys. Null deletes a top-level key; nested objects and arrays are replaced.

GDSCRIPT

persistly.patch_account_data({
  "diamonds": 200,
  "bundles": {
    "starter": true,
  },
  "sharedInventory": [1, 25, 35],
})

var account_data := persistly.get_account_data()
var account := persistly.inspect_account()

persistly.force_sync_account({ "bypassCooldown": true })

Lifecycle

Save locally first; force sync at Godot lifecycle boundaries.

Async work during close is not guaranteed on every export target, so also sync on checkpoints, pauses, and manual save moments.

GDSCRIPT

persistly.save_data(current_data)

func _notification(what):
  if what == NOTIFICATION_WM_CLOSE_REQUEST:
    persistly.force_sync_data({ "bypassCooldown": true })

func _on_checkpoint_reached(data: Dictionary) -> void:
  persistly.save_data(data)
  persistly.force_sync_data({ "bypassCooldown": true })

Cleanup

Keep logout and permanent erasure separate.

Use local clear for account switching. Use delete methods only behind explicit danger UI.

GDSCRIPT

# Logout or switch local player. Cloud data stays intact.
persistly.clear_local_account()

# Permanent slot/account erasure. Use only behind explicit danger UI.
persistly.delete_slot("autosave")
persistly.delete_account()