設定リファレンス（`kumo.config.json`）

1つの環境のマスターデータです。kumodeck config push [file] --env <env>でpushするか、ダッシュボードで編集します。何かを変更する前にドキュメント全体を検証し、エラーはJSONのパス付きで返ります（multiplayer.modes[0].maxPlayers: …）。どのセクションも省略でき、使うたびにお金がかかる機能や、利用者（API の名前では players = プレイヤー）に見えるものを変える機能（外部サービスでのログイン、シェア機能）は、ここでONにするまでOFFです。

{
  "version": 1,
  "resetTimeZone": "UTC",
  "multiplayer": { "modes": [] },
  "auth": { "redirectUrls": [], "providers": {} },
  "web": { "allowedOrigins": [] },
  "share": {}
}

共通の型#

型	ルール
key	小文字のsnake_case: `^[a-z][a-z0-9_]{0,47}$`。キーはセクション内で一意
text	文字列（1〜120文字）または言語コード→文字列のマップ: `{ "en": "Coins", "ja": "コイン" }`。言語コードは`en`、`ja`、`pt-BR`のような形
long text	textと同じで、最大500文字

トップレベル#

項目	型	既定値
`$schema`	string	—	無視される（エディターの補完用）
`version`	`1`	`1`	形式のバージョン
`resetTimeZone`	IANAのタイムゾーン	`"UTC"`	例: `Asia/Tokyo`。不明なタイムゾーンは拒否される

`stats[]`（最大128）#

項目	型	既定値
`key`	key	必須
`title`	text	—
`aggregation`	`sum` \| `max` \| `min` \| `latest`	`sum`	報告をどう集計するか
`maxPerSubmit`	0より大きい数	—	1回の報告で受け付ける最大値（改ざん対策の最低ライン）

`multiplayer.modes[]`（最大16）#

項目	型	既定値
`key`	key	必須	`rooms.quickMatch(key)` / `rooms.create(key)`で使う
`title`	text	—
`minPlayers`	1〜64	`2`	この人数が待機するとクイックマッチが始まる
`maxPlayers`	1〜64	`4`	`minPlayers`以上であること
`fillTimeoutSeconds`	0〜300	`15`	この時間が過ぎたら少ない人数で始める。`0`は無期限に待つ
`transport`	`server` \| `p2p`	`server`	`p2p` = ゲームのメッセージをプレイヤー同士がWebRTCで直接やり取りする（P2Pモード）。審判がいないので、スコアを競う対戦や賞品のある対戦には使わない
`p2p.maxPlayers`	2〜8	`4`	メッシュの上限。モードの`maxPlayers`はこの値までに抑えられ、`minPlayers`はこの値以下であること。満員のメッシュへの参加は`p2p_room_full`
`p2p.relayOnly`	boolean	`true`	全員をTURNの中継経由にして、相手にIPアドレスが見えないようにする。13歳未満のプレイヤーはこの値にかかわらず常に中継経由

モードを1つも定義しない場合は、組み込みのdefaultモード（2〜8人、15秒）が使えます。モードを1つでも定義すると、定義したモードだけが使えます。

リアルタイムの部屋（kumo.realtime）は、モードとは別の機能のスイッチfeatures.realtimeChannelsでONにします（kumodeck features on realtimeChannels。既定はOFF）。WebSocketは、multiplayerとこのスイッチのどちらかがONならつながります。音声通話はfeatures.voiceでONにし、realtimeChannelsも要ります（kumodeck features on realtimeChannels voice）。

`auth`#

ログインの設定です（ガイド）。ゲストとメールでのログインは常に使えます。外部のプロバイダーはすべて、ONにするまでOFFです。

項目	型	既定値
`redirectUrls`	URL[]（最大32）	`[]`	メールのリンクとOAuthの戻り先として許可するアプリのページ。完全一致のURL（クエリは任意）か、パスの前方一致なら末尾に``: `https://mygame.example.com/`。developmentのlocalhostと、KUMODeckでホスティングしているURLは常に許可される
`providers.google.enabled`	boolean	`false`	Googleでログイン（ダッシュボードで自分のOAuthクライアントの登録が必要）
`providers.discord.enabled`	boolean	`false`	Discordでログイン（ダッシュボードで自分のOAuthクライアントの登録が必要）
`providers.apple.enabled`	boolean	`false`	Appleでログイン（ダッシュボードでServices IDと鍵の登録が必要）
`providers.x.enabled`	boolean	`false`	Xでログイン（ダッシュボードで自分のXアプリのClient IDとSecretの登録が必要。KUMODeckの共用Xアプリが使える環境では設定なしで使うも選べ、ログインは無料）

プロバイダーの認証情報は、このファイルには決して保存しません（このファイルは手元のマシンからpushされ、履歴に残るため）。認証情報はダッシュボードで入力し、暗号化して保存されます。

{ "auth": { "redirectUrls": ["https://mygame.example.com/*"], "providers": { "x": { "enabled": true } } } }

`web`#

項目	型	既定値
`allowedOrigins`	origin[]（最大32）	`[]`	公開鍵の使用を許可するWebのオリジン。空ならすべてのオリジン

アプリはどこでもホスティングできます。KUMODeck上でも、自分のサーバーでも、itch.ioでもかまいません。既定（空のリスト）では、SDKはどのオリジンからでも動きます。オリジンを列挙すると、ほかのサイトがあなたの公開鍵を使うのを止められます（利用料を払うのはあなたです）。ほかのオリジンからのブラウザのリクエストは403 origin_not_allowedになります。KUMODeckでホスティングしているあなたのアプリのURLと、developmentでのlocalhostは常に許可されます。項目はパスを含まないオリジンで書きます: https://mygame.example.com、https://*.itch.zone（任意のサブドメイン）、http://localhost:5173、capacitor://localhost（自分のアプリ）。

{ "web": { "allowedOrigins": ["https://mygame.example.com", "https://*.itch.zone"] } }

`share`#

アプリやゲームをXで広めるための機能です（ガイド）。すべて既定はOFFです。使うものだけをONにしてください。

項目	型	既定値
`images.enabled`	boolean	`false`	1200×600のカード画像を描画する（既定のカード + スコア / 挑戦のカード）
`images.title`	text（60以下）	—	カードに描くアプリの名前
`images.background`	デプロイ内のパス	—	文字の背景に置くPNG / JPEG（2MB以下、2:1が最適）
`images.font`	デプロイ内のパス	—	追加のTTF / OTF（10MB以下）。組み込みのフォントはラテン文字のみなので、日本語などにはフォントを追加する
`images.theme`	`{ background, accent, text }`	`#0f1115` / `#ffcc33` / `#ffffff`	`#rrggbb`形式の色
`tags.enabled`	boolean	`false`	使われません。KUMODeckはページにタグを足しません（pushのときに1行で知らせます）。`kumodeck share tags`のタグを`<head>`に書きます
`tags.title` / `tags.description` / `tags.imageAlt`	text	—	カードの文面
`tags.image`	デプロイ内のパスまたは`https://`のURL	—	固定のカード画像（なければ描画された既定のカード）
`tags.site`	`@handle`	—	`twitter:site`
`links.enabled`	boolean	`false`	`kumo.share()`がシェアID（`?ks=`）を発行し、挑戦を復元できるようにする
`links.text`	text（200以下）	—	既定の投稿文。`{score}`が置き換えられる
`links.hashtags` / `links.via`	string[]（最大5） / handle	`[]` / —	Xの投稿に追加される
`tracking.enabled`	boolean	`false`	シェアIDごとに訪問数 / 新しい利用者 / 利用回数（plays）を数える（集計値のみ）
`inAppBrowser.enabled`	boolean	`false`	Xのアプリ内ブラウザから、同じゲストのまま「ブラウザで開く」ことを許可する

カード用のタグには画像が必要です。tags.imageかimages.enabledのどちらかを指定してください。

{
  "share": {
    "images": { "enabled": true, "title": "Space Cats", "background": "/card-bg.png" },
    "tags": { "description": "A tiny space game", "site": "@spacecats" },
    "links": { "enabled": true, "text": "I scored {score} in Space Cats. Can you beat it?", "hashtags": ["spacecats"] },
    "tracking": { "enabled": true }
  }
}

`audience`#

general（既定）、mixed、kidsのいずれかで、誰がアプリやゲームを使うかを表します。kidsはすべての利用者を13歳未満として扱います。mixedは、年齢が不明な利用者を、年齢を申告するまで子どもとして扱います。

`integrity`#

報告されたstatsをサーバー側でチェックします。チェックはstatが保存される前に行われます。拒否された値はPOST /v1/statsのrejectedで返り、シグナルとして記録されます（自動で何かが処置されることはありません）。

項目	型	既定値
`stats.rules[]`（最大128）	`{ stat, min?, max? }`	`[]`	statの値の許容範囲（例: ベストタイムが1秒未満はありえない → `min: 1000`）
`stats.maxSubmitsPerMinute`	1〜600	`60`	利用者ごとの1分あたりの報告回数
`stats.webhook.url`	httpsのURL	—	判断を自分のサーバーに任せる（developmentでは`http://localhost`も可）
`stats.webhook.timeoutMs`	100〜5000	`1500`
`stats.webhook.onFailure`	`accept` \| `reject`	`accept`	自分のサーバーが落ちている・遅いときの扱い

webhookはPOST { type: "stats.verify", environmentId, playerId, stats, submittedAt }を受け取ります。ヘッダーはKumo-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + "." + body)>です（シークレットはダッシュボードとGET /v1/admin/integrity/webhook-secretで確認できます）。{ "approve": true }または{ "results": { "<stat>": true } }で応答します。

そのほかのセクション#

セクション	定義するもの	API

リクエストとレスポンスの形はREST APIを参照してください。

検証ルール（相互参照）#

セクション内でキーが重複していると拒否される
minPlayers ≤ maxPlayers

設定リファレンス（kumo.config.json）

共通の型#

トップレベル#

stats[]（最大128）#

multiplayer.modes[]（最大16）#

auth#

web#

share#

audience#

integrity#