---
title: "設定リファレンス（kumo.config.json）"
description: "1つの環境のマスターデータです。`kumodeck config push [file] --env <env>`でpushするか、ダッシュボードで編集します。"
url: "/ja/docs/reference/config/"
lang: ja
index: "/ja/llms.txt"
---
# 設定リファレンス（`kumo.config.json`）

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

```json
{
  "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モード](/ja/docs/guides/multiplayer/index.md#p2pモード)）。審判がいないので、スコアを競う対戦や賞品のある対戦には使わない |
| `p2p.maxPlayers` | 2〜8 | `4` | メッシュの上限。モードの`maxPlayers`はこの値までに抑えられ、`minPlayers`はこの値以下であること。満員のメッシュへの参加は`p2p_room_full` |
| `p2p.relayOnly` | boolean | `true` | 全員をTURNの中継経由にして、相手にIPアドレスが見えないようにする。13歳未満のプレイヤーはこの値にかかわらず常に中継経由 |

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

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

## `auth`

ログインの設定です（[ガイド](/ja/docs/guides/auth/index.md)）。ゲストとメールでのログインは常に使えます。外部のプロバイダーはすべて、**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され、履歴に残るため）。認証情報はダッシュボードで入力し、暗号化して保存されます。

```json
{ "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`（自分のアプリ）。

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

## `share`

アプリやゲームをXで広めるための機能です（[ガイド](/ja/docs/guides/sharing/index.md)）。**すべて既定は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`のどちらかを指定してください。

```json
{
  "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](/ja/docs/reference/rest-api/index.md)を参照してください。

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

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