playdotfun

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

当用户需要将游戏与Play.fun集成，或从Play.fun获取数据时，即可使用此技能。你也可以用它来引导用户完成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.

当用户要求你将游戏与Play.fun集成时，你必须遵循以下集成流程，不得跳过步骤。创建任务列表来跟踪每个阶段的进度。

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.

将新游戏或现有游戏与Play.fun集成时，请按顺序完成以下阶段。为每个步骤创建任务并依次完成。

Phase 1: Authentication

阶段1：身份验证

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.

在进行任何需要身份验证的操作前，先确认凭证已配置完成。

检查身份验证状态 — 运行
```
node skills/scripts/playfun-auth.js status
```
查看凭证是否存在
若缺少凭证则进行配置 — 遵循身份验证设置指南。启动回调服务器并指导用户通过浏览器完成身份验证
验证凭证有效性 — 使用
```
test_connection
```
MCP工具确认访问权限。保存返回的用户ID — 这是后续要放入
```
<meta name="x-ogp-key">
```
标签中的API密钥

在凭证验证通过前，不得进入阶段2。

Phase 2: Build the Game

阶段2：游戏开发

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

开发或修改游戏 — 创建或更新游戏代码。此时暂不添加任何Play.fun SDK集成 — 先确保核心游戏功能正常运行
测试游戏独立运行情况 — 在浏览器中打开游戏，验证无需SDK即可正常进行游戏

Phase 3: Register the Game on Play.fun

阶段3：在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.

确定游戏名称与描述 — 询问用户或生成一个有趣且描述性的名称
准备游戏图片 — 找到现有图片或生成占位图。⚠️ 重要提示：你必须严格遵循图片安全规则，否则会导致程序崩溃。 简化步骤：(1) 在磁盘上获取/创建图片文件，(2) 运行
```
./skills/scripts/image-to-base64.sh <image> --data-uri --file /tmp/game_image_b64.txt
```
，(3) 使用读取工具读取文本文件，(4) 将字符串传入
```
register_game
```
。切勿将base64内容输出到标准输出，切勿使用读取工具读取二进制图片文件。
部署游戏以获取公开URL — 若游戏需要托管，遵循GitHub Pages部署指南。游戏URL必须可公开访问
注册游戏 — 使用MCP工具
```
register_game
```
，传入参数：名称、描述、gameUrl、平台、base64Image及反作弊限制（根据游戏类型，参考最佳实践中的限制建议）。保存返回的**
```
id
```
（游戏UUID） — 这是后续要放入
sdk.init({ gameId })
中的游戏ID**
确认注册成功 — 使用MCP工具
```
get_my_games
```
验证游戏已出现在用户的游戏列表中

在获取到有效的

gameId

前，不得进入阶段4。

Phase 4: Integrate the Play.fun SDK

阶段4：集成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

选择SDK方案 — 询问用户或根据其需求决定：
- 浏览器SDK（参考文档）— 适用于原型、演示、游戏开发 jam。无需服务器端验证
- 服务器SDK（参考文档）— 适用于带有代币奖励和反作弊机制的生产级游戏
- 混合方案（参考文档）— 同时使用浏览器组件+服务器端验证（推荐用于生产环境）
添加带有真实凭证的SDK — 遵循所选SDK的参考文档。对于浏览器SDK集成：
- 添加meta标签：
```
<meta name="x-ogp-key" content="your-api-key" />
```
  — 值为创作者API密钥（来自控制台的用户UUID），而非gameId或gameKey
- 添加脚本：
```
<script src="https://sdk.play.fun"></script>
```
- 使用
```
OpenGameSDK
```
  类（而非PlayFunSDK）
- 使用防御性代码模式：
```
typeof
```
  检查、
```
sdkReady
```
  标志、
```
sdk && sdkReady
```
  校验、try/catch、分数>0检查（参考浏览器SDK代码片段）
- 使用游戏ID初始化：
```
sdk.init({ gameId: 'your-game-id' })
```
  — 此ID为
```
register_game
```
  响应中的
```
id
```
  字段，而非API密钥
对接计分功能 — 在游戏过程中集成
```
sdk.addPoints()
```
，在游戏结束时集成
```
sdk.endGame()
```
（浏览器SDK）；或在服务器端使用
```
savePoints()
```
+
```
sdk.refreshPointsAndMultiplier()
```
（混合方案）
测试SDK集成效果 — 打开游戏，验证Play.fun组件是否显示，进行一局游戏并确认分数已提交

Phase 5: Deploy and Verify

阶段5：部署与验证

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

重新部署集成SDK后的游戏 — 将更新后的代码推送到托管URL
若URL变更则更新游戏注册信息 — 若游戏URL发生变更，使用MCP工具
```
update_game
```
进行更新
最终验证 — 在公开URL上进行游戏，验证分数已保存，使用MCP工具
```
get_game_leaderboard
```
查看排行榜
Playcoin发行（可选） — MCP工具
```
launch_playcoin
```
需要Privy钱包身份验证，使用HMAC凭证会导致失败。请引导用户通过Play.fun控制台上的游戏页面进行发行操作

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

资源	描述
API参考文档	完整的API端点参考文档
API身份验证	HMAC-SHA256身份验证指南
SDK最佳实践	SDK选择与反作弊配置
服务器SDK参考文档	服务器端SDK参考文档
浏览器SDK参考文档	浏览器SDK参考文档
混合SDK参考文档	浏览器+服务器组合方案参考文档
功能特性（连续登录与倍数奖励）	内置的用户参与功能
MCP快速入门	用于游戏注册与管理的MCP工具
术语表	Play.fun相关术语与概念
身份验证设置	凭证配置指南
GitHub Pages部署	通过GitHub Pages进行免费游戏托管
游戏上传规则	必填字段与图片规范
服务器SDK代码片段	可直接复制使用的服务器端代码示例
浏览器SDK代码片段	可直接复制使用的浏览器端代码示例