Игровой UI-kit UIDoc

Оформите готовые экраны UIDoc с помощью рисованного от руки игрового UI-kit движка: механизм @import, справочник классов, правила компоновки и примеры с разбором.

---

UI-набор Game UI — это нарисованный вручную набор интерфейса команды художников ($AO/ui/kit/Game UI/**): модальные окна, кнопки, вкладки, полосы прогресса, баннеры, иллюминаторы, слоты предметов, флажки и переключатели. Движок поставляет соответствующий stylesheet, так что любой ресурс UIDoc может принять внешний вид набора без копирования CSS.

Применяйте набор как финальный этап стилизации. Сначала постройте экран — разметку, привязки, события, поведение viewport — проверьте, что всё работает, и только потом оформляйте его. Стилизация набора — это краска и отступы; она никогда не должна быть средством исправления разметки.

Включение набора

Добавьте одну строку в index.css:

@import "game-ui-kit";

Во время bake-этапа движок подставляет res/ui/kit/kit.css вместо импорта, поэтому ставьте импорт первым, а свои правила — ниже него: ваши правила выигрывают при равенстве в каскаде. Импорт сочетается с утилитами Tailwind. Изменение stylesheet движка заново выпекает импортирующие ресурсы при следующей сборке; UIDoc всё ещё не делает hot reload в запущенной игре.

Единственный паттерн, который нужно знать

У UIDoc нет bitmap CSS-фонов, поэтому арткит попадает через обычные img элементы. Каждый контейнер набора — это позиционированный элемент, у которого первый дочерний элемент — .kit-bg изображение; div отвечает за форму и разметку, изображение только рисует, с девятисрезом через настройки ресурса, которые идут в комплекте с набором:

<div class="kit-modal">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_grey1.png">
  <!-- content -->
</div>

.kit-bg это object-fit: fill для арта с девятисрезом (модальные окна, кнопки, вкладки, полосы, баннеры). Арт с фиксированным соотношением сторон (флажки, переключатели, иллюминаторы, иконки слотов) использует .kit-bg--contain и собственные width/height контейнера.

Используйте .kit-bg--shadow на самом подложечном изображении img когда арт должен отбрасывать тень. Он использует учитывающий альфу drop-shadow(...), так что прозрачные углы и результат девятисреза, нарисованный в изображении, определяют силуэт. А box-shadow вместо этого следует за прямоугольной рамкой контейнера, тогда как размещение drop-shadow(...) на контейнере также включит в тень его текст и других потомков.

Помещайте видимый текст кнопки/вкладки на передний план, в элемент-метку после арта. Сырой текст, принадлежащий контейнеру, может рисоваться под его дочерним изображением:

<button class="kit-btn kit-btn--green">
  <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_green1.png">
  <span class="kit-btn-label">PLAY</span>
</button>

Набор оптически опускает прямые подписи кнопок на 5px, чтобы они совпадали с артом. Для составного foreground, например иконки плюс цена, оберните весь foreground в .kit-btn-content чтобы иконка и текст двигались вместе:

<button class="kit-btn kit-btn--green">
  <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/shiny_buttons/button_large_green1.png">
  <span class="kit-btn-content price">
    <img src="coin.png">
    <span class="kit-btn-label">300</span>
  </span>
</button>

Справочник классов

Класс	Используйте
.kit-bg, .kit-bg--contain, .kit-bg--shadow	Изображение подложки арта, fit с фиксированным соотношением сторон и учитывающая альфу тень изображения
.kit-fg	Общий слой foreground над .kit-bg
.kit-modal	Позиционированная панель flex-column с отступами набора
.kit-modal-header	Центрированная безопасная зона заголовка, по 72px зарезервировано с каждой стороны
.kit-modal-title	Центрированная строка заголовка; сочетайте с .kit-text-header
.kit-title-banner	pointy_banner_* подложка за заголовком модального окна, полностью внутри модалки
.kit-header-band	modal_header_* полоса поперёк верхнего края, нарисованного у модалки
.kit-dim	Затемнение на весь экран позади модалки
.kit-btn, .kit-btn-label, .kit-btn-content, .kit-btn--<colour>	Арт кнопки плюс оптически опущенная метка/группа foreground с контуром в цвет кнопки
.kit-tab-row, .kit-tab, .kit-tab-label, .kit-tab--active	Строка навигации из табов-пилюль с метками на переднем плане
.kit-progress, .kit-progress-fill, .kit-progress--N, .kit-progress--compact	Дорожка плюс привязанный fill; модификатор семейства выравнивает fill, а compact выбирает масштаб 30px
.kit-card, .kit-list-row	Структурные контейнеры для карточек и строк на основе арта
.kit-close	Элемент закрытия на переднем плане, абсолютно закреплённый в правом верхнем углу модалки
.kit-slot, .kit-slot-icon, .kit-slot-qty	Квадрат инвентаря/магазина с иконкой и количеством
.kit-porthole	Круглая рамка; укладывайте *_back.png под *_ring.png
.kit-checkbox, .kit-toggle	Элементы управления состоянием с фиксированным соотношением сторон
.kit-text-header/body/body-dark/info	Четыре утверждённых текстовых стиля из art doc

Размеры текста соответствуют art doc (65/55/45/40) при стандартном логическом viewport; переопределяйте в ресурсе, когда экрану нужен другой масштаб.

Правила сборки

Это взято из документации Game UI команды художников и устоявшейся практики; классы кодируют большую часть из них, а шаблоны разметки покрывают остальное.

• Заголовки: белый, Heavy, чёрная обводка, тень (.kit-text-header), задавайте либо прямо на модалке, либо на .kit-title-banner (тёмная подложка-баннер, полностью внутри модалки — избегайте коричневого "yellow" pointy banner), либо на .kit-header-band если сочетание цветов работает: насыщенная полоса на светлой модалке (красный на белом) читается хорошо; приглушённое на приглушённом (золото на сером) — нет. Если сомневаетесь, обычный текст заголовка всегда безопасен.
• Заголовки модалок с кнопкой закрытия: держите .kit-close как прямого потомка .kit-modal, где он остаётся абсолютно закреплённым в правом верхнем углу. Поместите заголовок или баннер заголовка внутрь .kit-modal-header; его симметричные боковые резервы по 72px визуально центрируют заголовок и держат его вдали от кнопки закрытия. Планируйте ширину модалки как желаемую ширину заголовка/баннера плюс оба резерва по 72px плюс левый и правый padding панели. Это намеренно делает закрываемые модалки немного шире, чем плотно подогнанный body content.
• Тени арта: box-shadow следует за прямоугольной рамкой. Для нерегулярного или девятисрезного арта набора поместите .kit-bg--shadow на самом подложечном изображении img чтобы тень следовала его нарисованной альфе. Не помещайте фильтр на .kit-modal, потому что тогда в силуэт тени попадут текст модалки и дочерний арт.
• Кнопки: текст белый с цветной обводкой в тон арту кнопки — никогда не чёрной. Поместите обычную метку непосредственно в .kit-btn-label чтобы она рисовалась поверх арта и получала 5px оптического смещения базовой линии набора. Для контента с иконкой и текстом поместите оба элемента в прямого .kit-btn-content потомка, чтобы пара получила это смещение вместе. Используйте shiny_buttons для покупок и особых взаимодействий, basic_buttons для всего остального и давайте тексту щедрые отступы. Сероая кнопка — это вид в состоянии disabled.
• Текст body: тонкая обводка с прозрачностью 20% (.kit-text-body) на цветных модалках; обычный тёмный текст (.kit-text-body-dark) на белых/серых модалках.
• Вкладки: строка-пилюля внутри тела модалки, а не прикреплённая к верхнему краю. Помещайте текст в .kit-tab-label. Активная вкладка использует цветной вариант арта (например tabs_blue) с соответствующей цветной обводкой текста; неактивные вкладки используют tabs_black. Используйте tab_med.png или tab_large.png для динамических меток. Исходники tab_small.png непоследовательны, и некоторые содержат встроенные метки, поэтому они намеренно не девятисрезные.
• Полосы прогресса: каждая progress_bar_N папка содержит пару backing.png с специально созданным fill_*.png, но внутренние отступы отличаются у разных семейств и часто асимметричны из-за нижнего обода/тени. Арт дорожки помещается в .kit-bg; соответствующий fill семейства — в .kit-progress-fill, который использует object-fit: fill; добавьте соответствующий .kit-progress--N модификатор к контейнеру и привяжите data-style-image-fill-amount. Не подставляйте окрашенную иконку или декоративное прозрачное изображение: tint сохраняет исходную альфу, а cover может обрезать квадратный арт до щелей или диагональных клиньев на тонкой дорожке. Просматривайте полосу при 0, 0.25, 0.5, и 1; текущая диагностика не определяет неподходящую альфу текстуры. Компонент по умолчанию имеет толщину 40px; добавьте .kit-progress--compact для пропорционально масштабированной формы 30px. Для пользовательской толщины задайте одинаковые font-size и height значения на контейнере, чтобы его семейство внутренних отступов на основе em масштабировалось вместе с ним. Дорожки набора используют flex-shrink: 0; выбирайте толщину явно, а не полагайтесь на flex-родителя, который сожмёт дорожку, потому что тогда дорожка и её fill могут вычислиться в разных размерах.
• Слоты предметов: цветные квадраты (inv_square_<colour>1.png) для заполненных слотов; inv_square_empty2.png — это задуманное состояние EMPTY.
• Арт семейства модалок использует один масштаб (углы 37px, обводка 6px в исходных пикселях — уже поставляемые insets slice это учитывают). Элементы, которые должны композироваться, например полоска заголовка поверх модалки, выравниваются, потому что рисуются в одном масштабе; не редактируйте вручную отдельные значения slice.

Пример: модалка настроек

Модалки с полосой (modal_stripe_*) имеют более тёмную нижнюю полосу — размещайте на ней ряд действий, оставляя его последним flow-потомком.

<div class="kit-modal settings">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_stripe_blue1.png">
  <div class="kit-modal-header">
    <div class="kit-modal-title kit-text-header">НАСТРОЙКИ</div>
  </div>
  <button class="kit-close" data-on-click="event:settings:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <div class="rows">
    <div class="row">
      <span class="kit-text-body">Музыка</span>
      <button class="kit-toggle" data-on-click="event:toggle:music">
        <img class="kit-bg kit-bg--contain" data-if="music.on" src="$AO/ui/kit/Game UI/Additional Elements/Sliders + Toggles/switch_long_on.png">
        <img class="kit-bg kit-bg--contain" data-if="music.off" src="$AO/ui/kit/Game UI/Additional Elements/Sliders + Toggles/switch_long_off.png">
      </button>
    </div>
    <div class="row">
      <span class="kit-text-body">Сезонный пропуск</span>
      <div class="kit-progress kit-progress--1 pass-progress">
        <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/backing.png">
        <img class="kit-progress-fill" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/fill_yellow.png"
             data-style-image-fill-amount="pass.progress">
      </div>
    </div>
  </div>
  <div class="actions">
    <button class="kit-btn kit-btn--yellow" data-on-click="event:settings:save">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_yellow1.png">
      <span class="kit-btn-label">СОХРАНИТЬ</span>
    </button>
    <button class="kit-btn kit-btn--red" data-on-click="event:settings:reset">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_red1.png">
      <span class="kit-btn-label">СБРОСИТЬ</span>
    </button>
  </div>
</div>

@import "game-ui-kit";

.settings { width: 620px; }
.settings .rows { display: flex; flex-direction: column; gap: 18px; margin-bottom: 26px; }
.settings .row { display: flex; align-items: center; justify-content: space-between; gap: 20px; }
.settings .pass-progress { width: 260px; }
.settings .actions { display: flex; gap: 16px; justify-content: center; }

UI.uidoc_bind_bool("music.on", player.music_enabled);
UI.uidoc_bind_bool("music.off", !player.music_enabled);
UI.uidoc_bind_float("pass.progress", clamp(player.pass_progress, 0.0, 1.0));

Пример: диалог подтверждения (боевой запрос)

Насыщенная полоса заголовка на светлой модалке, тёмный текст body и пара кнопок принятия/отклонения жёлтого/красного цвета.

<div class="kit-modal battle">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_white1.png">
  <div class="kit-header-band">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_header_red1.png">
    <div class="kit-modal-header">
      <span class="kit-text-header band-title">БОЕВОЙ ЗАПРОС</span>
    </div>
  </div>
  <button class="kit-close" data-on-click="event:battle:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <div class="kit-porthole challenger">
    <img class="kit-bg kit-bg--contain" src="$AO/ui/kit/Game UI/Additional Elements/Circle Portholes/blue_back.png">
    <img class="kit-bg kit-bg--contain" src="$AO/ui/kit/Game UI/Additional Elements/Circle Portholes/gold_ring.png">
  </div>
  <span class="kit-text-body-dark message">{{challenger.name}} вызывает вас на бой!</span>
  <div class="actions">
    <button class="kit-btn kit-btn--yellow" data-on-click="event:battle:accept">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_yellow1.png">
      <span class="kit-btn-label">ПРИНЯТЬ</span>
    </button>
    <button class="kit-btn kit-btn--red" data-on-click="event:battle:decline">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_red1.png">
      <span class="kit-btn-label">ОТКЛОНИТЬ</span>
    </button>
  </div>
</div>

@import "game-ui-kit";

.battle { width: 680px; align-items: center; }
.battle .band-title { font-size: 55px; }
.battle .challenger { margin-bottom: 10px; }
.battle .message { text-align: center; margin-bottom: 24px; }
.battle .actions { display: flex; gap: 16px; }

Пример: ежедневная награда

Заголовок на баннерной подложке на серой модалке, слоты наград, полоса серии и блестящая кнопка получения.

<div class="kit-modal reward">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_grey1.png">
  <div class="kit-modal-header">
    <div class="kit-title-banner">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Horizontal Banners/pointy_banner_blue.png">
      <span class="kit-text-header banner-title">ЕЖЕДНЕВНАЯ НАГРАДА</span>
    </div>
  </div>
  <button class="kit-close" data-on-click="event:reward:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <span class="kit-text-body-dark streak">День {{streak.day}} — не останавливайтесь!</span>
  <div class="slots">
    <div class="kit-slot" data-for="reward in rewards" data-for-key="reward.id">
      <img class="kit-bg kit-bg--contain" src="{{reward.back}}">
      <img class="kit-slot-icon" src="{{reward.icon}}">
      <span class="kit-slot-qty">{{reward.count}}</span>
    </div>
  </div>
  <div class="kit-progress kit-progress--1 streak-bar">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/backing.png">
    <img class="kit-progress-fill" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/fill_yellow.png"
         data-style-image-fill-amount="streak.progress">
  </div>
  <button class="kit-btn kit-btn--yellow claim" data-on-click="event:reward:claim">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/shiny_buttons/button_large_yellow1.png">
    <span class="kit-btn-label">ПОЛУЧИТЬ</span>
  </button>
</div>

@import "game-ui-kit";

.reward { width: 600px; align-items: center; }
.reward .banner-title { font-size: 50px; }
.reward .streak { margin-bottom: 16px; }
.reward .slots { display: flex; gap: 12px; margin-bottom: 18px; }
.reward .streak-bar { width: 320px; margin-bottom: 22px; }

Заполненные слоты привязывают reward.back к $AO/ui/kit/Game UI/Item Backs/inventory_squares_1/inv_square_blue1.png (или другому цвету); пустые слоты используют inv_square_empty2.png без иконки.

Покрытие арта

Отступы для девятисреза поставляются в res/ui/kit/Game UI/.asset_settings для: Basic Modals (simple, stripe, headers), basic и shiny buttons, medium/large modal tab pills и trapezoids, горизонтальные backings/fills полос прогресса (кроме сегментных спрайтов и фиксированного bar 12), горизонтальные pointy banners и горизонтальные внутренние панели. Элементы с фиксированным соотношением сторон — включая квадраты инвентаря, флажки, слайдеры и переключатели, иллюминаторы, вспомогательные masks и highlights — не требуют срезов. Другие семейства (карточки, облачка речи, fancy banners, ranking backings) есть в наборе, но пока не имеют настроенных insets — измеряйте их перед нарезкой и держите композитные элементы в одном общем масштабе.