Cloud Storage

Status

Available

SDK version

1

Requires authentication

Yes, for cloud storage

Standalone behavior

Cloud storage unavailable; add a local fallback if needed

Install the official SDK

The canonical browser artifact is public/sdk/v1/3jsgames-storage.js. Download it unchanged and vendor it inside an uploaded game as 3jsgames-sdk/v1/storage.js.

<script src="./3jsgames-sdk/v1/storage.js"></script>

• Version: Storage SDK v1
• Official size: 10,390 bytes
• SHA-256: 92d7feb120e1361c6a21d6eb90112e7a4b79b4910c21fe892e8a00aafce16e5b

Public API

• ThreeJSGames.storage.get(key)
• ThreeJSGames.storage.set(key, value)
• ThreeJSGames.storage.delete(key)
• ThreeJSGames.storage.isAvailable()

Examples

Save

await ThreeJSGames.storage.set("savegame", {
  level: 4,
  coins: 120
});

Load

const save = await ThreeJSGames.storage.get("savegame");

Delete

await ThreeJSGames.storage.delete("savegame");

Check platform availability

if (ThreeJSGames.storage.isAvailable()) {
  // Platform integration is available.
}

isAvailable() reports whether the platform integration is available. It does not mean the player is authenticated; a storage call can still reject with AUTH_REQUIRED.

Handle stable error codes

try {
  await ThreeJSGames.storage.set("savegame", saveData);
} catch (error) {
  if (error.code === "AUTH_REQUIRED") {
    // Keep the local save and invite the player to sign in.
  } else if (error.code === "QUOTA_EXCEEDED") {
    // Reduce or remove stored data before retrying.
  } else {
    throw error;
  }
}

Check error.code; do not parse human-readable message strings. Stable public codes include: AUTH_REQUIRED, INVALID_GAME_CONTEXT, CONTEXT_EXPIRED, INVALID_PROTOCOL, UNSUPPORTED_VERSION, INVALID_REQUEST, INVALID_JSON, INVALID_KEY, VALUE_REQUIRED, VALUE_TOO_LARGE, KEY_LIMIT_EXCEEDED, QUOTA_EXCEEDED, GAME_NOT_AVAILABLE, RATE_LIMITED, STORAGE_UNAVAILABLE, REQUEST_TIMEOUT.

Limits and key rules

• Keys must match ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$: start with a letter or digit, then use letters, digits, period, underscore, colon, or hyphen.
• Maximum key length: 64 characters.
• Maximum individual JSON value: 32 KiB serialized.
• Maximum keys: 64 per player per game.
• Total quota: 256 KiB per player per game.
• Values must be JSON-compatible.

Authentication and scope

Cloud storage requires a player signed in to 3JSGames and follows that profile across devices for the same game. Authentication and game scoping are handled by the platform. In standalone play, cloud storage is unavailable; implement an explicit local fallback if the game needs one.