---
type: reference
title: カスタマイズスキーマリファレンス
summary: すべてのカスタマイズ可能な面の背後にある、共有のフィールド型とプリセットのモデル、各軸が許すフィールド型、それぞれが受け付ける値、そしてスキーマとプリセットがどう定義されて解決されるか。
---

これは Caputchin の **フィールド型とプリセットのモデル**、すべてのカスタマイズ可能な面の下の共有の基盤の、単一のリファレンスです：

- [ゲームのカスタマイズ](/docs/game-customization/overview)：マーケットプレイスのゲームの言語、スキン、構成。
- [カスタムゲームのスキーマ](/docs/custom-game-development/dashboard-schema)：カスタムゲームのために自分で作るスキーマ。
- [マーケットプレイスゲームのマニフェスト](/docs/marketplace-game-development/the-caputchin-json-manifest)：ゲームの作者が宣言する `locales` / `skins` / `configurations` ブロック。
- [ウィジェットのホワイトラベル](/docs/widget-customization/white-label)：ウィジェットシェルの組み込みスキーマ。

4 つすべてが、ここで述べる同じフィールド型と同じプリセットモデルを使います。カスタマイズは **プリセット** から作られ、プリセットは型付き **フィールド** の袋です。

## 軸ごとのフィールド型

各軸は固定のフィールド型のセットを許します：

| 軸 | 許されるフィールド型 |
|---|---|
| 構成 | `boolean`、`number`、`range`、`list`、`string`、`link` |
| 言語 | `string` のみ |
| スキン | `color`、`image`、`audio`、`video`、`boolean`、`number`、`range`、`list` |

スキンは色とアセットだけではありません。スカラーのつまみ `boolean`、`number`、`range`、`list`（「影」のトグル、角の丸みの数値、「パターン」の選択肢）も公開できます。これらは構成の対応物とちょうど同じように振る舞い、その型付きの値に解決されます（`boolean` は `true` のまま、`number` は `8` のまま）。`color` とアセットの値は文字列に解決されます。スキンは `string` や `link` を許しません（自由なテキストは言語に属し、リンク先は構成です）。

## 各型が受け付けるもの

| 型 | 値 | ルール |
|---|---|---|
| `string` | 自由なテキスト | 任意のテキスト。 |
| `boolean` | トグル | `true` か `false`。 |
| `number` | 数値 | 任意の有限の数値。 |
| `range` | 境界のある数値 | フィールドの最小と最大の中の有限の数値。ステップはスライダーの便宜です。ステップ外の値も受け付けられます。 |
| `list` | 1 つの選択肢 | フィールドの挙げられたオプションの 1 つでなければなりません。 |
| `link` | URL | `http` か `https` の URL。埋め込まれた資格情報は拒否されます。 |
| `color` | 色 | hex の色（`#rgb`、`#rgba`、`#rrggbb`、または `#rrggbbaa`）か、`rgb()` / `rgba()` の値。名前付きの色やほかの色空間は受け付けられません。 |
| `image` | 画像 | アップロードしたファイルか、`.png`、`.jpg`、`.jpeg`、`.webp`、`.svg`、`.gif` で終わる `https` URL。 |
| `audio` | 音声クリップ | アップロードしたファイルか、`.mp3`、`.ogg`、`.wav` で終わる `https` URL。 |
| `video` | 動画 | アップロードしたファイルか、`.mp4`、`.webm` で終わる `https` URL。 |

Caputchin は保存時にすべての値を検証するので、その型に合わない値は訪問者に届く前に拒否されます。

## 予約キー

そのコンテンツのフィールドと並んで、プリセットは、何を表示するかではなく、どう選ばれて解決されるかを制御する、いくつかの予約された **メタデータキー**（それぞれアンダースコアが接頭につく）を運びます。それらをどう設定するかは面によります。[マーケットプレイスのゲームの作者](/docs/marketplace-game-development/the-caputchin-json-manifest) は `caputchin.json` にそれらをそのまま書きます。ダッシュボードのエディター（カスタムゲーム、ホワイトラベル）では、コントロールを通じて設定し、キーを決して打ちません。どちらにしても意味は同じです。

| キー | 軸 | 意味 |
|---|---|---|
| `_lang` | 言語 | ロケールのプリセットが提供する BCP-47 の言語タグ（`en`、`es` など）。プリセットはそれでまとめられます。複数のプリセットが 1 つの `_lang` を共有できます（たとえば 2 つの英語の変種）。 |
| `_direction` | 言語 | `ltr` か `rtl`。任意、右から左の言語（`ar`、`he`、`fa`、`ur`、`yi`、`ps`、`sd`）については `_lang` から自動で導かれます。手で設定することはまれです。 |
| `_theme` | スキン | `light`、`dark`、または `any`。`light` / `dark` のプリセットはその背景の下でのみ示されます。`any` のプリセットは両方の下で働き、どちらの資格もあります。なければ `light` が既定です。 |
| `_default` | すべて | 訪問者が選ばないとき、サーバーがそのグループに選ぶプリセットをマークします。グループごとに 1 つの既定（スキンはモードごと）。`any` のスキンは、ライト、ダーク、または両方の既定になれます。 |
| `_extends` | すべて | 継承する別のプリセットを名指します。[プリセットを拡張する](#extending-a-preset) を参照。 |

予約されたメタデータキーは **解決の間に取り除かれます**。`_extends` と `_default` はゲームに決して届かず、生き残るメタデータ（`_lang`、`_direction`、`_theme`）に、平坦化されたコンテンツのフィールドを足したものだけが届けられます。

## プリセットを拡張する [#extending-a-preset]

`_extends` は、1 つのプリセットに別のものからすべての値を継承させるので、プリセットをまるごと繰り返す代わりに、違うフィールドだけを作ります。`_extends` を **同じ軸の別のプリセットの名前** に設定します。拡張するプリセットは、そのプリセットのすべての値から始まり、それ自身が設定するキーを上書きします。

```json
{
  "skins": {
    "presets": {
      "brand-light": { "_theme": "light", "accent": "#2da44e", "bg": "#ffffff" },
      "brand-light-warm": { "_extends": "brand-light", "accent": "#d97706" }
    }
  }
}
```

ここで `brand-light-warm` は `brand-light` から `bg` を継承し、`accent` だけを変えます。

2 つの細部：

- **スキンのテーマのショートカット。** スキンのプリセットでは、`_extends` はプリセットではなくテーマ（`light` か `dark`）を名指せます。その形は、そのテーマの `_default` であるプリセットに解決され、名指さずに「既定のライトのスキン」に変種の土台を置く便利な方法です。
- **それは解決されて消えます。** `_extends` は追われ、それから取り除かれます。ゲームは完全にマージされた結果を受け取り、`_extends` キー自体を決して受け取りません。

## スキーマがどこから来るか

プリセットが埋められるフィールドのセット（その **スキーマ**）は、3 つのソースを持ち、すべて上の同じフィールド型を使います：

- **マーケットプレイスのゲーム**：スキーマはゲームの作者のマニフェストから来て、エディターを開くと取得されます。ゲームのプリセットは上書きしますが、そのスキーマは変えません。
- **カスタムゲーム**：あなたがダッシュボードでスキーマを自分で定義し、それに対してプリセットを作ります。[カスタムゲーム](/docs/game-customization/custom-games) を参照。
- **ウィジェットシェル（ホワイトラベル）**：固定された組み込みのスキーマ。そのプリセットは上書きしますが、フィールドのセットは作者が宣言するものではありません。[ウィジェットをホワイトラベルする](/docs/widget-customization/white-label) を参照。

## プリセットと解決

軸の中で、フィールドは名前付きのプリセットにまとめられ、サーバーは層をなしたスコープから、グループごとに 1 つの有効なプリセットを解決します。サイトキー、チーム、バンドル済みの既定の順で、値ごとに計算されます。セレクターは軸によって違います。言語は訪問者のブラウザの言語で選ばれ、スキンは訪問者のライトかダークの設定で（モードが `any` のプリセットはどちらの資格もあります）、構成はサーバー権威です（訪問者は選べません）。スコープモデルは [概要](/docs/game-customization/overview#troop-and-site-key-scope) を参照してください。

## あわせて読む

- [ゲームのカスタマイズの概要](/docs/game-customization/overview)：ゲームの登録と管理、加えて [構成](/docs/game-customization/configurations)、[言語](/docs/game-customization/locale)、[スキン](/docs/game-customization/skin) の軸ごとのハウツー。
- [カスタムゲームのダッシュボードスキーマ](/docs/custom-game-development/dashboard-schema)：カスタムゲームのためにスキーマを自分で作る。
- [caputchin.json マニフェスト](/docs/marketplace-game-development/the-caputchin-json-manifest)：マーケットプレイスのゲームの作者としてこれらのブロックを宣言する。
- [ウィジェットをホワイトラベルする](/docs/widget-customization/white-label)：ウィジェットシェルに適用された同じ型。