JavaScript Create Load Sync

Create once, then load and sync only by saveId.

This is the canonical public-client flow. The game creates a save record once, persists saveId locally, then uses create/load/sync responses as the canonical snapshot source.

Reference Example

Use this as the base integration pattern.

import { PersistlyClient, PersistlySyncStatus } from "@persistly/sdk-js";

const client = new PersistlyClient({
  runtimeKey: process.env.PERSISTLY_RUNTIME_KEY!,
});

const created = await client.createSave({
  externalUserId: "player-184",
  metadata: {
    characterName: "Ayla",
    slotLabel: "Mage"
  },
  state: {
    checkpoint: "vault",
    coins: 418
  }
});

const reloaded = await client.loadSave(created.saveId);

const result = await client.syncSave(created.saveId, {
  baseVersion: reloaded.version,
  metadata: reloaded.metadata,
  state: {
    checkpoint: "vault",
    coins: 612
  }
});

if (result.status === PersistlySyncStatus.Conflict) {
  console.error("Conflict. Canonical server save:", result.save);
}

Behavior

These runtime guarantees are what the SDK is preserving.

The JavaScript SDK is the current behavior reference for all other SDK tracks.

Create, load, and sync always return canonical save payloads from the server.

Conflict responses preserve the canonical server save so the game can decide how to recover.

The SDK validates payload-size limits before requests leave the client.