AI integration rules

CURRENT SUPPORTED APIs
ThreeJSGames.storage
ThreeJSGames.leaderboards (Beta)

AVAILABLE
Cloud Storage — Storage SDK v1

BETA
Leaderboards — SDK v2, approved keys only

PLANNED / NOT AVAILABLE
Achievements
Multiplayer

DO
- Use the official Storage SDK v1 for Storage-only games.
- Use SDK v3 at 3jsgames-sdk/v3/3jsgames.js for new integrations.
- Use only ThreeJSGames.player.getProfile() for the current public username.
- Treat username as mutable presentation data, never authorization or a permanent ID.
- Use ThreeJSGames.leaderboards only with platform-approved keys.
- Preserve standalone game behavior where practical.
- Handle stable error.code values, not message text.
- Keep data within documented limits.
- Treat leaderboard scores as casual and unverified against cheating.

DO NOT
- Connect the game directly to Supabase.
- Ask for, invent, or send a user ID or game ID.
- Access window.parent manually.
- Implement custom raw postMessage communication.
- Invent leaderboard API endpoints.
- Request arbitrary players, internal user IDs, email, display names, or avatars.
- Modify an official SDK artifact.
- Invent APIs for planned features.
- Bypass the upload scanner.

Do not implement against planned features yet.

Integrate the existing 3JSGames Leaderboards Beta SDK into this standalone HTML5 game.

1. Preserve the existing game architecture and standalone gameplay.
2. Vendor the unchanged official SDK v3 at 3jsgames-sdk/v3/3jsgames.js and load it with ./3jsgames-sdk/v3/3jsgames.js before the game script. Existing SDK v2 integrations remain supported.
3. Use only ThreeJSGames.leaderboards.submit(key, score), getTop(key, { limit }), getPersonal(key), and isAvailable().
4. Use only this platform-approved leaderboard key: global. Do not create or guess keys.
5. Submit the final JavaScript safe-integer score once at game over. Higher scores are better and the platform keeps one personal best.
6. Show explicit loading, empty, unavailable, signed-out, failure, and retry states. A failed submission must not discard or crash the game result.
7. Treat AUTH_REQUIRED as a sign-in state; public getTop reads may still work. Branch on error.code, never message text.
8. Do not call Supabase or private platform endpoints, access window.parent, write raw postMessage transport, send player/game IDs, modify the SDK, or add credentials.
9. Render public player fields safely and do not treat browser-submitted scores as cheat-proof.
10. Test standalone behavior and the uploaded-game SDK/iframe bridge path.