API リファレンス

失敗すると、error（英語の説明文）か code（機械で読める識別子）と params のどちらかを持つ JSON が返ります。details が付くこともあります。

{ "error": "API token is missing the games:write scope." }
{ "code": "build.tooManyFiles", "params": { "limit": 2000 } }

対象ゲームを絞ったトークンを他のゲームへ向けたときは、存在を漏らさないために 403 ではなく 404 になります。

curl -X POST "https://gamerush.jp/api/games" \
  -H "Authorization: Bearer $GRUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "ねこジャンプ",
    "description": "タップで跳ぶだけのショートゲーム",
    "visibility": "public",
    "streamingPolicy": "allowed",
    "acceptTerms": true,
    "confirmAssetRights": true,
    "declareAllAges": true
  }'

応答は { game, mediaUploads } です。作成には冪等キーが無いので、失敗しても機械的に再試行しないでください。応答が失われた場合は GET /api/games で作られたかを確かめてからやり直します。

トークンでゲームを作るスクリプトや CI も、visibility に public / unlisted を指定するときは declareAllAges: true を送る必要があります。無ければ 403 になり、ゲームは作られません。private で作る要求は declareAllAges が無くても作れます（confirmAssetRights: true はどちらでも必須です）。

対象ゲームを絞ったトークンではゲームを作れません（まだ無いゲームは対象に入れられないため）。

PATCH は送ったフィールドだけを変えます。Studio の保存ボタンと同じ処理を通るので、審査やホールドの扱いも画面と同じです。

curl -X PATCH "https://gamerush.jp/api/games/$GAME_ID" \
  -H "Authorization: Bearer $GRUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "streamingPolicy": "conditional",
    "streamingPolicyNote": "収益化した配信ではクレジットを表示してください",
    "visibility": "unlisted",
    "declareAllAges": true
  }'

実況ポリシーの意味と、プレイヤーにどう見えるかは ゲーム実況ポリシー にあります。officialFeatureOptOut も PATCH で切り替えられ、真偽値でなければ 400 になります。sourceUrl に null か空文字を送ると消えます。

全年齢の申告（declareAllAges）の記録が無いゲームは、PATCH で declareAllAges: true を送ると申告を記録できます。公開設定とは関係なく、private のままでも送れます。記録が無いゲームを private から public / unlisted へ変えるときは必須です（公開設定と審査）。申告は一度記録したら変わらず、記録済みのゲームに送っても何も起きません。公開設定を上げない要求では、ほかのトークンや別の要求が同時に申告していても失敗せず、同じ要求のほかの変更もそのまま保存されます。private から上げる要求では、申告は公開設定の変更と一緒に保存され、別の要求が先に申告していたときは公開設定も変えずに 409 review.stateChanged になります。false を送っても記録は消えず、何も起きません。真偽値でなければ 400 になります。

streamingPolicy に表に無い値（"Allowed" のような打ち間違いを含む）を送ると、エラーにはならず unspecified として保存されます。title / description / howToPlay / streamingPolicyNote は上限を超えた分が切り詰められます。description / howToPlay / streamingPolicyNote の改行は LF に揃い、制御文字（タブを含む）は空白に、行末の空白は削られます。応答の game で保存された値を確かめてください。

title・description・howToPlay は作品の既定の文面です。これとは別に、言語ごとの訳を POST と PATCH の localizations で書けます。プレイヤーの表示言語の訳があればそれを、無い言語と空の項目には既定の文面を出します。

curl -X PATCH "https://gamerush.jp/api/games/$GAME_ID" \
  -H "Authorization: Bearer $GRUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "localizations": {
      "en": { "title": "Cat Jump", "howToPlay": "Tap to jump." },
      "ko": null
    }
  }'

応答と GET の localizations は、{ "en": { "title": "...", "description": "...", "how_to_play": "..." } } の形で、保存されている訳だけが入ります。遊び方のキーは how_to_play です。既定の文面と同じ訳は保存されないので、title と同じ文字列を en の title に送ると、en の title は消えます。

訳は今の値に重ねて保存します。読んでから保存するまでの間に、Studio やほかのトークンが同じゲームの訳か sourceLocale を変えていたときは、保存せずに 409 localizations.changed を返します。GET /api/games/:id で最新の訳を読んでからやり直してください。

sourceLocale は、title・description・howToPlay を書いた言語です。値は localizations のキーと同じく ja / en / ko / zh-Hans / zh-Hant / id / fil / vi / th のどれかを、この綴りのまま送ります。null は未設定です。ほかの値（en-US・zh-hans など）は 400 です。POST で省略すると未設定、PATCH で省略すると今の値のまま、PATCH で null を送ると未設定に戻ります。localizations を送らない PATCH で今と同じ値を送ったときは、省略したときと同じです（毎回送っても、ほかの変更の保存には影響しません）。GET と応答の source_locale で今の値を確かめられます（未設定は null）。

指定したゲームでは、この言語の閲覧者に既定の文面を出し、ゲームの紹介ページはこの言語の版で検索に載ります。英語で書いたゲームは sourceLocale を en にしてください。未設定のゲーム（sourceLocale を送らずに作ったゲームを含む）は、既定の文面を日本語の版として扱い、ja を含むどの言語の訳も書けて、閲覧者の言語の訳があればそれを出します。

sourceLocale を指定したゲームは、その言語の訳を持てません。保存した後の localizations に sourceLocale の言語の訳が残る要求は、何も保存せずに 400 localizations.sourceLocale を返します。未設定から指定するときと、別の言語に変えるときに、その言語の訳が残っているときも同じです。既定と同じ文面か空の項目だけを送った言語は、正規化で落ちて残らないので通ります。その言語の訳を消す null は送れます。

既定の文面と訳を入れ替えるときは、1回の PATCH に新しい sourceLocale・その言語の既定の文面・新しい言語の訳を消す null・前の言語の文面を訳として送ります。既定の文面は3項目（title・description・howToPlay）をすべて送ってください。送らなかった項目は前の言語の文面のまま既定に残り、新しい言語のその項目の訳は null で消えます。前の言語の訳にも、3項目をすべて送ります。下の例は、日本語で書いて英語の訳を持つゲームを、英語の既定の文面と日本語の訳に入れ替えます。

curl -X PATCH "https://gamerush.jp/api/games/$GAME_ID" \
  -H "Authorization: Bearer $GRUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceLocale": "en",
    "title": "Cat Jump",
    "description": "Tap to jump over the walls.",
    "howToPlay": "Tap anywhere to jump.",
    "localizations": {
      "en": null,
      "ja": {
        "title": "ねこジャンプ",
        "description": "タップで壁を跳び越える。",
        "howToPlay": "画面のどこかをタップして跳ぶ。"
      }
    }
  }'

• private への変更はすぐに反映され、審査待ちがあれば取り消されます。
• unlisted への変更は、審査を経ずにすぐに反映されます。審査待ちがあれば取り消されます。
• public への変更は、最新ビルドが審査済みならすぐに反映されます。そうでなければ requested_visibility に希望が入り、review_status が pending になります。visibility は、unlisted のゲームなら unlisted のまま、承認済みのビルドを配信している public のゲームなら public のまま、それ以外は private のままです。
• public のゲームが配信するのは、審査で承認されたビルドです。新しいビルドが審査を待つ間と差し戻された後も、承認済みのビルドの配信が続きます。
• ビルドがまだ無いゲームは public にも unlisted にもできません（409 review.buildRequired）。
• 素材の権利をまだ確認していないゲームを公開へ変えるときは、confirmAssetRights: true を一緒に送ります。無ければ 403 rights.confirmRequired になります。
• 全年齢の申告の記録が無いゲームを private から public / unlisted へ変えるとき（公開の審査の申請を含む）は、declareAllAges: true を一緒に送ります。無ければ 403 ageRating.declarationRequired になり、同じ要求のほかの変更も保存されません。認証済みクリエイターと管理者、トークンからの変更も同じです。public と unlisted の間の変更と、private への変更では求めません。
• ホールド中のゲームは公開設定を変えられません（403 hold.locked）。
• ホールド中のゲームで description か howToPlay（どちらかの訳を含む）の内容を変えると、一般公開の審査に積まれます。
• 審査待ち（review_status が pending）のゲームで title・description・howToPlay・それらの訳・サムネイル・sourceUrl の内容を変えると、運営は新しい内容で審査し直します。審査の順番は、変えた時点で申請したものとして後ろへ回ります。
• 変更の途中で審査の状態が変わったときは 409 review.stateChanged になります。最新の状態を読んでからやり直してください。

審査を飛ばせるのは、オーナー本人が運営の認めた認証済みクリエイターか管理者のときだけです。その場合はトークンからでも Studio と同じく即時に反映されます。共同制作者の立場では審査を飛ばせません。認証済みクリエイターの場合、運営が最後に差し戻したゲームは審査に回ります。全年齢の申告の記録が無いゲームの申請も、審査を飛ばさずに審査に回ります。

• engine は unity / godot / phaser / web のどれかです。
• ルートに index.html が要ります。HTML は圧縮せずに送ってください。
• ファイル数は 2000 まで、合計は 50MB までです（目安は 15MB 以下で、30MB 以上は危険です）。size はそのまま送るバイト数を書きます。
• 使えるファイルの種類は Studio からのアップロードと同じです。ソースマップ（.js.map）は含めないでください。
• Unity の Build/x.wasm.br のように、書き出した時点で .br / .gz が付いたファイルはその名前のまま送ります。自分で gzip したファイルを送るときは、元の名前の path に "encoding": "gzip" を添え、size は圧縮後の大きさにします。
• 最上位の grush.json はランキングの定義として読みます（書式は SDK ガイドのランキング）。トークンに leaderboards:write が無ければ 403 です。grush.json は 64KB までで、圧縮しないか "encoding": "gzip" で送ります。"encoding": "br" と、圧縮せずに送る 64KB 超のファイルは 400 です。gzip で送ったものの大きさは展開してから確かめ、64KB を超えれば complete が 422 を返します。

Studio の画面から Unity を選んで上げたときは、GameRush がプレイヤーを組み立ててローディングバーと先読みを付けます。API から上げたビルドは、送った index.html がそのまま使われます。

• uploadUrls[].headers に入っているヘッダーは、そのまま付けて送ってください（いまは If-None-Match: * です）。
• 同じファイルは1度しか書けません。2度目は 412 になるので、送信済みとして扱って構いません。途中で止まったときは、残りのファイルだけ送り直せます。
• url の期限は 1 時間です。

complete は、送ったファイルの大きさ・中身の形式・HTML の内容を検査してから、ゲームの最新ビルドに切り替えます。

grush.json を含むビルドの 200 の応答には leaderboards: { applied, unchanged, failed } が付きます。applied は作成か更新をした key、unchanged は同じ内容で何も書かなかった key です。検査の後に投稿が割り込むなどで書けなかった定義は、ビルドを最新にしたまま failed: [{ key, code }] に載ります。grush.json に書かなかった key の枠は、消えも止まりもしません。public のゲームで審査を待つビルドは、grush.json の検査だけを complete で行い、定義は審査で承認されて配信される時点で反映します。このときの応答には leaderboards の代わりに leaderboardsDeferred: true が付きます。

既に ready になったビルドへ complete をもう一度呼んで 400・409・422 が返ったときは、ビルドは ready のまま残り、配信も続きます。失敗扱いにも削除にもならないので、作成からやり直す必要はありません。

public のゲームに審査前のビルドを完了させると、ゲームは public のまま、新しいビルドが審査に積まれます（review_status が pending）。審査の間は前に承認されたビルドの配信が続き、承認されると新しいビルドに差し替わります。差し戻されたときは、新しいビルドは配信されず、承認済みのビルドの配信が続きます。新しいビルドは Studio の試遊で確かめられます。オーナー本人が運営の認めた認証済みクリエイターか管理者なら、審査を経ずにすぐ差し替わります。unlisted のゲームは審査を経ずに、unlisted のままビルドが差し替わります。

ビルドの作成には冪等キーが無いので、POST /api/games/:id/builds を機械的に再試行しないでください。再試行するたびに別のビルドができます。