# 3JSGames creator documentation summary

Canonical Docs: https://www.3js.games/docs
Current SDK manifest: https://www.3js.games/sdk/latest.json
AI SDK integration instructions: https://www.3js.games/docs/ai-sdk.txt
Machine-readable SDK v3 API: https://www.3js.games/sdk/v3/api.json

## Recommended SDK
Platform SDK v3 is recommended for all new integrations.
Artifact: /sdk/v3/3jsgames.js
Uploaded-game path: 3jsgames-sdk/v3/3jsgames.js
SHA-256: 3ec794a26949b0da425af2f26f5ee0699d95b8f206666cba540b5a4eaba64b1a
Size: 22635 bytes
It provides Cloud Storage (Available), Leaderboards (Beta), and Player Identity (Beta). Achievements and Multiplayer are planned and have no public API.

## Current contract
Cloud Storage is available in the recommended Platform SDK v3. Storage SDK v1 remains supported for existing Storage-only integrations.
Public namespace: ThreeJSGames.storage
Methods: get(key), set(key, value), delete(key), isAvailable()
Authentication: required for cloud operations. isAvailable() does not prove authentication.
Scope: profile-bound, per game, cross-device for the same authenticated 3JSGames profile.
Standalone: cloud storage is unavailable unless the game implements a local fallback.

## Leaderboards Beta contract
Recommended artifact: /sdk/v3/3jsgames.js
Uploaded-game path: 3jsgames-sdk/v3/3jsgames.js
SHA-256: 3ec794a26949b0da425af2f26f5ee0699d95b8f206666cba540b5a4eaba64b1a
SDK v2 remains supported for existing Leaderboards integrations at /sdk/v2/3jsgames.js (3jsgames-sdk/v2/3jsgames.js; SHA-256 c8049a413c5ddbf23c92f615e97b60558917d35a9be3566dfa9a0046c038db06).
Public namespace: ThreeJSGames.leaderboards
Methods: submit(key, score), getTop(key, options?), getPersonal(key), isAvailable()
Keys: platform-approved per game; arbitrary calls do not create boards.
Scores: JavaScript safe integers; higher is better; one persistent personal best; equal and lower scores do not replace it.
Reads: Top is public; submit and personal require authentication.
Availability: isAvailable() does not prove authentication, key approval, or network availability.
Errors: branch on error.code, never message text. Stable codes are AUTH_REQUIRED, INVALID_GAME_CONTEXT, CONTEXT_EXPIRED, INVALID_KEY, INVALID_SCORE, INVALID_LIMIT, INVALID_REQUEST, LEADERBOARD_NOT_AVAILABLE, RATE_LIMITED, LEADERBOARD_UNAVAILABLE, and REQUEST_TIMEOUT.
Trust: browser-submitted scores are casual and unverified; do not use for prizes or high-stakes competition.

## Player Identity Beta contract
Recommended artifact: /sdk/v3/3jsgames.js
Uploaded-game path: 3jsgames-sdk/v3/3jsgames.js
SHA-256: 3ec794a26949b0da425af2f26f5ee0699d95b8f206666cba540b5a4eaba64b1a
Public namespace: ThreeJSGames.player
Method: getProfile()
Success shape: { username: string }
Username is public, globally unique, and mutable. It is presentation data, not authorization, a permanent ID, or a durable database key.
Signed out: AUTH_REQUIRED. Missing profile, service failure, bridge unavailable, or standalone: PLAYER_UNAVAILABLE. Timeout: REQUEST_TIMEOUT.
No arbitrary-player lookup, internal user ID, email, display name, avatar, token, provider, or private profile metadata is exposed.

## Limits
Key rule: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Key maximum: 64 characters
Individual value maximum: 32 KiB serialized JSON
Key count: 64 per player per game
Total quota: 256 KiB per player per game

## Historical supported SDK identity
Storage SDK v1 canonical file: public/sdk/v1/3jsgames-storage.js
Uploaded-game path: 3jsgames-sdk/v1/storage.js
SHA-256: 92d7feb120e1361c6a21d6eb90112e7a4b79b4910c21fe892e8a00aafce16e5b
All official SDK artifacts must remain unchanged.

## Safety rules
Do not connect uploaded games directly to Supabase. Do not ask for, invent, or send player/game IDs. Do not invent leaderboard endpoints. Do not access window.parent or implement raw postMessage transport. Use the official SDK, preserve standalone behavior, and do not bypass the upload scanner.

## Feature status
- Cloud Storage: available; /docs/sdk/cloud-storage
- Player: beta; /docs/sdk/player
- Leaderboards: beta; /docs/sdk/leaderboards
- Achievements: planned; /docs/sdk/achievements
- Multiplayer: planned; /docs/sdk/multiplayer

Features marked planned have no available API. Do not invent or implement their interfaces. Player Identity and Leaderboards are Beta, not Available.

## Pages
- /docs/getting-started
- /docs/game-requirements
- /docs/sdk
- /docs/sdk/cloud-storage
- /docs/sdk/leaderboards
- /docs/sdk/player
- /docs/guides/local-fallback
- /docs/ai
- /docs/ai/add-cloud-saves
- /docs/ai/diagnose-storage
- /docs/examples
- /docs/downloads
- /docs/features.json
- /sdk/latest.json
- /sdk/v3/api.json
- /docs/ai-sdk.txt