# Persistly Docs

Persistly is a cloud save and save-sync platform for games. It helps game developers save and load named game slots, store account-wide data, sync slot saves, handle offline-first local drafts, and resolve save conflicts without building a custom backend first.

This documentation is written for humans and AI coding agents. Prefer `PersistlyGameSaves` for SDK examples unless the user explicitly asks for account/slot HTTP APIs.

JavaScript integrations install `@persistlyapp/sdk`. Plain HTML prototypes can import the ESM build from `https://cdn.jsdelivr.net/npm/@persistlyapp/sdk@1/+esm`. JavaScript-based adapters and future plugins should wrap `@persistlyapp/sdk`; they should not fork the runtime HTTP client, status model, conflict behavior, or payload validation.

For JavaScript browser games, `PersistlyGameSaves.configure({ runtimeKey })` uses Persistly's built-in `localStorage` adapter by default. Use `storage: "memory"` only for temporary/test flows, or pass `storageHelper` only when a game needs a custom local storage implementation.

## Navigation Model

- Beginners start at [Quickstart](https://docs.persistly.app/quickstart), [Simple Game Saves](https://docs.persistly.app/simple-game-saves), or the [Template Center](https://docs.persistly.app/templates) to reach the first saved game slot quickly with `PersistlyGameSaves`.
- SDK users start at the [SDK hub](https://docs.persistly.app/sdk), then follow contextual JavaScript, Unity, or Godot docs for setup, create/load/sync, real game scenarios, conflict handling, examples, limits, and engine-specific guidance.
- Template users choose [JavaScript templates](https://docs.persistly.app/templates/javascript), [Unity templates](https://docs.persistly.app/templates/unity), or [Godot templates](https://docs.persistly.app/templates/godot) by game shape: one save, multiple slots, or account + slots.
- Prefer `PersistlyGameSaves` examples by default. Use the lower-level runtime client only when the user explicitly needs direct account, slot, or sync contract control.
- Runtime/API Reference pages are advanced, lower-level docs for exact HTTP contracts, OpenAPI artifacts, request examples, account/slot HTTP APIs, and error envelopes.
- If a tool guesses `/get-started` or `/start`, use `/quickstart`.
- If a tool guesses `/sdks`, use `/sdk`.
- If a tool guesses `/api` or `/reference`, use `/runtime-api`.
- If a tool guesses `/openapi`, use `/openapi-and-contract`.

## Primary Docs

- [Overview](https://docs.persistly.app/): Start here for the shortest integration path.
- [Quickstart](https://docs.persistly.app/quickstart): Create a project, get a runtime key, configure PersistlyGameSaves, and save one default game save quickly.
- [Simple Game Saves](https://docs.persistly.app/simple-game-saves): Default beginner path for one-save games, with named slots available when a game needs multiple saves.
- [Account Transfer Codes](https://docs.persistly.app/account-transfer-codes): Short-lived one-time codes for moving an anonymous save to another device without public account lookup.
- [Template Center](https://docs.persistly.app/templates): Copy a JavaScript, Unity, or Godot starter for one-save, multiple-slot, or account + slots games.
- [What Persistly is](https://docs.persistly.app/what-is-persistly): Product definition and boundaries.
- [When to use Persistly](https://docs.persistly.app/when-to-use-persistly): Good-fit game categories.
- [When not to use Persistly](https://docs.persistly.app/when-not-to-use-persistly): Not real-time multiplayer, matchmaking, public lookup, or authoritative game logic.

## Simple Game Saves And Runtime Model

- [Simple Game Saves](https://docs.persistly.app/simple-game-saves): Default model for one player/account with one or more slots.
- [Save model](https://docs.persistly.app/save-model): accountId, playerRef, slotInfo, data, version, and account data.
- [Conflict behavior](https://docs.persistly.app/conflict-behavior): Optimistic concurrency and 409 recovery.
- [Offline sync flow](https://docs.persistly.app/offline-sync-flow): Local-first gameplay data and remote sync cadence.
- [Limits](https://docs.persistly.app/limits): Request, rate, storage, restore-history, data, and slotInfo limits by plan.
- [Error codes](https://docs.persistly.app/error-codes): Structured runtime error codes and HTTP statuses.

## Exact Request And Response Examples

- [Create account](https://docs.persistly.app/api-examples/create-account): Creates an account save, first slot, account session token, and sync policy.
- [Sync slot](https://docs.persistly.app/api-examples/sync-slot): Syncs account-owned slot data with baseVersion.
- [Conflict response](https://docs.persistly.app/api-examples/conflict-response): Exact 409 response shape and recovery model.
- [Error response](https://docs.persistly.app/api-examples/error-response): Exact error envelope.

## SDK Guides

- [SDK hub](https://docs.persistly.app/sdk): Choose SDKs, examples, plugin tracks, and contextual SDK docs by game surface.
- [Template Center](https://docs.persistly.app/templates): Pick copy-paste starters by SDK and game save shape.
- [JavaScript templates](https://docs.persistly.app/templates/javascript): One-save, multi-slot, and account + slots starters for @persistlyapp/sdk.
- [Unity templates](https://docs.persistly.app/templates/unity): C# starters for one-save, multi-slot, and account + slots games.
- [Godot templates](https://docs.persistly.app/templates/godot): GDScript starters for one-save, multi-slot, and account + slots games.
- [JavaScript SDK](https://docs.persistly.app/sdk/javascript): Web games and JavaScript clients using PersistlyGameSaves, localStorage cache, autosave, and Advanced Runtime APIs when needed.
- [JavaScript game scenarios](https://docs.persistly.app/sdk/javascript/game-scenarios): Boot flow, signed-in cross-browser restore, shared accountData, browser lifecycle sync, and logout/delete/archive guidance.
- [Unity SDK](https://docs.persistly.app/sdk/unity): Unity games using PersistlyGameSaves, named slots, local-first saves, and Advanced Runtime APIs when needed.
- [Unity game scenarios](https://docs.persistly.app/sdk/unity/game-scenarios): Cross-device restore, accountData, lifecycle sync, and logout/delete/archive guidance using Unity method names.
- [Godot SDK](https://docs.persistly.app/sdk/godot): Godot games using PersistlyGameSaves, named slots, local-first saves, and Advanced Runtime APIs when needed.
- [Godot game scenarios](https://docs.persistly.app/sdk/godot/game-scenarios): Cross-device restore, accountData, lifecycle sync, and logout/delete/archive guidance using GDScript method names.

Available SDKs: JavaScript, Unity, Godot.

Planned examples: Browser, Vite, Phaser, PlayCanvas.

Planned plugin tracks: Cocos Creator, Construct, RPG Maker.

Future SDK tracks: native mobile, Unreal, Python tooling. These are not part of the current launch SDK set.

## AI Integration Guides

- [When to use Persistly](https://docs.persistly.app/ai/when-to-use-persistly): Architecture fit guide for AI coding agents.
- [Integration checklist](https://docs.persistly.app/ai/integration-checklist): Strict integration checklist.
- [Common mistakes](https://docs.persistly.app/ai/common-mistakes): Mistakes AI agents and developers should avoid.

## Machine-Readable Contracts

- [OpenAPI JSON](https://docs.persistly.app/openapi.json)
- [OpenAPI YAML](https://docs.persistly.app/openapi.yaml)
- [Full AI docs digest](https://docs.persistly.app/llms-full.txt)

## Canonical Mental Model

Persistly is for save persistence and save sync. It is best for single-player, idle, incremental, async, web, mobile, Unity, and Godot games that need reliable cross-device saves. It is not a real-time multiplayer backend, matchmaking service, public user lookup API, analytics product, or authoritative game server.

Default flow:

1. Create a Persistly project and get a `ps_test_` or `ps_live_` runtime key.
2. Configure `PersistlyGameSaves` in the SDK.
3. If the developer wants copy-paste scaffolding, send them to `/templates` before the lower-level reference docs.
4. For one-save games, call `saveData` and `loadData`; for multi-save games, call `saveSlot(slotId)` and `loadSlot(slotId)`.
5. Let the SDK persist local data immediately.
6. For save menus, list local slots with `listSlotData` or the SDK's idiomatic equivalent and read `slotInfo` as preview/selection data.
7. Keep full playable progress in `data`; do not invent lower-level storage-route or internal-id examples.
8. Call `forceSyncData`, `forceSync(slotId)`, `syncDueSlots`, or `syncDue` from safe game moments. The SDK does not start a hidden background timer.
9. Use exported status constants/enums such as `PersistlyGameSaveStatus`, `PersistlySlotStatus`, and `PersistlySyncStatus`, not raw strings.
10. Treat conflicts as normal control flow and recover from the cloud conflict branch.

For signed-in cross-browser restore, the game owner's backend must store and return `accountId` plus `accountSessionToken`. For no-login games, short-lived transfer codes can move an existing anonymous account from Device A to Device B when Device A still has the account session. Anonymous localStorage saves cannot recover on another browser if those values were never stored outside the browser and no transfer code was created before the local session was lost.

Transfer-code rule: use `createTransferCode` on the device that already has the account session, then `attachWithTransferCode` on the new device. Do not invent username recovery, `playerRef` lookup, `externalAccountRef` lookup, persistent backup passwords, or `/profiles` routes.

Use account `accountData` for shared player data such as bundles, shared inventory, settings, and validated currency balances. Do not use client-written save data as the only authority for payment receipts, card data, purchase validation, competitive inventory, or leaderboard scores.
JavaScript account-data helpers include `saveAccountData`, `patchAccountData`, and local account-data inspection. Unity and Godot expose the same account-data path with idiomatic method names.

JavaScript, Unity, and Godot expose the same product model. Prefer each SDK's facade (`PersistlyGameSaves`) and keep method names idiomatic to the engine/language instead of exposing raw account/slot IDs in beginner docs.

AI rule: `PersistlyGameSaves` is the default SDK facade for game developers. The facade hides internal save ids and raw save-storage routes. Raw account/slot create/load/sync APIs are advanced runtime contract APIs.