UiCore
Обзор
UiCore рисует меню, карточки, HUD, диалоги, миникарту и карту мира в пространстве GUI ванильного клиента, без клиентского мода. Для этого используется core-шейдер (text.vsh), поставляемый в ресурспаке: всё нарисованное — это глифы шрифта, а шейдер читает ascent и цвет глифа, чтобы понять, куда поместить его на фиксированной сетке 15 на 15. Результат одинаков для каждого игрока, независимо от масштаба GUI, поля зрения или размера окна, и может появляться в любом месте экрана, а не только там, где открывается инвентарь.
UiCore заменяет два более старых инструмента: AdvancedMenus (сундучные меню) и BetterHud. Меню больше не является инвентарём-сундуком: это представление (view), стопка слоёв компонентов, которую вы создаёте в веб-панели и на которую игрок наводится головой. Та же сетка рисует модули HUD, реплики диалогов и варианты ответов.
Папка исходного кода этого расширения названа по старому расширению HUD; название расширения — UiCore. Оно работает на сборке BTC для TypeWriter, нуждается в CraftEngine для размещения ресурспака и помечено как альфа (0.1.0-alpha).
Возможности
- Представления — полные экраны с панелями, кнопками, списками, вкладками, подэкранами, подсказками, шкалами и вводом текста.
- Состояния и анимации — компоненты меняются в зависимости от фактов или прав, а представление может появляться с протиркой, цветением или затуханием.
- Модули HUD — постоянные элементы, привязанные к углу или центру, скрываемые, пока игрок читает другой экран.
- Диалоги — реплики и варианты ответов, выбираемые колёсиком прокрутки или курсором, с одной общей записью стиля.
- Кинематографический диалог — та же реплика на таймлайне кинематики.
- Миникарта и карта мира — карта местности с точками интереса, маршрутными точками и режимом съёмки.
- Таблички — трёхмерные таблички для мобов и игроков с баннерами, значками уровня и индикаторами состояния NPC.
- Баннеры и управление чатом — однострочное объявление в верхней части экрана и действие для отключения чата в определённом месте.
- Триггеры предметов — открывайте представление правым кликом по материалу.
- Интеграции — показывает данные из квестов, codex, боевого пропуска, косметики, питомцев, социальных функций, вики и RPG Core, когда эти расширения присутствуют.
Установка
- Установите CraftEngine: он размещает ресурспак, несущий шейдер, шрифты и изображения. Установите PacketEvents, если ваша сборка его не предоставляет; он используется для подавления чата, колёсика прокрутки и клавиш перемещения.
- Установите расширения TypeWriter Entity и Quest и расширение BTCMobs: они объявлены зависимостями.
- По желанию установите расширения, из которых UiCore может читать данные: Ghost, Codex, BattlePass, TinyEssentials, Cosmetics, NumericalStorage, Permissions, Pets, Friend, Party и Guild. Расширение GUI также необязательно: когда оно присутствует, UiCore читает публикуемые им состояния меню.
- Поместите JAR-файл UiCore в
plugins/Typewriter/extensions/и перезапустите сервер. - Разверните фрагмент ресурспака UiCore в пакете CraftEngine. Пакет генерируется собственными инструментами расширения (
generate-gui-pack, затемvalidate-gui-pack) и должен быть развёрнут до соответствующего ему JAR-файла, иначе все значки предметов сдвинутся на одну позицию без какой-либо ошибки.
Идентификатор ресурса Minecraft принимает только [a-z0-9._-/]. Провайдер шрифта с любым другим символом молча отклоняется клиентом, а глиф появляется как чёрный прямоугольник в верхней части экрана. Генератор пакета отказывается записывать такой путь.
Начало работы
Откройте небольшое меню от компаса.
- В веб-панели TypeWriter откройте страницу static и добавьте запись UI View. Задайте
viewIdравнымhello_menu. - Добавьте слой (
layerIdmain) и первый компонент:placement.kindCELL,column4,row6,width7,height3,paletteSURFACE,hoverPaletteBLUE_LIGHT,textHello,tooltipClick me. - В
onLeftClickсвяжите действие, например команду или сообщение. Добавьте второй компонент сnavigateToили Close UI View, чтобы выйти. - Добавьте действие Open UI View с
viewIdhello_menuлибо привяжите предмет: добавьте UI Item Trigger сmaterialCOMPASSиviewIdhello_menu. - Опубликуйте. Кликните правой кнопкой по компасу: появится экран, наведитесь головой на кнопку и кликните.
Как это работает
Представление — это список слоёв (от заднего к переднему); слой содержит компоненты; компонент указывает, где он находится, как закрашен, что показывает и что запускает клик. Три ограничения происходят от кодировки, а не от кода:
- Оттенок — это индекс. Цвет ячейки несёт её столбец, строку и индекс палитры, поэтому оттенки берутся из фиксированной именованной палитры (
SURFACE,BLUE_LIGHT,GOLD...), а не из произвольных значений hex. - Изображения дёшевы, шрифты в дефиците. Компонент можно закрасить изображением панели; любое число изображений делит один шрифт. Оттенок текста берётся из шрифта, а пакет содержит 16 оттенков текста, поэтому 17-й возвращается к белому.
- Ничего не скользит, а текст не затухает. Анимация раскрывает ячейки в определённом порядке. Текст появляется вместе со своей панелью.
Открытые представления отказываются запускаться, пока игрок падает (игрок получает сообщение). Цепочка отрисовщиков (rendererOrder у UI Configuration) определяет, какой отрисовщик обслуживает представление: GUI (этот шейдер), DIALOG, SPATIAL или CHEST.
Меню
Открытие
Представление можно открыть:
- действием Open UI View (
viewId); - командой
/ui open <viewId>из записи UI View Commands; - UI Item Trigger, который открывает представление, когда игрок кликает правой кнопкой с заданным материалом (две записи, претендующие на один материал, записываются в лог как предупреждение, и открывается только последняя);
openMaterialминикарты, который открывает карту мира.
Close UI View или /ui close закрывает его.
Раскладка и компоненты
Сетка для меню — 15 столбцов на 15 строк. placement.kind — это CELL (ячейка на сетке: column, row, width, height), MARKER (позиция от 0 до 1 поперёк области просмотра, x и y, с ограничением) или SCRIM (завеса на весь экран). Для кнопки нужно несколько ячеек, чтобы на неё было удобно наводиться.
| Поле компонента | Действие |
|---|---|
palette, hoverPalette, disabledPalette | Оттенок в покое, под курсором и пока criteria не выполняются. |
background | Изображение панели из пакета (девять частей) вместо плоского оттенка; backgroundBinding выбирает изображение по плейсхолдеру. |
text, textPalette, textAlign, textEffect | Текст, рисуемый поверх компонента. |
icon, lineIcon | Картинка материала, рисуемая перед текстом или завершающая строку. |
image, imageBinding | Изображение из пакета, вписанное в компонент с сохранением пропорций. |
label, tooltip | Текст, показываемый рядом с экраном или в точке привязки подсказки, пока курсор находится на компоненте. |
gauge | Рисует полосу по плейсхолдеру со значением от 0 до 100 (например, btcui_health_percent). |
binding | Плейсхолдер, из которого компонент берёт своё значение. |
criteria, onLeftClick, onRightClick | Условия для клика и запускаемые записи. |
navigateTo | Открывает другой экран того же представления. |
input | Просит игрока ввести значение; onInputCommands выполняются из консоли с заменой {input} и %player%. |
Экраны, списки и состояния
- Узлы (
nodes,rootNodeId) объявляют вкладки и подэкраны, каждый выбирает, какой слой заполняет какую именованную область. Заголовки формируют навигационную цепочку. - Повторы (
repeatsу слоя) рисуют окно над нумерованными источниками: элементnчитает привязку<source>.<n>.stepModePAGEлистает целое окно за жест,ITEMсдвигает на один. - Состояния (
states) меняют компоненты, пока выполняется условие: оттенок, текст, подсказку, значок, панель или видимость. Активно состояние с наивысшим приоритетом, условия которого выполняются, состояние может уточнятьparentId, а компонент адресуется по идентификатору или поcolumn:row. Состояния пересчитываются при каждой перерисовке. - Появление (
opening,openingMillis,openingFade):WIPE_DOWN,WIPE_UP,WIPE_RIGHT,WIPE_LEFT,BLOOMилиFADE. Воспроизводится только при входе в интерфейс, а не между двумя экранами.
Палитра
FRAME, SURFACE, SURFACE_LIGHT, MUTED, BLUE, BLUE_LIGHT, CYAN, TEAL, GREEN, GREEN_LIGHT, YELLOW, ORANGE, RED_DARK, RED, PURPLE, WHITE, BLACK, INK, SLATE, STEEL, STEEL_LIGHT, MIST, PAPER, FOREST, MINT, GOLD, AMBER, WINE, CORAL, VIOLET. NONE ничего не рисует.
Взаимодействие
Курсор следует за головой игрока: рысканье и тангаж проецируются на сетку и привязываются к ячейке. Игроки меняют его скорость командой /ui sensitivity <degrees>: больший угол означает более медленный курсор.
- Левый и правый клики запускают
onLeftClickиonRightClick; колёсико прокручивает списки и вкладки; Sneak — это сочетание клавиш, закрывающее представление (кроме случаев, когда фокус на списке дерева исследований). - Представление уступает миру: уход в сторону, телепортация, получение урона или открытие инвентаря закрывают его.
- Пока представление открыто, чат других игроков не показывается на экране, а серверные сообщения перерисовываются чатом UI вместо ванильного чата.
Модули HUD
Записи UI HUD используют те же слои и компоненты, что и представление, привязанные к corner (TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT, CENTRE); смещения отсчитываются от него внутрь. priority определяет, какая из двух пересекающихся групп рисуется сверху, а visibility ограничивает группу. Модули HUD автоматически приостанавливаются, пока экраном владеет представление, диалог, кинематика или карта мира.
Диалоги
UI Spoken Dialogue показывает реплику с именем говорящего, необязательным portrait, duration печати (ноль показывает сразу) и sound. UI Option Dialogue добавляет варианты ответов (options): navigation — это KEYS (колёсико прокрутки и клавиша подтверждения), CURSOR или оба (по умолчанию); timer отменяет диалог и запускает cancelTriggers; у каждого варианта есть criteria (он рисуется заблокированным или скрывается через hideWhenLocked), lockedReason, показываемый вместо подсказки, пока он заблокирован, modifiers и triggers. Обе принимают запись style; оставьте её пустой, чтобы использовать собственную серверную.
UI Dialogue Style определяет внешний вид в ячейках сетки: speech (рамка, область текста, баннер говорящего, портрет), options (окно, панель, оттенки выбранных и заблокированных вариантов, каретка и стрелки прокрутки, необязательный второй столбец) и chrome (картинка клавиши подтверждения, строка обратного отсчёта, строки letterbox). UI Spoken Cinematic помещает реплики на страницу кинематики с сегментами startFrame и endFrame.
Карты и таблички
Постоянная миникарта настраивается через Minimap Settings (worlds и excludeListedWorlds, size, blocksPerCell, borderThickness, openMaterial, maxWaypoints, worldMapAreas), а её точки — через Minimap Points of Interest. Её положение на экране задаётся в ресурспаке, а не здесь, потому что сервер не знает ни разрешения, ни масштаба GUI. Карта мира открывается правым кликом по openMaterial или командой /worldmap; обычная игра заполняет её тем, что читает миникарта, а режим съёмки намеренно наносит на карту более широкий радиус.
Таблички трёхмерны и индивидуальны для каждого зрителя. Global Nameplate рисует строки над мобами (entityTypes, btcMobsOnly, lines, viewDistance, requireLineOfSight...). Player Nameplate Banner определяет выбираемые фоны-баннеры (префикс изображения CraftEngine с частями _left, _middle и _right), а выбор игрока хранится в артефакте выбора. Nameplate Settings задаёт расстояния, бюджеты и единицу здоровья; Level Badge Settings задаёт слово, пишущееся перед уровнем (префикс по умолчанию, может быть плейсхолдером перевода). NPC Status Override помещает модель-индикатор (доступен, активен, взаимодействие...) над NPC.
Команды
| Команда | Описание |
|---|---|
/ui open <viewId> | Открывает представление. |
/ui close | Закрывает открытое представление. |
/ui sensitivity [degrees] | Показывает или задаёт размах вашего курсора в градусах. |
/ui icons [materials] | Выводит значки предметов в чат для проверки шрифта-спрайтов. |
/ui chat vanilla | Только для операторов: возвращает вам ванильный чат до отключения или повторного выполнения. |
/worldmap | Открывает или закрывает карту мира. |
/worldmap survey, forget, stats, minimap, waypoint <name>, waypoint clear, save, debug | Режим съёмки, забыть вашу карту, показать её размер, переключить миникарту, переименовать или очистить маршрутные точки, сохранить и вывести диагностику. |
/nameplates (псевдонимы /nameplate, /btcnameplates) | equip <id>, unequip, preview [id], list, toggle [on|off], а также админ-формы force-equip, force-unequip, force-preview, admin-toggle. |
Названия /ui и /worldmap берутся из полей commandName их записей. Их поле permission — это узел права по вашему выбору: пусто означает для всех. /worldmap survey, forget, save и переключатель съёмки используют surveyPermission.
Права
| Право | Что даёт |
|---|---|
permission у UI View Commands | Подкоманды /ui (пусто: для всех). |
permission и surveyPermission у World Map Command | /worldmap, а также съёмка и забывание (пусто: для всех). |
btcnameplates.command.equip, .unequip, .preview, .list, .toggle | Соответствующие подкоманды /nameplates для игроков. |
btcnameplates.command.admin.force_equip, .force_unequip, .force_preview, .toggle | Админ-подкоманды /nameplates. |
visibility.permission у компонентов и групп | Показывает или скрывает элемент для игроков без этого узла. |
Плейсхолдеры
Расширение MiniPlaceholders btcui, для компонентов, шкал и текста.
| Плейсхолдер | Возвращает |
|---|---|
<btcui_level_glyph:37> | Любое число, записанное цветными цифрами уровня из пакета. |
<btcui_global_level_glyph>, <btcui_global_level>, <btcui_global_level_badge> | Глобальный уровень в виде глифов, цифр или с настроенным префиксом. |
<btcui_global_percent>, <btcui_global_detail>, <btcui_xp_detail> | Прогресс до следующего глобального уровня и его числа. |
<btcui_health>, <btcui_health_max>, <btcui_health_percent>, <btcui_absorption> | Здоровье и поглощение. |
<btcui_food>, <btcui_food_max>, <btcui_food_percent>, <btcui_saturation> | Голод. |
<btcui_air>, <btcui_air_max>, <btcui_air_percent>, <btcui_air_gauge> | Запас воздуха; шкала пуста, пока игроку не хватает воздуха. |
<btcui_xp_level>, <btcui_xp_progress>, <btcui_xp_percent> | Ванильная полоса опыта (используется для зачарования). |
<btcui_riding>, <btcui_mount_name>, <btcui_mount_health>, <btcui_mount_health_max>, <btcui_mount_health_percent>, <btcui_mount_gauge> | Скакун. |
<btcui_underwater>, <btcui_swimming>, <btcui_burning>, <btcui_freezing> | Состояния игрока. |
<btcui_x>, <btcui_y>, <btcui_z>, <btcui_world_time>, <btcui_world_day> | Позиция и время. |
<btcui_banner>, <btcui_actionbar>, <btcui_chat:...> | Текущий баннер, экшн-бар и строки чата, рисуемые UI. |
Записи
Записей: 26, сгенерированы из исходного кода расширения.
Действия5
- Close UI ViewClose UI View
- Mute UI ChatMute UI Chat
- Open UI ViewOpen UI View
- UI BannerUI Banner
- Unmute UI ChatUnmute UI Chat
Аудитории2
- NPC Status OverrideNPC Status Override
- UI Look AudienceLooking At A Position
Кинематики1
- UI Spoken CinematicUI Spoken Cinematic
Данные сущностей1
- BTC Nameplate DataConfigure native text lines and an optional 3D attachment
Команды2
- UI View CommandUI View Commands
- World Map CommandWorld Map Command
Артефакты1
- BTC Player Nameplate Selection ArtifactStores each player's selected nameplate banner
Манифесты12
- BTC Global NameplateGlobal mob nameplate
- BTC Player Nameplate BannerPlayer nameplate banner
- Minimap PoiMinimap Points of Interest
- Minimap SettingsMinimap Settings
- UI ConfigurationUI Configuration
- UI Dialogue StyleUI Dialogue Style
- UI HUDUI HUD
- UI Item TriggerUI Item Trigger
- UI Level Badge SettingsPrefix written before every level badge
- UI Nameplate SettingsShared nameplate visibility and health units
- UI Token ShopToken Shop Catalogue
- UI ViewUI View
Устранение неполадок
Чёрные прямоугольники или «тофу» там, где должны быть текст и ячейки. Фрагмент ресурспака отсутствует, устарел или развёрнут после JAR-файла, либо путь шрифта содержит символ вне [a-z0-9._-/]. Сначала разверните пакет заново, затем соответствующий JAR и проверьте, что CraftEngine его перезагрузил.
Значки предметов показывают не тот предмет. Пакет и JAR не совпадают: символ значка — это его порядковый номер в таблице, поэтому пакет, сгенерированный после JAR, сдвигает каждый значок. Заново сгенерируйте и проверьте пакет, затем разверните оба.
Предмет открывает пустое меню. Две привязки UI Item Trigger претендуют на один материал; в логе написано est reclame par ... с числом компонентов каждой. Удалите лишнюю привязку.
names view '<id>', which no page defines. viewId, переданный действию, команде или предмету, не соответствует ни одному опубликованному UI View. У представления со статусом declared but incomplete нет слоя или компонента, которые можно было бы разрешить.
Меню не открывается в воздухе. UiCore отказывается открывать экран, пока игрок падает. Повторите на земле.
Чат пропал. UiCore рисует чат сам: открыто представление, активно Mute UI Chat либо игрок его выключил. Используйте Unmute UI Chat при выходе из места, где вы его отключили; операторы могут использовать /ui chat vanilla, чтобы проверить ванильный чат.
Жесты перестают работать. Gesture decoding unavailable в логе означает, что PacketEvents не удалось запустить: колёсико прокрутки и клавиши перемещения теряются, но клики по-прежнему работают.
Связанные расширения
- TinyEssentials — данные вики, домов и вкладок, показываемые представлениями.
- RPG Core — панели прогрессии, хранилища и гардероба используют UiCore.
- Codex, BattlePass, Cosmetics, Pets — экраны данных.
- Party, Friend, Guild — социальные панели.
- GUI — сундучные меню; UiCore использует публикуемые им состояния меню.