playdotfun

When to use

Use this skill whenever users need to integrate a game with Play.fun or fetch data from Play.fun. You can also use this skill to help guide users through different workflows of Play.fun.

How to use

When a user asks you to integrate a game with Play.fun, you MUST follow the integration workflow below. Do not skip steps. Create a task list to track progress through each phase.

Integration Workflow

When integrating a game (new or existing) with Play.fun, follow these phases in order. Create tasks for each step and complete them sequentially.

Phase 1: Authentication

Before any authenticated operation, verify credentials are set up.

1. Check auth status — Run node skills/scripts/playfun-auth.js status to see if credentials exist
2. Set up credentials if missing — Follow the Auth Setup guide. Start the callback server and instruct the user to authenticate via their browser
3. Verify credentials work — Use the test_connection MCP tool to confirm access. Save the returned user ID — this is the API key that goes in the <meta name="x-ogp-key"> tag later

Do NOT proceed to Phase 2 until credentials are verified.

Phase 2: Build the Game

4. Build or modify the game — Create/update the game code. Do NOT add any Play.fun SDK integration yet — get the core game working first. Use safe area insets in your layout: backgrounds and canvas should fill the full viewport (100vw × 100vh), while all game UI (HUD, buttons, controls) must use var(--ogp-safe-top-inset, 0px) and var(--ogp-safe-bottom-inset, 0px) for margin/padding. For canvas games, read the insets via JS and offset UI drawing. See Safe Area Layout
5. Test the game works standalone — Open in browser and verify gameplay functions correctly without SDK (safe area variables fall back to 0px)

Phase 3: Register the Game on Play.fun

6. Choose a game name and description — Ask the user or generate a fun, descriptive name
7. Prepare a game image — Find an existing image or generate a placeholder. ⚠️ CRITICAL: You MUST follow the Image Safety Rules exactly or you will crash. The short version: (1) get/create an image file on disk, (2) run ./skills/scripts/image-to-base64.sh <image> --data-uri --file /tmp/game_image_b64.txt, (3) Read the text file with the Read tool, (4) pass the string to register_game. NEVER output base64 to stdout. NEVER read binary image files with the Read tool.
8. Deploy the game to get a public URL — If the game needs hosting, use the GitHub Pages Deploy guide. The game URL must be publicly accessible
9. Register the game — Use the MCP register_game tool with: name, description, gameUrl, platform, base64Image, and anti-cheat limits (see Best Practices for limit recommendations based on game type). Save the returned id (game UUID) — this is the game ID that goes in sdk.init({ gameId }) later
10. Confirm registration — Use the MCP get_my_games tool to verify the game appears in the user's game list

Do NOT proceed to Phase 4 until you have a valid gameId from registration.

Phase 4: Integrate the Play.fun SDK

11. Choose SDK approach — Ask the user or decide based on their needs:
    • Browser SDK (Reference) — For prototypes, demos, game jams. No server-side validation
    • Server SDK (Reference) — For production games with token rewards and anti-cheat
    • Hybrid (Reference) — Both Browser widget + Server validation (recommended for production)
12. Add the SDK with real credentials — Follow the chosen SDK reference. For Browser SDK integration:
    • Add meta tag: <meta name="x-ogp-key" content="your-api-key" /> — value is the creator API key (user UUID from dashboard), NOT the gameId or gameKey
    • Add script: <script src="https://sdk.play.fun"></script>
    • Use OpenGameSDK class (NOT PlayFunSDK)
    • Use defensive patterns: typeof guard, sdkReady flag, sdk && sdkReady checks, try/catch, score > 0 check (see Browser SDK Snippets)
    • Init with game ID: sdk.init({ gameId: 'your-game-id' }) — this is the id field from the register_game response, NOT the API key
13. Wire up scoring — Integrate sdk.addPoints() during gameplay and sdk.endGame() at game end (for Browser SDK) or server-side savePoints() + sdk.refreshPointsAndMultiplier() (for Hybrid)
14. Test SDK integration — Open the game, verify the Play.fun widget appears, play a round, and confirm points are submitted

Phase 5: Deploy and Verify

15. Re-deploy with SDK integration — Push updated code to the hosted URL
16. Update game registration if URL changed — Use MCP update_game tool if the game URL changed
17. Final verification — Play the game at its public URL, verify points save, check the leaderboard with MCP get_game_leaderboard
18. Playcoin launch (optional) — The launch_playcoin MCP tool requires Privy wallet auth and will fail with HMAC credentials. Direct the user to launch via their game page on the Play.fun dashboard instead

Quick Reference

Resource	Description
API Reference	Complete API endpoint reference
API Authentication	HMAC-SHA256 authentication guide
SDK Best Practices	SDK selection and anti-cheat configuration
Server SDK Reference	Server-side SDK reference
Browser SDK Reference	Browser SDK reference
Hybrid SDK Reference	Browser + Server combined reference
Features (Streaks & Multipliers)	Built-in engagement features
MCP Quickstart	MCP tools for game registration and management
Glossary	Play.fun terms and concepts
Auth Setup	Credential setup guide
GitHub Pages Deploy	Free game hosting via GitHub Pages
Game Upload Rules	Required fields and image guidelines
Server SDK Snippets	Copy-paste server code examples
Browser SDK Snippets	Copy-paste browser code examples