Справочник схемы настройки

Это единый справочник для модели типов полей и пресетов Caputchin, общего фундамента под каждой настраиваемой поверхностью:

• Настройка игр: язык, скин и конфигурация игры из маркетплейса.
• Схемы пользовательских игр: схема, которую ты авторствуешь сам для пользовательской игры.
• Манифесты игр маркетплейса: блоки locales / skins / configurations, которые объявляет автор игры.
• White-label виджета: встроенная схема оболочки виджета.

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

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

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

Скин это не только цвета и ассеты: он может также выставить скалярные ручки boolean, number, range и list (переключатель «тени», число радиуса угла, выбор «узор»). Они ведут себя ровно как их аналоги в конфигурации и разрешаются в своё типизированное значение (boolean остаётся true, number остаётся 8); значения color и ассета разрешаются в строки. Скин не допускает string или link (свободный текст принадлежит языку; цель ссылки это конфигурация).

Что принимает каждый тип

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

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

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

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

Расширение пресета

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

{
  "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.

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

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

• Игра маркетплейса: схема приходит из манифеста автора игры, запрашиваемого, когда ты открываешь редактор. Ты переопределяешь пресеты игры, но не меняешь её схему.
• Пользовательская игра: ты определяешь схему сам в панели, затем авторствуешь пресеты против неё. Смотри пользовательские игры.
• Оболочка виджета (white-label): фиксированная, встроенная схема. Ты переопределяешь её пресеты; набор полей не объявляется автором. Смотри white-label виджета.

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

Внутри оси поля сгруппированы в именованные пресеты, и сервер разрешает один действующий пресет на группу из слоёных охватов, ключ сайта поверх команды поверх встроенного умолчания, вычисляется на каждое значение. Селекторы различаются по оси: язык выбирается языком браузера посетителя, скин предпочтением посетителя светлого или тёмного (пресет, чей режим any, годен для любого), а конфигурация авторитетна на сервере (посетитель не может её выбрать). Смотри обзор о модели охвата.

См. также

• Обзор настройки игр: регистрация и управление играми, плюс инструкции по осям для конфигураций, языка и скина.
• Схема панели пользовательской игры: авторствование схемы самому для пользовательской игры.
• Манифест caputchin.json: объявление этих блоков как автор игры маркетплейса.
• White-label виджета: те же типы, применённые к оболочке виджета.