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.

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"></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