Карточки интерфейса

Весь ваш двумерный интерфейс — это карточка: HUD, меню, кнопки, подписи, диалоги. Не 3D-текст на плоскости и не текстура со словами.

Карточки верстаются как обычный интерфейс, перед 3D-видом, поэтому остаются чёткими на любом расстоянии и при любом размере экрана. Текст в карточке читается; текст на плоскости в мире зависит от милости камеры.

Карточка — это ресурс, и вы прикрепляете её к объекту.

Два способа разместить

Overlay заполняет экран. Это ваш HUD, меню, окно диалога.

Anchored прикалывает карточку к экранной позиции объекта — имя над персонажем, цена над товаром.

Привязанная карточка не уменьшается с расстоянием

Она остаётся того размера, каким вы её нарисовали, и скрывается, когда её объект уходит за камеру. Это подпись, прикреплённая к чему-то, а не объект в мире. Если нужно что-то, что уменьшается по мере удаления, используйте 3D-текст.

Что можно собрать

Все привычные строительные блоки на месте:

container · text · image · gif · video · separator · grid · gallery
pager · tabs · state · indicator · slider · input · select · switch

Компонента «кнопка» нет — и это нормально

Кнопка — это text или container с фоном, отступами, рамкой и действием. Звучит как лишняя работа, а на деле наоборот: вы получаете ровно ту кнопку, которую просит дизайн, вместо того чтобы бороться со стандартной.

Для всего повторяющегося (строка списка, чип, карточка в галерее) соберите шаблон один раз и переиспользуйте.

У карточки может быть несколько собственных экранов, и она переключает их вообще без участия сцены. Именно так правильно делать панель с вкладками или многошаговый диалог: сцене об этом знать не нужно.

Пользовательские компоненты и сторонние расширения вроде Lottie отрисованы не будут.

Как заставить карточку что-то делать

У карточки есть собственные переменные, и ими она меняет саму себя: показать и скрыть, поменять текст, переключить экран, запустить таймер. Всё, что касается только интерфейса, должно оставаться внутри карточки.

Когда ей нужно дотянуться до сцены, есть три способа, по возрастанию возможностей:

Способ	Для чего
Встроенное действие карточки	только состояние интерфейса — вкладка, переключатель, таймер
Шаг сцены в действии	запуск шага сцены без кода: сменить сцену, проиграть анимацию
Именованное действие плюс скрипт	игровая логика

Действие на карточке также поднимает обычное событие, которое идёт вверх по иерархии, так что событие на сцене может поймать нажатие из любой карточки внутри неё — по имени или вообще любое.

Общение со скриптом

Скрипт может читать переменные карточки, писать их и слушать нажатия:

const ui = ctx.getDivKit(entity);

ui.set('score', (v) => v + 1);
ui.subscribe('lives', (v) => {
  /* изменился показатель */
});
ui.onAction('restart', () => {
  /* нажата кнопка перезапуска */
});

Вот шаблон, который стоит усвоить: состояние игры живёт в скрипте, а карточка его показывает. Не наоборот.

Как указывать на изображения и видео

Внутри карточки указывайте на ресурс проекта, а не на URL. Ссылки работают и внутри выражений, так что выбор изображения по условию ведёт себя так, как вы и ожидаете.

Прежде чем садиться проектировать

• Карточка показывается, только пока её сцена активна, поэтому интерфейс не протекает между сценами.
• Скриншот 3D-вида не будет содержать ваши карточки. Проверяйте интерфейс в предпросмотре.
• Переменные карточки не общие для участников и сбрасываются при перезагрузке. Всё, что должно быть общим или пережить перезагрузку, — в скрипт.
• Визуальный редактор показывает отобранный набор свойств, но сохраняет написанные вручную раскладки нетронутыми: они переживают редактирование, просто у них нет панели свойств.

---

Дальше: Графы материалов — когда стандартных материалов не хватает.