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.

• Check auth status — Run node skills/scripts/playfun-auth.js status to see if credentials exist

• Set up credentials if missing — Follow the Auth Setup guide. Start the callback server and instruct the user to authenticate via their browser

• 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

• 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

• Test the game works standalone — Open in browser and verify gameplay functions correctly without SDK

Phase 3: Register the Game on Play.fun

• Choose a game name and description — Ask the user or generate a fun, descriptive name

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

• 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

• 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

• 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

• 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)

• 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">&#x3C;/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

• 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)

• 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

• Re-deploy with SDK integration — Push updated code to the hosted URL

• Update game registration if URL changed — Use MCP update_game tool if the game URL changed

• Final verification — Play the game at its public URL, verify points save, check the leaderboard with MCP get_game_leaderboard

• 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