Godot SDK

Runtime SDK track pinned to the Persistly contract.

The Godot SDK track now implements the runtime contract directly with explicit create, load, sync, cache, and error-envelope behavior while staying aligned with the shared Persistly API.

Current State

What exists today and what is still pending.

Contract bundle is pinned and the intended runtime surface is visible.

The runtime shape is create, load, and sync by explicit save ID, with a small canonical-save cache.

Blocking HTTP transport, fixture-driven validation, and error-envelope handling now exist. The remaining work is live editor/runtime verification in an environment with a Godot binary.

Last Beacon now ships as a playable endless-idle proof inside the Godot repo and uses the SDK for create, load, and sync.

Runtime Surface

The Godot client now follows the same save contract as JavaScript and Unity.

create_save(payload) creates a save and returns the canonical save envelope.

load_save(save_id) loads a known save by explicit saveId.

sync_save(save_id, payload) preserves both accepted and conflict responses, including the canonical server save on conflicts.

Install

Use the public Godot addon source, not a private checkout path.

Download the addon from the official GitHub repository and copy addons/persistly into your Godot project.

Official repository: https://github.com/persistly/persistly-sdk-godot

Setup

Configure the client with the public API origin and a runtime key.

var client := PersistlyClient.new(
  "https://api.persistly.app",
  "ps_test_..."
)

var created := client.create_save({
  "externalUserId": "auth0|player-184",
  "metadata": {
    "characterName": "Ayla",
    "slotLabel": "Mage"
  },
  "state": {
    "coins": 418,
    "checkpoint": "vault"
  }
})

var result := client.sync_save(created.save.saveId, {
  "baseVersion": created.save.version,
  "metadata": created.save.metadata,
  "state": {
    "coins": 612,
    "checkpoint": "reactor"
  }
})

Behavior Notes

What the current Godot SDK enforces.

HTTP and HTTPS runtime requests go through HTTPClient with an explicit bearer runtime key and timeout.

Payload size checks run locally before transport: 16 KB for metadata and 256 KB for state.

A small in-memory cache stores canonical saves by saveId and can provide baseVersion when the caller omits it during sync.

Playable Demo

Use the public Last Beacon project to verify a real engine integration.

The official Godot repository includes Last Beacon, an endless idle proof project that creates, loads, and syncs Persistly saves from a custom game UI.

Use the sample to confirm gameplay flow, saveId handling, and conflict behavior before you wrap Persistly in your own project abstractions.

Validation

Validate against the public sample and your stage environment.

Run the official sample with a ps_test_ key and verify create, load, sync, and a forced conflict before using ps_live_ in production.

Keep your game UI custom. Persistly should stay behind the scenes as the save-sync layer.