Discordでログイン
Discordでログイン

開発者向けガイド

AIエージェントに読ませる場合は https://waiwai.town/llms.txt をどうぞ（同じ内容のプレーンテキスト版です）。

このサイトに載せられるもの

わいわいタウンは、Webで遊べる自作ゲーム・アプリのポータルです。ジャンル・IPは問いません。

禁止：性的表現・違法コンテンツ（詳細な掲載基準は準備中です）。

サイト内プレイ（iframe埋め込み）の技術条件

サイト内でそのまま遊べる（サイト内プレイ）ようにするには、以下の条件を満たすWeb版のURLが必要です。

  • httpsで公開されたWeb版のURLがあること（自サイト・GitHub Pages・Cloudflare Pagesなど）
  • X-Frame-Options ヘッダーを送らないこと
  • CSPの frame-ancestors ディレクティブで わいわいタウン（https://waiwai.town）を許可しているか、そもそも設定していないこと
  • 判定は登録・更新のたびにサーバーが実URLへ自動アクセスして行います（タイムアウト5秒・リダイレクト3回まで追跡。最終URLがhttpsでない、または最初のURLとオリジンが変わるリダイレクトも不可）
  • itch.ioのゲームページは埋め込みできません（itch.io側が frame-ancestors で自ドメインのみを許可しているため）。ただしリンクとしての掲載は可能です
  • スマホでの表示・操作に対応していることを推奨します（レスポンシブ・タッチ操作）
  • 音声を自動再生しないこと、ページが非表示になったとき（pagehide・visibilitychange）にBGMを止めることを推奨します（他タブ・他ページに音が残り続ける事故が実際に起きています）

セーブデータの保全（わいわいSDK）

Safari等では、埋め込み中のゲーム自身のlocalStorageが保持されません。わいわいSDKを入れると、わいわいタウン側にセーブが代理保存され、大幅に消えにくくなります。さらにDiscordログイン中のプレイヤーは、セーブがわいわいタウンのサーバーにも自動同期され、別の端末・ブラウザでも続きから遊べます（クラウド同期は2026-08-06から稼働中。ゲーム側の追加実装は不要で、SDK導入済みなら自動で有効です）。

導入は2ステップです。①scriptタグを1行追加 ②保存・読込をSDK経由にする、という形です。

script src="https://waiwai.town/sdk.js" crossorigin="anonymous" を1行貼るだけの、HTMLの標準的な読み込みタグと同じ形です。

  • crossorigin="anonymous" は省略しない形を推奨します。Godot等のPWAビルドはService WorkerがCOEP（クロスオリジン分離）ヘッダを注入するため、この属性が無いとSW制御下（2回目以降の訪問）でsdk.jsが黙ってブロックされ、セーブ中継が動かなくなります（初回訪問だけ動くため検証をすり抜けやすい・2026-08-05に実例あり）。COEPを使わないページでも付けて問題ありません

await waiwai.save("progress", {stage: 3}); ／ const d = await waiwai.load("progress"); ／ await waiwai.delete("progress");

  • 保存できる値：JSONにできるもの（バイナリはbase64文字列にしてから）。上限は1キー100KB・1作品合計512KB・20キーまでです
  • わいわいタウンの外（公式サイト・itch等）で開かれたときは、自動でそのページ自身のlocalStorage保存に切り替わります＝同じビルドをそのまま配布できます
  • セーブには個人情報・パスワード等の秘密を含めない設計を想定しています
  • 既存セーブの移行：初回ロード時に旧localStorageキーを読み、あればwaiwai.save()で書き込んでから旧キーを消す、が推奨手順です
  • SDKに未対応の作品は、プレイ画面に「セーブは公式サイト推奨」という案内を自動表示します（ハンドシェイクが10秒届かず、かつ過去にも届いたことがない場合のみ）

共通ランキング基盤（わいわいSDK・ランキング）

わいわいタウンのSDKには、ゲーム内スコア・タイムを保存し、全国ランキングを出せる仕組みが入っています。導入はセーブ保全と同じ sdk.js を1回読み込むだけで、追加のscriptタグは不要です。

await waiwai.submitScore("board名", score, meta?) ／ const top = await waiwai.getTopScores("board名", n?) ／ const mine = await waiwai.getMyScore("board名")

  • board名は英数字・.・_・-のみ、1〜64字です（:は使えません）。ゲームモード・難易度ごとに分けて構いません
  • scoreは整数のみです。タイムアタック系はミリ秒の整数で送ってください（小数は使えません）
  • ボード（board名）は初回のsubmitScore呼び出しで自動的に作られます。事前登録は不要です。既定は「大きいほど上位」（降順）です。「小さいほど上位」（タイムアタック等）にしたい場合や、スコアの受理上限を決めたい場合は、開発者向けAPI（後述）で設定を変更してください
  • 自己ベストのみが保存されます（履歴は残りません）。改善したときだけサーバーに書き込まれ、応答のimprovedで分かります
  • わいわいタウンの外（公式サイト・itch等）で開かれたときは、自動でこのブラウザ内だけの自己ベスト保持（localStorage）に切り替わります＝同じビルドをそのまま配布できます（全国ランキングにはタウン内でのプレイのみ反映されます）
  • 表示名はサーバーが決めます。Discordログイン中はアカウント名、未ログイン（匿名プレイ）はmetaに{name:"..."}を含めるとその名前候補が使われます（不適切な語や空欄は自動的に「ナナシ」に置き換わります）
  • metaは任意のJSONで、文字列化後512バイトまでです。サーバーは中身を解釈しません（不正調査のための開発者向け監査材料という位置づけです）
  • ゲームバランスを変えたら、既存のboardは変えず新しいboard名（例：main → main_v2）を使うことを推奨します。異なるルールのスコアが同じランキングに混ざるのを防げます
  • 偽のスコア送信を完全に防ぐことはできません（クライアント配布物に秘密は置けないため）。基盤側の防御は受理上限・整合チェックまでで、ゲーム固有の整合性チェック（例：操作可能な最短クリア時間など）は基盤の対象外です。開発者側の対策として、受理上限の設定・metaへの検証材料の記録・不正スコアの削除（下記）・ユーザーからの通報を組み合わせてください

開発者向け管理API（要APIキー・本人の作品のみ）：

  • 一覧: curl -H "Authorization: Bearer <あなたのAPIキー>" https://waiwai.town/api/dev/scores/<作品のslug>/<ボード名>
  • 設定変更: curl -X PATCH -H "Authorization: Bearer <あなたのAPIキー>" -H "Content-Type: application/json" -d '{"sort":"asc"}' https://waiwai.town/api/dev/scores/<作品のslug>/<ボード名>（sortは"asc"／"desc"、max_scoreは整数またはnullで既定に戻せます）
  • 削除: curl -X DELETE -H "Authorization: Bearer <あなたのAPIキー>" https://waiwai.town/api/dev/scores/<作品のslug>/<ボード名>/<種別（discordまたはanon）>/<プレイヤーID>（不正なスコアの自己ベストを1件消します。BAN機能はありません＝再投稿は可能です）

AIエージェントからは、MCPツール get_top_scores（公開・APIキー不要）・list_score_boards（公開・APIキー不要）・list_scores_admin（要APIキー・本人）・delete_score（要APIキー・本人）でも同じ操作ができます。

埋め込みできない場合の掲載（リンク型）

サイト内プレイの条件を満たさない場合も、リンクとして掲載できます。対応しているリンク種別：App Store・Google Play・ブラウザで遊ぶ・Robloxで遊ぶ・Steam・itch.io・公式サイト・X（公式）・その他。

サムネイル画像の仕様

正方形 640×640px・2MBまで・PNGかJPEG。未設定の場合は頭文字のプレースホルダーで表示されます。

タイルは正方形で表示されるため正方形の画像を推奨します。長方形の画像を送っても受け付けますが、中央がクロップされて表示されます。

サムネ画像自体に作品タイトルの文字を入れ込むのは避けてください（タイトルはタイル側でホバー時に自動表示するため、画像に文字を焼き込むと二重表示・レイアウト崩れの原因になります）。

プレビュー動画の仕様（任意）

MP4（H.264）・10MBまで・5〜15秒・正方形または横長・音声トラック不要（サイトでは常にミュート再生）。設定すると、トップのタイル壁でマウスを乗せたとき（ホバー時）にサムネの上でデモ動画が自動再生されます（音声は常にミュート）。

マウスホバーが無い環境（スマホ・タブレット）では再生されず、通常どおりサムネイル表示のままです。

作品詳細ページにも、ネイティブの再生コントロール付きで表示されます。

形式はMP4（H.264）のみです（WebM・MOVは受け付けません）。ファイルサイズは10MBまでです。

動画ファイルのメタデータ（位置情報等）はサーバー側では除去しません。含めないようご注意ください。

掲載ガイド（セルフQA）

作品を登録する前に目を通していただきたいセルフチェックリストです（安全面以外は掲載を止めません。改善の提案として使ってください）。4つのグループ（あそべるか・こわれていないか・きもちよくあそべるか・みんなの場所として）とサムネイルの5箇条から成ります。

  • あそべるか
  • こわれていないか
  • きもちよくあそべるか
  • みんなの場所として

全文は https://waiwai.town/guide で確認できます（MCP経由では get_listing_guide でも同じ内容を取得できます）。

登録方法A：Webフォーム

Discordでログインし、「作品を登録する」（https://waiwai.town/submit）から登録します。ログインすればどなたでも登録できます。

NinjaDAOのホルダーロール（CNP／CNN／Musubi）または明鏡の対象ロールをお持ちの方は、登録するとそのまま公開されます。

それ以外の方は、登録後にAI審査があります（内容確認＋実プレイ。目安1〜2日）。審査結果は通知（ベルアイコン）でお知らせします。

登録方法B：AIエージェント（MCP）

わいわいタウンはMCP（Model Context Protocol）に対応しています。AIエージェントに登録作業を任せられます。

https://waiwai.town/my でAPIキーを発行し、お使いのAIエージェントに次のコマンドを伝えてください：

claude mcp add --transport http waiwai-town https://waiwai.town/mcp --header "Authorization: Bearer <あなたのAPIキー>"

このページ（または /llms.txt）のURLをAIエージェントに渡し、「わいわいタウンに登録して」と頼めば、以下のツールを使って登録を進められます。

  • search_apps：公開中の作品を検索する
  • get_app：slugで作品詳細を取得する
  • list_my_apps：自分の作品一覧を見る（非表示含む・要APIキー）
  • submit_app：作品を登録する（要APIキーのみ・登録権限は不要）。NinjaDAO/明鏡ロールが無い場合は応答が review:"pending" になり、公開前にAI審査があります
  • update_app：自分の作品を更新する（要APIキー＋本人）。**全項目の置き換え**です（部分更新ではありません）。省略した任意項目（説明・あそびかた・リンク等）は空に戻るため、一部だけ直すときは先に get_app で現在値を取り、変えない項目もそのまま含めて送ってください（content のみ例外＝省略時は据え置き）
  • submit_app / update_app には how_to_play（あそびかた・操作方法・任意・2000字以内）も渡せます。設定すると詳細ページに専用の欄が表示されます（REST APIも同フィールドに対応）
  • upload_thumb_url：サムネイル画像のアップロード先URL（15分有効・PUT）を発行する（要APIキー＋本人）。**推奨経路**。画像そのものをこのツールの引数として送るのではなく、応答で返る upload_url へファイルをPUTしてください。例：curl -T thumb.png (応答のupload_url)（応答の sha256 と手元の shasum -a 256 thumb.png を比較して破損の有無を確認すること。base64での送信は受け付けません）
  • upload_thumb：サムネイル画像をbase64でアップロードする（要APIキー＋本人）。sha256（デコード前提のバイト列に対するSHA-256・64桁hex）が必須で、不一致なら保存されません。AIエージェント経由のbase64送信はサイズに関わらずデータが破損することがあるため、可能な限り upload_thumb_url を使ってください。
  • upload_preview_video：プレビュー動画のアップロード先URL（15分有効・PUT）を発行する（要APIキー＋本人）。動画そのものをこのツールの引数として送るのではなく、応答で返る upload_url へファイルをPUTしてください。例：curl -T video.mp4 (応答のupload_url)（応答の sha256 と手元の shasum -a 256 video.mp4 を比較して破損の有無を確認すること。base64での送信は受け付けません）
  • upload_promo_video：宣伝用ショート動画のアップロード先URL（15分有効・PUT）を発行する（要APIキー＋本人）。登録＝公式SNS宣伝利用への許諾。agree_promo_terms: true 必須。MP4のみ・30MBまで・1作品3本まで。プレビュー動画とは別枠です。
  • reuse_preview_as_promo：すでに登録済みのプレビュー動画を、宣伝用ショート動画としても登録する（要APIキー＋本人）。agree_promo_terms: true 必須。動画を作り直さずに宣伝枠へ出したいときに使う。複製が作られるため、もとのプレビュー動画を差し替え・削除しても、この複製は自動では入れ替わらない
  • list_my_promo_videos：自分の作品の宣伝動画一覧（要APIキー＋本人）
  • delete_promo_video：宣伝動画を取り下げる（要APIキー＋本人・id指定）。削除＝以後の新規利用停止

サムネ・動画とも署名URL方式（upload_thumb_url・upload_preview_video・upload_promo_video）を推奨します。base64はsha256必須・小さい画像のみを想定した経路です。curlが使える環境ではREST（次項）が最速です。

※作品の削除はWeb画面（マイページ）からのみ行えます。AIエージェントからは削除できません。

宣伝用ショート動画（公式SNS用）

作品のプレビュー動画（タイルホバー用）とは別に、公式SNS（TikTok・Instagram・YouTube Shorts等）での宣伝に使う素材を登録できます。

推奨：MP4（H.264）・30MBまで・縦型（9:16）または正方形・15〜60秒・音声トラック無し（SNS投稿のBGMは運営側で付けます）

許諾：登録行為そのものが宣伝利用への同意になります。文言（版 v2）：宣伝用動画枠に登録すると、わいわいタウンの公式SNS（TikTok／Instagram／YouTube等）やブログ等で、この動画を使って作品と本サイトを紹介します。登録は任意で、登録された動画をすべて紹介するとお約束するものではありません。 ・動画の著作権はつくり手のものです。無償・非独占の利用許諾であり、著作権が運営者に移ることはありません。 ・紹介のために、長さの調整・静止画の切り出し（サムネイル用）・ロゴやテロップの付加・BGMの付加を行うことがあります（作品の内容そのものは変えません）。作品名とお名前は必ず表示します。 ・SNSへ投稿するため、各SNSの規約にもとづく利用許諾が、そのSNSの運営会社にも生じます。 ・動画に含まれる素材（映像・音楽・第三者のIP等）について、公開・紹介に使える権利をお持ちであることをご確認ください。音声トラックは付けずにご登録ください。 ・いつでも取り下げできます。取り下げ後は新しい投稿には使いません。すでに投稿済みのものは削除をお約束することまではできませんが、ご希望があればできるかぎり削除し、権利上の問題やつくり手の方の不利益がある場合は必ず削除します。 詳しくは利用規約第7条の2をご覧ください。

Web：マイページの作品カード内「宣伝動画」節から登録・削除できます。

MCP：upload_promo_video（agree_promo_terms:true必須）→ 返る upload_url へ PUT。list_my_promo_videos・delete_promo_video。

すでにプレビュー動画を登録している作品なら、reuse_preview_as_promo（agree_promo_terms:true必須）でそれを宣伝枠へ流用できます（Webでは /my の宣伝動画節にチェックがあります）。アップロードし直す必要はありません。

REST：curl -X POST -H "Authorization: Bearer <あなたのAPIキー>" -H "Content-Type: application/json" -d '{"agree_promo_terms":true}' https://waiwai.town/api/v1/apps/<作品のslug>/promo-upload-token で署名URLを取得し、返るURLへ PUT。

取り下げ＝いつでも削除可。削除した動画は以後の新規投稿には使われません（すでに投稿済みのものは残ります）。

新しいツールが見えないとき（ツール一覧のキャッシュ）

AIエージェントの多くは、接続した時点のツール一覧を保持します。運営側でツールを追加した直後は、すでに開いているセッションからは新しいツールが見えず、呼び出せないことがあります。サーバー側が正しく公開できていても起きる、クライアント側の仕様です。

現在のツールは全34本です（APIキーなしで見えるのは9本＝search_apps・get_app・get_save_sdk_guide・get_terms・get_privacy・get_listing_guide・submit_inquiry・get_top_scores・list_score_boards）。手元のツール数がこれより少なければ、一覧が古いと判断してください。

対処は2つあります。

① セッションを開き直す（いちばん簡単）。再接続のときに最新のツール一覧を取り直します。

② 開き直さずに使う：MCPエンドポイントへ直接POSTする。どのツールでも同じ形で呼べます。

  • 一覧の確認: curl -X POST https://waiwai.town/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "Authorization: Bearer <あなたのAPIキー>" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  • 呼び出し: 同じ形で、bodyを {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ツール名","arguments":{}}} に差し替える

なおわいわいタウンのMCPはステートレスなJSON応答です（GET https://waiwai.town/mcp は405）。サーバーから notifications/tools/list_changed を送る仕組みはないため、一覧の更新はクライアント側の再接続に依存します。

サムネ・動画のアップロード（REST API・最速）

APIキーがあれば、MCPを経由せずHTTPのPUT 1回でサムネ・プレビュー動画を登録・差し替えできます（curl 1発。いちばん速い経路です）。

  • サムネ: curl -T thumb.png -H "Authorization: Bearer <あなたのAPIキー>" https://waiwai.town/api/v1/apps/<作品のslug>/thumb
  • 動画（プレビュー）: curl -T video.mp4 -H "Authorization: Bearer <あなたのAPIキー>" https://waiwai.town/api/v1/apps/<作品のslug>/video
  • 宣伝動画の署名URL: curl -X POST -H "Authorization: Bearer <あなたのAPIキー>" -H "Content-Type: application/json" -d '{"agree_promo_terms":true}' https://waiwai.town/api/v1/apps/<作品のslug>/promo-upload-token
  • 削除（サムネ・プレビュー）: 同URLへ -X DELETE（ボディ不要）

画像はPNG/JPEG・2MBまで、プレビュー動画はMP4のみ・10MBまで、宣伝動画はMP4のみ・30MBまで。応答の sha256 を手元の shasum -a 256 と比較して破損の有無を確認してください。

要APIキー＋本人の作品。base64での送信は受け付けません。

プロフィール・お気に入り（MCP・登録権限は不要）

https://waiwai.town/my でAPIキーを発行すれば、登録権限（作品を登録できる権限）がなくても、以下のツールでプロフィールとお気に入りを操作できます。

  • update_profile：自分のSNSアカウント（X・YouTube・Instagram・TikTok・Threads・サイトURL）を設定・解除する（要APIキー）。指定した欄だけを更新する部分更新で、各欄に空文字を送るとその欄だけ解除。作品ページの作者欄・シェア文面の@メンションに使われます
  • add_favorite：作品をお気に入りに追加する（要APIキー・冪等・二度呼んでも1件のまま）
  • remove_favorite：作品をお気に入りから外す（要APIキー・冪等）
  • list_favorites：自分のお気に入り一覧を取得する（要APIキー・非公開＝本人にしか見えません）

お気に入りはランキング・番付には一切影響しません。

お知らせ（MCP通知）

レビュー・改善要望・審査結果の通知は、https://waiwai.town/notices（ベルアイコン）に加え、MCP接続時にも確認できます。

  • list_notices：自分への通知一覧を取得する（要APIキー）。引数 unread_only:true で未読のみに絞れます。読んでも既読にはなりません（何度でも確認できます）
  • mark_notices_read：自分への通知をすべて既読にする（要APIキー）

未読が1件以上あるときは、initialize応答のinstructionsに件数が案内されます（対応クライアントのみ表示）。

submit_app・update_app・list_my_appsの応答にも、いつでも unread_notices（未読件数）が同梱されます。

問い合わせ・要望（MCP／APIキー不要）

わいわいタウンへの問い合わせ・要望は、同じMCPエンドポイント（https://waiwai.town/mcp）のツール submit_inquiry で送れます。

APIキーは不要です（キー付きで接続すると、送信者として記録されます）。

回答は公開のQA（https://waiwai.town/qa）と更新履歴（https://waiwai.town/changelog）で行います。個別の返信は原則ありません。

機械可読なQA一覧: https://waiwai.town/qa.txt ／ 人間向けフォーム: https://waiwai.town/contact ／ 取り扱い: https://waiwai.town/privacy ／ 利用規約: https://waiwai.town/terms

上限・制限

1人あたり公開中の作品は30件までです（非表示にすると枠が空きます）。

登録は1時間に5件・1日に10件までです。