Unity / Godot SDK ガイド

入力の検証・再送・通信方式の選択・プロトコル差分の吸収は GameRush 側のランタイムが持っていて、SDK が持つのは型のついた呼び出しと待ち合わせだけです。そのため、作者が SDK を更新しなくても GameRush 側の改善はそのまま既存のビルドへ届きます。

SDK の更新が要るのは、新しい API を使いたいときだけです。

• 例外を投げません。すべての呼び出しが結果オブジェクトを返します。GameRush の外（作者の自サイトなど）で動かした場合も unsupported を返して静かに縮退します。
• 起動時に protocolVersion を読みます。SDK が要求する版数を満たさない環境では、その機能を無効にします。
• 知らないイベントは黙って捨てます。ランタイムが SDK より新しいことは常に起こり、close の reason のように既知のイベントへ新しい値が増えることもあります。
• メッセージは 8KB 上限です。WebRTC のデータチャネルの実用上限に合わせてあり、緩める予定はありません。
• channel と宛先は必須の概念です。いまの WebSocket 中継では unreliable も落ちずに順序どおり届きますが、将来 WebRTC へ切り替わると本当に落ちて並び替わります。落ちる前提で書いてください。
• join は置き換えです。部屋にいる状態で join を呼ぶと、先に現在の部屋が閉じて close（reason は replaced）が届き、それから新しい部屋を取りに行きます。join が失敗しても元の部屋には戻らないので、続けたいときは close を受けてから join し直してください。

ランキングの定義は作者が宣言するもので、ゲームからは作れません。

ゲームからできるのは、宣言済みの枠へ投稿することと読むことだけです。宣言は Studio の画面からでも API からでもできます（「6. API トークン」）。

スコアはゲームからの自己申告値で、GameRush は値を検証していません。

応答の Verified / verified は常に false です。これをゲーム内で表示する義務はありません — 使いたいときのために値を渡しているだけで、GameRush 側の画面では GameRush が自分で明示します。

entry の DisplayName / AvatarUrl は、その相手が同意済みのときだけ入ります。

// Unity
var boards = await GRush.Leaderboards.ListAsync();
var posted = await GRush.Leaderboards.SubmitAsync("high_score", 12000);
var page = await GRush.Leaderboards.TopAsync("high_score", 20);
var near = await GRush.Leaderboards.AroundMeAsync("high_score", 5);
foreach (var entry in page.Value.Entries)
{
    var label = entry.IsGuest ? "ゲスト" : (entry.DisplayName ?? "匿名");
}

# Godot
var boards: Dictionary = await GRush.leaderboards.list()
var posted: Dictionary = await GRush.leaderboards.submit("high_score", 12000)
var page: Dictionary = await GRush.leaderboards.top("high_score", {"limit": 20})
var near: Dictionary = await GRush.leaderboards.around_me("high_score", {"range": 5})

ConsentDeclined は session が拒否されたときと FriendsAsync / friends の同意拒否のときの両方で返り、コードもメッセージも同じなので結果からは区別できません。投稿の失敗を Code だけで一括に捌くと、切れたセッションを同意拒否と誤診します。

session はゲームが指定できません。信頼済みの親 UI が live なセッションを付け、そのセッションがこのゲーム・この相手のものかをサーバが検証します。

AroundMeAsync / around_me は、自分がまだ載っていないときに空の一覧を返します。先頭を返すとゲーム側が「自分は1位」と誤読するためです。

FriendsAsync / friends は相互フォローに絞った一覧ですが、ゲームごとのフレンド同意がまだ無いため、現在は常に ConsentDeclined を返します。

エントリの metadata は、Godot はそのまま辞書で返しますが Unity は返しません。metadata が要る Unity のゲームは、応答の生 JSON である GRushLeaderboardPage.RawJson を自前のパーサへ渡してください。

他プレイヤーへ見せる進捗（称号・ひとことなど）の入れ物です。クラウドセーブとは別で、本人だけが読む非公開データはこの経路から一切読めません。

ここに置いたものは他プレイヤーへ見えるユーザー生成コンテンツで、通報とモデレーションの対象になります。そのため payload に制約があります。

Unity の payload は生の JSON 文字列、Godot は辞書です。

// Unity
await GRush.PlayerState.SetMineAsync("{\"title\":\"初心者\",\"level\":3}");
var mine = await GRush.PlayerState.GetMineAsync();
var others = await GRush.PlayerState.GetAsync(new[] { pseudoIdA, pseudoIdB });

# Godot
await GRush.player_state.set_mine({"title": "初心者", "level": 3})
var mine: Dictionary = await GRush.player_state.get_mine()
var others: Dictionary = await GRush.player_state.get_many([pseudo_id_a, pseudo_id_b])

Godot 側だけメソッド名が get_many なのは、get が Godot 側の Object.get と衝突してパースエラーになるためです。通信上のメソッド名は Unity と同じ playerState.get です。

運営が伏せた状態は返りません。要求した疑似IDの数だけ返ってくる前提で書かないでください。エディタのモックでも GRushMockPlayerStates.Define(id, json, hidden: true) / define(id, payload, true) で同じ挙動を試せます。

SetMine に baseRevision を渡すと楽観ロックになり、他所で更新されていれば InvalidParams で戻ります。省略すれば常に上書きします。

ランキングを画面で1つずつ足すのが面倒なときは、Studio の「API トークン」から資格情報を発行して HTTP で宣言できます。CI から流しても構いません。

トークンをゲームのビルドへ入れないでください。ビルドに入れたものは公開したのと同じで、出回った後は取り消せません。

置き場所はエンジンプロジェクトの外側 — 手元の環境変数か CI のシークレットです。

• GameRush Studio の「API トークン」から発行する
• 権限は要るものだけ選ぶ（宣言だけなら leaderboards:read と leaderboards:write。ゲーム ID を調べるなら games:read）
• 対象のゲームを絞れる。絞ったトークンを他のゲームへ向けると 404 になる
• 平文が出るのは発行直後の一度だけ。失くしたら失効させて出し直す

curl -X PUT "https://gamerush.cc/api/games/$GAME_ID/leaderboards/high_score" \
  -H "Authorization: Bearer $GRUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"ハイスコア","sort":"desc","valueType":"int","aggregation":"best","period":"all_time","minValue":0,"maxValue":1000000}'

PUT は key での冪等な適用です。無ければ作り、あって内容が違えば更新し、同じ内容なら何もしません。同じコマンドを何度流しても結果は変わらないので、宣言をリポジトリのスクリプトに置いて毎回流して構いません。

• 一覧は GET /api/games/$GAME_ID/leaderboards、ゲーム ID は GET /api/games で取れる
• 投稿が1件でもある枠では sort / valueType / aggregation / period を変えられない（409）。保存済みの値の意味が後から変わるため。変えたいときは別の key を作る。同じ値を流し直す分は変更ではないので通る
• 値域（minValue / maxValue）は両方揃って初めて意味を持つ。宣言が無い枠は投稿を受け付けない

Unity から出ずに、ログインからビルドのアップロード、ランキングの宣言まで通せます。

「6. API トークン」のトークンを手で貼る必要はありません。Editor がブラウザ承認で自分で取ります。

トークンはプロジェクトの外（%APPDATA%\GameRush\ / ~/Library/Application Support/GameRush/ / $XDG_CONFIG_HOME/GameRush/）に置きます。Assets/ にも EditorPrefs にも書かないので、リポジトリにもプロジェクト設定にも漏れません。Editor 側のコードは Editor 専用のアセンブリに入っており、書き出したビルドにはコードもトークンも含まれません。

WebGL / Web 書き出し以外では、SDK は自動的にモックへ落ちます。これが無いとエディタで一切テストできないため、モックは付属品ではなく SDK 本体の一部として扱っています。

AddPeer / mock_add_peer が返す相手は、同じプロセス内の2人目の peer として実際に部屋へ入り、送受信が往復します。実機やサーバへ繋がずに2人分の挙動を確認できます。

ランキングのモックが再現するのは、実サーバの縛りのうち「値域」と「集約」だけです。

session 束縛と有効プレイ 10 秒はエディタでは意味を持たないので省いてあります。つまりエディタで通った投稿が実環境で 400 / 403 になることはあるので、投稿の失敗経路はゲーム側で必ず扱ってください。

UnreliableDropRate は既定 0 ですが、出荷前に必ず 0 より大きくして試してください。

本番の WebSocket 中継は unreliable を落とさないため、パケットが落ちる前提で書けているかを確かめられる場所はここしかありません。確認を怠ったゲームは、WebRTC へ切り替わった時点で初めて壊れます。

各エンジン2本です。どちらもシーンアセットを持たないので、空のシーンにノード（Unity は GameObject、Godot は Control）を1つ作ってスクリプトを付けてください。

ランキングと公開プレイヤー状態はサンプルではまだ使っていないので、「4. ランキング」「5. 公開プレイヤー状態」の API を直接呼んでください。