playdotfun（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

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

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

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

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)

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

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