playdotfun

When to use

How to use

Integration Workflow

Phase 1: Authentication

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

Phase 2: Build the Game

1. 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
2. Test the game works standalone — Open in browser and verify gameplay functions correctly without SDK

Phase 3: Register the Game on Play.fun

1. Choose a game name and description — Ask the user or generate a fun, descriptive name
2. 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.
3. 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
4. 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
5. Confirm registration — Use the MCP

   get_my_games

   tool to verify the game appears in the user's game list

gameId

Phase 4: Integrate the Play.fun SDK

1. 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)
2. 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
3. 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)
4. 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

1. Re-deploy with SDK integration — Push updated code to the hosted URL
2. Update game registration if URL changed — Use MCP

   update_game

   tool if the game URL changed
3. Final verification — Play the game at its public URL, verify points save, check the leaderboard with MCP

   get_game_leaderboard

4. 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