AI integration rules

CURRENT SUPPORTED APIs
ThreeJSGames.storage
ThreeJSGames.leaderboards (Beta)
ThreeJSGames.player (Beta)
ThreeJSGames.multiplayer (Beta; Premium Creator games, authenticated players)

AVAILABLE
Cloud Storage — Storage SDK v1

BETA
Leaderboards — approved keys only
Player Identity — current public username, normalized avatar and Premium badge
Multiplayer — rooms, Quick Match, presence, bounded state/events, host state, reconnect, and optional 1v1 Elo

PLANNED / NOT AVAILABLE
Achievements

DO
- Use the official Storage SDK v1 for Storage-only games.
- Use SDK v4 at 3jsgames-sdk/v4/3jsgames.js for new integrations.
- Use ThreeJSGames.player.getProfile() for username, avatar ({ type, value }) and read-only isPremium. Use textContent for text and img.src for images, with 🎮 as the image-error fallback.
- 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.
- Treat Multiplayer host authority and host-reported outcomes as casual, not cheat-proof.

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 private account information.
- Modify an official SDK artifact.
- Supply user IDs, game IDs, Premium flags, channel names, host status, or ratings.
- Bypass the upload scanner.

Do not implement against planned features yet. Follow /docs/sdk/multiplayer for the exact Multiplayer Beta contract.

Integrate the existing erebo.si Leaderboards Beta SDK into this standalone HTML5 game.

1. Preserve the existing game architecture and standalone gameplay.
2. Vendor the unchanged official SDK v4 at 3jsgames-sdk/v4/3jsgames.js and load it with ./3jsgames-sdk/v4/3jsgames.js before the game script. Existing SDK v2/v3 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.