Quest Codex
Обзор
Quest Codex даёт игрокам книгу квестов. Главное меню перечисляет категории (Основной сюжет, Побочные квесты, Подземелья...), каждая категория открывает список своих квестов, а клик по активному квесту включает его отслеживание. Сами квесты — это те, которые вы создаёте с помощью официального расширения TypeWriter Quest: Quest Codex только упорядочивает и отображает их.
Каждый экран вы рисуете сами. Меню — это раскладка расширения GUI, в которую вы помещаете предметы-маркеры: маркер QUEST_SLOT заменяется квестами игрока, маркер CATEGORY_SLOT — категориями, а маркер SORT_SLOT — кнопкой сортировки. Всё вокруг маркеров (рамки, заголовки, кнопки, прокрутка, страницы) — это обычное содержимое GUI.
Помимо меню, расширение добавляет отслеживание нескольких квестов, переживающее повторные подключения, восстановление прерванного диалога или кинематики, клиентские GPS-маршрутные точки и точки на полосе локатора, пользовательские достижения Minecraft, выдаваемые со страницы, и значки квестов на BlueMap.
Возможности
- Категории — вложенные категории с порядком, значком, видимостью и критериями завершения, а также сообщениями для каждого статуса.
- Назначение квестов — помещайте квесты в категорию, задавайте их порядок и переопределяйте значок, название, описание (lore) и видимость для каждого статуса.
- Пулы раскладок — вы проектируете каждое меню с помощью раскладок GUI; codex заполняет маркеры
QUEST_SLOT,CATEGORY_SLOT,TRACKED_QUEST_SLOTиSORT_SLOT. - Кнопка сортировки — переключает режимы Все, Не начатые, В процессе и Завершённые, с подписью, значком и описанием для каждого режима.
- Мультиотслеживание — отслеживайте несколько активных квестов одновременно; последний из них — основной квест официального HUD-трекера.
- Меню отслеживаемых квестов — отдельное меню квестов, которые отслеживает игрок.
- Маршрутные точки — слои текста, блока и маяка, существующие только в пакетах и указывающие на цель, позицию или сущность, а также вариант для ванильной полосы локатора.
- Восстановление взаимодействий — восстанавливает активный диалог или кинематику после отключения.
- Достижения — определяйте вкладки достижений Minecraft в панели и выдавайте их действием.
- Значки BlueMap — размещайте на BlueMap значок квеста со всплывающим окном.
Установка
- Установите TypeWriter на сервер Paper или Folia вместе с его официальным расширением Quest, которое определяет квесты, отображаемые Quest Codex.
- Установите расширение GUI (версии 0.18 или новее).
- По желанию: установите PacketEvents (он уже требуется для TypeWriter) для маршрутных точек и BlueMap для значков на карте.
- Скачайте JAR-файл Quest Codex из релизов GitHub (кнопка в сводной панели выше), поместите его в
plugins/Typewriter/extensions/и перезапустите сервер. - Выдайте игрокам право
typewriter.codex.open, см. «Права» ниже.
Начало работы
Создайте журнал квестов с одной категорией:
- На static-странице добавьте запись Quest Codex Tracking Data. Здесь сохраняются отслеживаемые квесты.
- На странице manifest добавьте запись Quest Codex Global Settings. Задайте
trackingArtifactравным артефакту и проверьтеmaxTrackedQuestsи звуки. - Добавьте запись Quest Category с
categorymain_quests,title, например<gold>Main Story, иicon. - Добавьте запись Quest Assignment с
categorymain_questsи вашими квестами вquestRefs.ordersнеобязателен. - Создайте две записи Open GUI, используемые только как контейнеры для раскладок. В первой,
main_gui, добавьте раскладкуsimpleсidmain, задайтеmainLayoutIdравнымmain,guiTypeравнымCUSTOMиsizeравнымSIZE_36. Добавьте предмет сbuttonPrefixcodex_button:,buttonTypeCATEGORY_SLOT,x1,y1,count7 иdirectionright. Во второй,quests_gui, сделайте то же самое с маркеромQUEST_SLOTи добавьте предметCLOSEв нижнем ряду. - Добавьте Category Menu с пустым
category,rows4иmenu, равнымmain_gui. Это главное меню. - Добавьте второе Category Menu с
categorymain_quests,rows4иmenu, равнымquests_gui. - Опубликуйте (Publish), затем выполните в игре
/tw codex. Кликните по категории, затем по активному квесту, чтобы начать его отслеживание.
Инвентарь строится по rows у Category Menu, а не по size у Open GUI. Если они различаются, слоты ниже меньшей высоты отбрасываются, и консоль предупреждает вас об этом при запуске.
Один слот-маркер показывает один квест. Используйте count, direction, gap и repeatY, чтобы растянуть маркер на сетку: count 7, direction right и repeatY 3 дают 21 слот для квестов. Без direction маркер остаётся одним слотом. Квесты заполняют маркеры в порядке чтения, а следующая страница квестов открывается кнопкой PAGE_NEXT.
Как это работает
При запуске расширение загружает категории, назначения и меню. Когда игрок открывает меню, оно переписывает каждый маркер раскладки в пронумерованный маркер (QUEST_SLOT#0, QUEST_SLOT#1, ...) до разбора раскладки, поэтому маркеры ведут себя как обычные слоты внутри раскладок scrollable, paginated и frame. При отрисовке каждый маркер заменяется n-м квестом или категорией.
Меню
Какие записи составляют меню
Category Menu — это запись, которую вы открываете. Её поле menu указывает на запись Open GUI, которая предоставляет только пул раскладок, главную раскладку, тип окна и звуки. Не запускайте этот Open GUI сами.
category у Category Menu | Меню | Маркер, который оно должно содержать |
|---|---|---|
| пусто | Главное меню со списком корневых категорий | CATEGORY_SLOT |
| название категории | Квесты этой категории | QUEST_SLOT |
@tracked | Квесты, которые отслеживает игрок | TRACKED_QUEST_SLOT |
Каждой определённой категории нужно Category Menu, иначе её открытие ничего не делает, и консоль сообщает об этом при запуске.
Маркеры и кнопки
Задайте buttonPrefix равным codex_button:, а buttonType равным одному из значений:
buttonType | Назначение |
|---|---|
CATEGORY_SLOT | Значок категории с её заголовком, прогрессом {completed}/{total}, подсказкой о клике и сообщением о статусе. Клик открывает категорию. |
QUEST_SLOT | Квест. Значок зависит от его статуса, название и описание берутся из квеста, назначения и записей Quest Lore. Клик по активному квесту включает или отключает его отслеживание. |
TRACKED_QUEST_SLOT | Отслеживаемый квест в меню @tracked. Пустой слот сохраняет ваш собственный предмет и остаётся неактивным, поэтому это ваше пустое состояние. |
SORT_SLOT | Кнопка сортировки. Настройте каждый режим в sortDisplay у Category Menu. |
PAGE_NEXT, PAGE_PREV | Переход на следующую или предыдущую страницу квестов или категорий. |
SCROLL_UP, SCROLL_DOWN, SCROLL_LEFT, SCROLL_RIGHT | Прокрутка меню. |
BACK | Возвращает в главное меню, если оно есть, иначе к записи mainMenuTrigger, иначе в предыдущее меню, иначе закрывает. |
CLOSE | Закрывает меню. |
SORT | Кнопка сортировки, размещённая как обычный навигационный слот. |
Кнопки навигации сохраняют настроенные вами предмет, название и описание; встроенная стрелка, барьер или воронка используются только тогда, когда у слота нет предмета.
Размещайте маркеры в раскладках simple, принадлежащих Open GUI, на который указывает menu. Маркеры в раскладках других типов или в раскладках общего шасси не нумеруются и остаются скрытыми.
Шасси, представления и вкладки
Чтобы построить книгу квестов со вкладками, задайте у Category Menu baseMenuId равным общей оболочке Open GUI и добавьте views, defaultViewId и breadcrumbSeparator, точно как в Представления, вкладки и наследование. pushHistoryOnViewSwitch заставляет «Назад» возвращать на предыдущую вкладку. Шасси, у корневой раскладки которого есть вариант _extended, автоматически получает холст из десяти рядов.
Отображение квеста
- Значок квеста по умолчанию — книга, часы или изумруд для не начатого, выполняемого и завершённого квеста соответственно. Переопределите его для каждого статуса в Quest Assignment (
notStartedItem,inProgressItem,completedItem). notStartedName,inProgressNameиcompletedNameзаменяют название квеста, а соответствующие поля описания добавляют строки. Скройте квест для каждого статуса с помощьюhideWhenNotStarted,hideWhenInProgressиhideWhenCompleted.- Запись Quest Lore добавляет строки для каждого статуса к квесту, в одной категории или во всех.
- Порядок квестов определяется сначала
orders, затем порядком вquestRefs. Категория также перечисляет квесты своих подкатегорий. - Главное меню перечисляет только категории верхнего уровня (без
parent). Подкатегория открывается командой/tw codex <category>или кнопкой, выполняющейcodex:open <category>.
Конфигурация
Запись Quest Codex Global Settings содержит параметры, не привязанные к меню. Создавайте только одну; без неё используются значения по умолчанию.
- Звуки —
soundOnOpen,soundOnSwitch,soundOnClick,soundOnTrack,soundOnUntrack. - Отслеживание —
multiTrackingEnabled,maxTrackedQuests(не менее 1) иtrackingArtifact. Без артефакта отслеживаемые квесты хранятся только в памяти, и консоль предупреждает об этом при запуске. Артефакт — это файл, у которого должен сохраняться егоartifactId, как только им начинают пользоваться игроки. - Восстановление —
recoveryEnabled,recoveryArtifact,recoveryRetentionSeconds(от 10 до 86400) иrecoveryRestoreDelayTicks(от 1 до 20). Когда игрок выходит во время диалога или кинематики, снимок сохраняется и восстанавливается вскоре после возвращения игрока. Без артефакта восстановление отключено. - Сообщения —
nowTrackingMessage,stoppedTrackingMessage,questInactiveMessage,questCompletedMessage,trackingLimitMessage({quest},{max}),categoryProgressMessage({completed},{total}) и подсказки в описаниях категорий и квестов. - Подписи навигации —
navLabelsзадаёт название каждой встроенной кнопки (next,previous,up,down,left,right,back,close,sort). Используется только тогда, когда у помеченного слота нет собственного предмета: слот с предметом сохраняет своё название и лор. - Кнопка сортировки —
sortTextsзадаёт подпись каждого режима сортировки (allLabel,notStartedLabel,activeLabel,completedLabel) и строку лораhint. Category Menu, у которого вsortDisplayдля режима заданlabelилиlore, сохраняет свои. - Заголовки меню —
mainMenuTitleиtrackedQuestsTitle— заголовки, которые используются, когда у соответствующего Category Menu пустойtitle. - Ошибка команды —
unknownCategoryMessage— ошибка, которую/tw codex <category>показывает для несуществующей категории ({category}). - Запасной вариант главного меню —
mainMenuTriggerзапускается, когда нет главного Category Menu, например это ваш собственный Open GUI, кнопки которого выполняютcodex:open <category>.
Маршрутные точки и полоса локатора
Quest Codex Waypoint — это запись-аудитория: подключите её к фильтру аудитории, чтобы выбрать, кто её видит. Её target — это фиксированная позиция, находимая цель, отслеживаемая цель (выбор HIGHEST_PRIORITY, FIRST, CLOSEST, ALL или ONE_PER_QUEST) или сущность. Её layers сочетают текстовый слой (плейсхолдеры {icon}, {distance}, {distance_m}, {distance_km}, {elevation}, {direction}, {vertical_direction}, {target}, {world_name}, {height_diff} и {eta}), слой блока и слой маяка. displayMode — это HUD_LOCKED (по умолчанию), WORLD_DIRECTIONAL, TARGET_ANCHORED или ADAPTIVE, и каждый слой может переопределить его. Всё отправляется пакетами; ни одна сущность не сохраняется в мире.
Quest Codex Locator Bar показывает те же цели точками на ванильной полосе локатора, для чего нужен Minecraft 1.21.6 или новее, и сочетается с трёхмерной маршрутной точкой.
Достижения и BlueMap
- Advancement Definition описывает достижение. Достижение без
parentстановится вкладкой. Они записываются при запуске в датапакquestcodex_advancementsв папке мира, а сервер перезагружает свои данные, когда содержимое изменилось, поэтому для нового определения нужен перезапуск. Достижение зарабатывается только действием Grant Advancement. - BlueMap Icon при запуске размещает маркер с подписью и всплывающим окном на картах BlueMap своего мира. В
descriptionтекст<objectives>заменяется целями квеста.
Команды
Все команды — это подкоманды /typewriter, обычно вводимые как /tw, и они требуют typewriter.codex.open.
| Команда | Описание |
|---|---|
/tw codex | Открыть главное меню: Category Menu с пустым category, иначе запись mainMenuTrigger. |
/tw codex tracked | Открыть меню отслеживаемых квестов. |
/tw codex <category> | Открыть категорию. Автодополнение перечисляет определённые категории. |
Кнопки меню также могут выполнять эти внутренние команды: codex:open <category>, codex:tracked, codex:quest <quest_id> и codex:nav <action>. Используйте codex:open и codex:tracked в кнопках своих меню GUI.
Права
| Право | Что даёт |
|---|---|
typewriter.codex.open | Все команды /tw codex. Расширение объявляет его со значением по умолчанию только для операторов, и оно появляется в вашем плагине прав: выдайте его группам, которым разрешено использовать /tw codex. |
Открытие меню из действия Category Menu или кнопкой меню права не требует.
Плейсхолдеры
Плейсхолдеры PlaceholderAPI с расширением typewriter. Им нужен игрок.
| Плейсхолдер | Возвращает |
|---|---|
%typewriter_total_quests% | Число квестов во всех категориях. |
%typewriter_total_completed%, %typewriter_total_in_progress%, %typewriter_total_not_started% | Число квестов в каждом статусе для игрока. |
%typewriter_total_progress% | Завершённые из общего числа, например 15/42. |
%typewriter_category_<name>% | Число квестов в категории. |
%typewriter_category_<name>_completed%, _in_progress%, _not_started% | Квесты категории в этом статусе. |
%typewriter_category_<name>_progress% | Завершённые из общего числа для категории. |
%typewriter_codex_tracked_count%, _limit% | Число отслеживаемых квестов и максимум. |
%typewriter_codex_tracked_multi_enabled%, _has_any% | true или false. |
%typewriter_codex_tracked_ids%, _names%, _names_lines% | Идентификаторы или названия отслеживаемых квестов через запятую или по одному в строке. |
%typewriter_codex_tracked_primary_id%, _primary_name% | Основной квест, показываемый официальным трекером. |
%typewriter_codex_tracked_has_<quest_id>% | Отслеживается ли этот квест. |
%typewriter_codex_tracked_<n>_id%, _name%, _status%, _primary% | Сведения о n-м отслеживаемом квесте, начиная с 1. Пусто, если его нет. |
%typewriter_codex_tracked_<n>_objective_count%, _objectives%, _objectives_lines%, _priority% | Видимые цели n-го отслеживаемого квеста. |
<name> — это название категории, сопоставляемое без учёта регистра. Подробнее: Плейсхолдеры, Команды и Права.
Записи
Записей: 12, сгенерированы из исходного кода расширения.
Действия2
- Category MenuCategory Menu Configuration
- Grant AdvancementGrant Advancement
Аудитории2
- Quest Codex Locator BarQuest Codex Locator Bar
- Quest Codex WaypointQuest Codex Waypoint
Артефакты2
- Quest Codex Recovery ArtifactQuest Codex Recovery Data
- Quest Codex Tracking ArtifactQuest Codex Tracking Data
Манифесты6
- Advancement DefinitionAdvancement Definition
- Bluemap IconAdds an icon to BlueMap for a specific quest
- Quest AssignmentQuest Assignment to Category
- Quest CategoryQuest Category
- Quest CodexQuest Codex Global Settings
- Quest LoreQuest Additional Lore
Устранение неполадок
/tw codex ничего не делает. Нет Category Menu с пустым category и нет mainMenuTrigger. Консоль записывает Main menu could not open с указанием причины. Для категории создайте Category Menu, у которого category равен category у Quest Category.
Меню открывается пустым. Консоль сообщает об этом при запуске: ни у одного слота указанного Open GUI нет маркера, нужного меню (CATEGORY_SLOT, QUEST_SLOT или TRACKED_QUEST_SLOT), menu пуст или не является Open GUI, пул раскладок пуст либо mainLayoutId в нём отсутствует. У маркеров должен быть buttonPrefix codex_button:.
Не хватает слотов в нижних рядах. rows у Category Menu меньше, чем size у Open GUI. Задайте для обоих одинаковое число рядов.
Квесты расположены вплотную друг к другу, а не через один пустой слот. gap — это шаг: 1 означает соседние слоты, а 2 оставляет один пустой слот. Меню, написанные до Quest Codex 0.3.0, использовали gap как интервал, поэтому удвойте значение. Столкновение с декорацией сообщается предупреждением Slot overlap.
Несколько маркеров накладываются на одну ячейку. У маркера задан count, но нет direction, либо позиция выходит за пределы сетки. Задайте direction.
Квеста нет в категории. Квест скрыт опцией hideWhen... для его текущего статуса, его отфильтровывает текущий режим сортировки либо назначение не смогло его определить (Quest '...' could not be resolved в консоли).
Отслеживаемый квест пропадает после перезапуска. trackingArtifact пуст или его artifactId изменился. Квест, который больше не активен, удаляется из списка отслеживаемых.
Маршрутные точки не отображаются. Запись маршрутной точки должна находиться внутри аудитории, которой соответствует игрок, квест должен отслеживаться, а цель должна быть находимой. Текстовый слой с {icon} остаётся пустым, пока не задан icon.
Новое достижение неизвестно серверу. Определения записываются при запуске; перезапустите сервер после добавления. Определение, значок которого не является предметом, пропускается с предупреждением.