playdotfun

使用するタイミング

ユーザーがPlay.funとのゲーム連携や、Play.funからのデータ取得を必要としている場合は、いつでもこのスキルを使用してください。Play.funのさまざまなワークフローをユーザーに案内する場合にも、このスキルを使用できます。

使用方法

ユーザーからPlay.funとのゲーム連携を依頼された場合は、以下の連携ワークフローに必ず従ってください。手順を省略しないでください。各フェーズの進捗を追跡するためのタスクリストを作成してください。

連携ワークフロー

新規または既存のゲームをPlay.funと連携する場合は、以下のフェーズを順番に進めてください。各ステップのタスクを作成し、順次完了してください。

フェーズ 1：認証

認証が必要な操作を行う前に、認証情報が設定されていることを確認してください。

1. 認証ステータスを確認 — node skills/scripts/playfun-auth.js status を実行し、認証情報が存在するか確認します
2. 認証情報がない場合は設定 — 認証設定ガイドに従います。コールバックサーバーを起動し、ブラウザーから認証するようユーザーに案内してください
3. 認証情報が有効であることを確認 — test_connection MCP ツールを使用してアクセスを確認します。返されたユーザー ID を保存してください。これは、後で <meta name="x-ogp-key"> タグに設定する API キー です

認証情報が確認できるまで、フェーズ 2 に進まないでください。

フェーズ 2：ゲームの構築

4. ゲームを構築または変更 — ゲームコードを作成または更新します。この時点ではPlay.fun SDKとの連携を追加しないでください。まずゲーム本体を動作させてください。レイアウトにはセーフエリアのインセットを使用してください。背景とキャンバスはビューポート全体（100vw × 100vh）に表示し、ゲーム UI（HUD、ボタン、コントロール）はすべて、余白またはパディングに var(--ogp-safe-top-inset, 0px) と var(--ogp-safe-bottom-inset, 0px) を使用してください。キャンバスゲームの場合は、JS でインセットを読み取り、UI の描画位置を調整します。セーフエリアのレイアウトを参照してください
5. ゲームが単独で動作することをテスト — ブラウザーで開き、SDK なしでゲームプレイが正しく機能することを確認します（セーフエリア変数のデフォルト値は 0px です）

フェーズ 3：Play.fun へのゲーム登録

6. ゲーム名と説明を決定 — ユーザーに尋ねるか、楽しく内容が伝わる名前を考えます
7. ゲーム画像を準備 — 既存の画像を探すか、プレースホルダー画像を生成します。⚠️ 重要：画像の安全性ルールに必ず厳密に従ってください。従わない場合、クラッシュします。 概要：（1）画像ファイルをディスク上に用意または作成する、（2）./skills/scripts/image-to-base64.sh <image> --data-uri --file /tmp/game_image_b64.txt を実行する、（3）Read ツールでテキストファイルを読み取る、（4）文字列を register_game に渡す。標準出力に Base64 を絶対に出力しないでください。Read ツールでバイナリ画像ファイルを絶対に読み取らないでください
8. 公開 URL を取得するためにゲームをデプロイ — ゲームのホスティングが必要な場合は、GitHub Pages デプロイガイドを使用します。ゲーム URL は公開アクセス可能である必要があります
9. ゲームを登録 — MCP の register_game ツールに、name、description、gameUrl、platform、base64Image、およびチート対策の制限値を渡します（ゲームの種類に応じた制限値の推奨については、ベストプラクティスを参照してください）。返された id（ゲーム UUID）を保存してください。これは後で sdk.init({ gameId }) に設定する ゲーム ID です
10. 登録を確認 — MCP の get_my_games ツールを使用し、ユーザーのゲーム一覧にゲームが表示されることを確認します

有効な gameId が登録によって取得できるまで、フェーズ 4 に進まないでください。

フェーズ 4：Play.fun SDK を統合する

11. SDK の方式を選択する — ユーザーに尋ねるか、ニーズに応じて判断します：
    • ブラウザー SDK (リファレンス) — プロトタイプ、デモ、ゲームジャム向け。サーバー側の検証はありません
    • サーバー SDK (リファレンス) — トークン報酬とチート対策を備えた本番ゲーム向け
    • ハイブリッド (リファレンス) — ブラウザーウィジェットとサーバー検証の両方を使用（本番環境に推奨）
12. 実際の認証情報を使って SDK を追加する — 選択した SDK のリファレンスに従います。ブラウザー SDK を統合する場合：
    • メタタグを追加します：<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、score > 0 チェック（ブラウザー SDK スニペットを参照）
    • ゲーム ID を使って初期化します：sdk.init({ gameId: 'your-game-id' }) — これは register_game のレスポンスにある id フィールドであり、API キーではありません
13. スコア処理を接続する — ゲーム中に sdk.addPoints() を、ゲーム終了時に sdk.endGame() を（ブラウザー SDK の場合）、またはサーバー側の savePoints() と sdk.refreshPointsAndMultiplier() を（ハイブリッドの場合）統合します
14. SDK の統合をテストする — ゲームを開き、Play.fun ウィジェットが表示されることを確認し、1 ラウンドプレイして、ポイントが送信されたことを確認します

フェーズ 5：デプロイと検証

15. SDK 統合後に再デプロイする — 更新したコードをホスト済み URL にプッシュします
16. URL が変わった場合はゲーム登録を更新する — ゲーム URL が変わった場合は、MCP の update_game ツールを使用します
17. 最終確認 — 公開 URL でゲームをプレイし、ポイントが保存されることを確認して、MCP の get_game_leaderboard でリーダーボードを確認します
18. Playcoin のローンチ（任意） — launch_playcoin MCP ツールには Privy ウォレット認証が必要で、HMAC 認証情報では失敗します。代わりに、ユーザーには Play.fun ダッシュボードのゲームページからローンチするよう案内してください

クイックリファレンス

リソース	説明
API リファレンス	API エンドポイントの完全なリファレンス
API 認証	HMAC-SHA256 認証ガイド
SDK のベストプラクティス	SDK の選択とチート対策の設定
サーバー SDK リファレンス	サーバー側 SDK のリファレンス
ブラウザー SDK リファレンス	ブラウザー SDK のリファレンス
ハイブリッド SDK リファレンス	ブラウザーとサーバーを組み合わせたリファレンス
機能（連続記録と倍率）	組み込みのエンゲージメント機能
MCP クイックスタート	ゲームの登録と管理に使う MCP ツール
用語集	Play.fun の用語と概念
認証設定	認証情報の設定ガイド
GitHub Pages へのデプロイ	GitHub Pages を使った無料のゲームホスティング
ゲームのアップロード規則	必須フィールドと画像のガイドライン
サーバー SDK スニペット	コピーして使えるサーバーコードの例
ブラウザー SDK スニペット	コピーして使えるブラウザーコードの例