---
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`, которые объявляет автор игры.
- [White-label виджета](/docs/widget-customization/white-label): встроенная схема оболочки виджета.

Все четыре используют те же типы полей и ту же модель пресетов, описанную здесь. Настройка построена из **пресетов**, а пресет это мешок типизированных **полей**.

## Типы полей по оси

Каждая ось допускает фиксированный набор типов полей:

| Ось | Допустимые типы полей |
|---|---|
| Конфигурация | `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` | Один выбор | Должен быть одним из перечисленных опций поля. |
| `link` | URL | URL `http` или `https`. Встроенные учётные данные отклоняются. |
| `color` | Цвет | Hex-цвет (`#rgb`, `#rgba`, `#rrggbb` или `#rrggbbaa`) или значение `rgb()` / `rgba()`. Именованные цвета и другие цветовые пространства не принимаются. |
| `image` | Изображение | Загруженный файл или `https`-URL, заканчивающийся на `.png`, `.jpg`, `.jpeg`, `.webp`, `.svg` или `.gif`. |
| `audio` | Аудиоклип | Загруженный файл или `https`-URL, заканчивающийся на `.mp3`, `.ogg` или `.wav`. |
| `video` | Видео | Загруженный файл или `https`-URL, заканчивающийся на `.mp4` или `.webm`. |

Caputchin валидирует каждое значение при сохранении, так что значение, которое не подходит под свой тип, отклоняется до того, как сможет дойти до посетителя.

## Зарезервированные ключи

Рядом с полями содержимого пресет несёт несколько зарезервированных **метаданных-ключей** (каждый с префиксом-подчёркиванием), которые управляют тем, как он выбирается и разрешается, а не тем, что он отображает. Как ты их задаёшь, зависит от поверхности: [автор игры маркетплейса](/docs/marketplace-game-development/the-caputchin-json-manifest) пишет их буквально в `caputchin.json`; в редакторе панели (пользовательские игры, white-label) ты задаёшь их через элементы управления и никогда не печатаешь ключ. В любом случае смысл один и тот же.

| Ключ | Ось | Значение |
|---|---|---|
| `_lang` | Язык | Языковой тег BCP-47, который обслуживает пресет локали (`en`, `es` и так далее). Пресеты группируются по нему; несколько пресетов могут разделять один `_lang` (например два английских варианта). |
| `_direction` | Язык | `ltr` или `rtl`. Опционально, авто-выводится из `_lang` для языков с письмом справа-налево (`ar`, `he`, `fa`, `ur`, `yi`, `ps`, `sd`); редко задаётся вручную. |
| `_theme` | Скин | `light`, `dark` или `any`. Пресет `light` / `dark` показывается только под этим фоном; пресет `any` работает под обоими и годится для любого. По умолчанию `light`, когда отсутствует. |
| `_default` | Все | Помечает пресет, который сервер выбирает для своей группы, когда посетитель не выбирает ни одного. Одно умолчание на группу (на режим для скина); скин `any` может быть умолчанием для светлого, тёмного или обоих. |
| `_extends` | Все | Называет другой пресет для наследования. Смотри [Расширение пресета](#extending-a-preset). |

Зарезервированные метаданные-ключи **убираются при разрешении**: `_extends` и `_default` никогда не доходят до игры, и доставляются только выжившие метаданные (`_lang`, `_direction`, `_theme`) плюс уплощённые поля содержимого.

## Расширение пресета [#extending-a-preset]

`_extends` позволяет одному пресету унаследовать каждое значение от другого, так что ты авторствуешь только те поля, что различаются, вместо повторения целого пресета. Задай `_extends` в **имя другого пресета на той же оси**; расширяющий пресет стартует со всех значений того пресета и переопределяет ключи, которые задаёт сам.

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

Здесь `brand-light-warm` наследует `bg` от `brand-light` и меняет только `accent`.

Две детали:

- **Сокращение темы скина.** На пресете скина `_extends` может вместо этого назвать тему (`light` или `dark`), а не пресет. Эта форма разрешается в тот пресет, который является `_default` для этой темы, удобный способ основать вариант на «скине по умолчанию для светлой темы», не называя его.
- **Оно разрешается прочь.** `_extends` прослеживается, а затем убирается; игра получает полностью слитый результат, никогда сам ключ `_extends`.

## Откуда приходит схема

Набор полей, который может заполнить пресет (его **схема**), имеет три источника, все используют те же типы полей выше:

- **Игра маркетплейса**: схема приходит из манифеста автора игры, запрашиваемого, когда ты открываешь редактор. Ты переопределяешь пресеты игры, но не меняешь её схему.
- **Пользовательская игра**: ты определяешь схему сам в панели, затем авторствуешь пресеты против неё. Смотри [пользовательские игры](/docs/game-customization/custom-games).
- **Оболочка виджета (white-label)**: фиксированная, встроенная схема. Ты переопределяешь её пресеты; набор полей не объявляется автором. Смотри [white-label виджета](/docs/widget-customization/white-label).

## Пресеты и разрешение

Внутри оси поля сгруппированы в именованные пресеты, и сервер разрешает один действующий пресет на группу из слоёных охватов, ключ сайта поверх команды поверх встроенного умолчания, вычисляется на каждое значение. Селекторы различаются по оси: язык выбирается языком браузера посетителя, скин предпочтением посетителя светлого или тёмного (пресет, чей режим `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): объявление этих блоков как автор игры маркетплейса.
- [White-label виджета](/docs/widget-customization/white-label): те же типы, применённые к оболочке виджета.