Codex

Кодекс открытий с разблокируемыми категориями, книгами рецептов и коллекционными фрагментами.

Приватныеv0.0.3Квесты и сюжет

ТребуетсяTypeWriter0.9BasicGUIQuestнеобязательноQuest Codexнеобязательно

Создано для сети BornToCraft. Это расширение описано для справки и не распространяется.

Поддержка

Обзор

Codex — это журнал открытий. Вы определяете категории (бестиарий, книга знаний, список мест) и предметы внутри них, а каждый предмет или категория открывается по criteria TypeWriter: факту, статусу квеста, праву — чему угодно, что может проверить criteria. Закрытые записи остаются видимыми со своим описанием (lore), поэтому игроки видят, что ещё предстоит открыть. Можно также добавлять категории рецептов, которые показывают ванильный рецепт крафта в небольшом виде верстака, когда игрок кликает по рецепту.

Расширение также содержит систему фрагментов: коллекционные предметы, которые игроки подбирают, сгруппированные в наборы, с последовательностью, запускаемой, когда собрано достаточно фрагментов. Всё — записи TypeWriter, создаваемые в веб-панели, а меню отрисовываются расширением GUI.

Расширение работает на сборке BTC TypeWriter (BTC Core, Paper/Folia) и документировано здесь для справки.

Возможности

• Категории открытий — группируйте предметы, с вложенными подкатегориями через parentCategory.
• Открытие по criteria — категории и предметы открываются по criteria; закрытые могут показывать собственный предмет и описание.
• Счётчики завершённости — открытые, закрытые, общее число и процент доступны в значках категорий и как плейсхолдеры.
• Книги рецептов — показ ингредиентов и результата ванильного рецепта по его recipeKey.
• Триггеры открытия — запуск триггеров, когда категория, предмет или рецепт открывается для игрока в первый раз, с сохранением, чтобы они никогда не срабатывали дважды.
• Четыре макета меню — PAGINATED, SCROLLABLE, FRAME или SIMPLE для каждой категории.
• Глобальное меню кодекса — макет GUI, где значки категорий размещаются маркерами и наследуют общее шасси меню.
• Коллекционные фрагменты — подберите предмет, чтобы собрать фрагмент, с триггером при завершении группы.
• Команда и действие открытия — открывайте категорию из команды, диалога или любого триггера.

Установка

1. Установите расширение GUI (GuiAndDialogs в сборке BTC) и расширение TypeWriter Basic. Без них Codex не загрузится.
2. По желанию установите расширение Quest и расширение Quest Codex, если хотите открывать записи по прогрессу квестов.
3. Положите JAR-файл Codex в plugins/Typewriter/extensions/ и перезапустите сервер.
4. Добавьте артефакт Codex Unlock, если используете триггеры открытия, и артефакт Fragment Storage, если используете фрагменты.

Быстрый старт

Создадим категорию «Лесные существа» с двумя предметами:

1. В веб-панели TypeWriter откройте страницу manifest и добавьте запись Discovery Codex Category.
2. Задайте category уникальный идентификатор, например forest_creatures, title, rows (например 3) и icon.
3. Задайте itemSlotRange — слоты для заполнения, например 10-16 (нумерация начинается с 1), и выберите guiLayout.
4. В items добавьте предмет: entryId wolf, item, показываемый, когда он открыт, lockedItem, показываемый до этого, а в criteria — факт, означающий «игрок видел волка». Добавьте unlockedLore и lockedLore.
5. Добавьте на страницу static или sequence запись с действием Open Discovery Codex, задайте definition равным вашей категории и запустите её из NPC, предмета или варианта диалога. Также можно использовать /tw codex open forest_creatures.
6. Опубликуйте и откройте кодекс. Предметы, чьи criteria не выполнены, остаются закрытыми.

Предметы без criteria

Предмет с пустым списком criteria всегда открыт. Добавьте criteria каждому предмету, который хотите скрыть.

Как это работает

Категория показывает либо свои подкатегории и категории рецептов (когда другие категории называют её parentCategory), либо собственные предметы. Criteria категорий и предметов вычисляются каждый раз, когда меню строится для игрока.

Меню

Каждая Discovery Codex Category — это отдельное меню-инвентарь с rows рядами (от 1 до 6). Предметы размещаются в слотах itemSlotRange (например 1-25, отсчёт с 1) либо от startSlot с заполнением по рядам или столбцам. У кнопок есть значения по умолчанию: предыдущая страница в слоте 0, следующая страница в слоте 8, информация в слоте 4 и «назад» в слоте 44. По умолчанию они используют стрелки и книгу и могут быть заменены через previousButton, nextButton, infoButton и backButton. Кнопка «назад» появляется только тогда, когда категория была открыта из родительской. Предмет background заполняет все свободные слоты.

Поле guiLayout выбирает, как предметы располагаются, когда не помещаются на одну страницу: PAGINATED (кнопки страниц), SCROLLABLE (кнопки прокрутки), FRAME (один фрейм на ряд) или SIMPLE (всё на одном экране).

В названии и описании значка категории (iconName, iconLore, lockedIconLore) можно использовать {unlocked}, {locked}, {total} и {percent}, которые заменяются, когда значок показывается в родительской категории или в глобальном меню. Остальные поля описаний (предметы, информационная и навигационные кнопки) показываются как написано, даже если в их справке перечислены плейсхолдеры.

Конечный предмет, чей entryId совпадает с entryId записи Recipe Category, открывает вид рецепта по клику. Вид рецепта показывает сетку крафта в craftingGridSlots и результат в resultSlot; рецепт, не зарегистрированный на сервере, показывает предмет-барьер с названием «Recipe not found».

Действие Codex Global Menu открывает хаб, построенный из пула макетов GUI. Разместите маркеры codex_button:CODEX_CATEGORY (с count, gap и direction для повторения), и каждый маркер будет заполнен одной категорией верхнего уровня, отсортированной по order. Категория без подходящего маркера не показывается, а маркер без категории остаётся пустым. CODEX_BACK возвращает назад, а CODEX_INFO, CODEX_PAGE_NEXT и CODEX_PAGE_PREV в этой версии — просто декоративные предметы.

Маркеры CODEX_RECIPE показывают рецепты: N-й маркер в порядке появления в макете (как у CODEX_CATEGORY) показывает иконку N-го рецепта. Рецепты всех Recipe Categories собираются в один плоский список: категории отсортированы по order, рецепты идут в порядке своего списка. Клик по разблокированному рецепту открывает его подробный вид. Если рецептов больше, чем маркеров, лишние рецепты не показываются; если маркеров больше, чем рецептов, лишние маркеры остаются пустыми.

Расстояние между маркерами

В маркерах count gap — это шаг, а не отступ: 1 размещает слоты рядом, а 2 оставляет между ними один пустой слот. Codex использует общую формулу GUI. Это то же правило, что действует для маркеров Quest Codex начиная с Quest Codex 0.3.0, поэтому макет, скопированный из старого меню Quest Codex, может потребовать удвоить gap. Справочник по макетам смотрите в расширении GUI.

Сами меню категорий могут открываться внутри общего шасси, когда задан baseMenuId (используйте rows, равное 3 или меньше, чтобы они помещались в область содержимого). Расширение UiCore также может отображать кодекс: его экран Codex распределяет категории верхнего уровня по четырём вкладкам (Bestiary, Items, Places и Fragments), ища ключевые слова вроде fragment, place, region, item или recipe в идентификаторе и названии категории, а всё остальное помещает в Bestiary.

Конфигурация

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

• Codex Unlock запоминает, какие триггеры открытия уже сработали для каждого игрока.
• Fragment Storage запоминает фрагменты, собранные каждым игроком, по группам.

Команды

Команда	Описание
/tw codex open <category> [targets]	Открывает категорию с этим идентификатором category для вас или выбранных игроков. Псевдоним: /tw dcx open.

У команды нет собственной проверки прав, кроме доступа к команде TypeWriter. Категория, чьи criteria не выполнены, отвечает «This codex is locked», а неизвестный идентификатор — «Unknown category».

Расширение также регистрирует внутреннюю команду /codexmenu, используемую кликами в меню (category, recipecat, recipe). Она работает только для игроков, и вводить её вручную не предполагается.

Плейсхолдеры

Это теги MiniPlaceholders расширения discoverycodex, доступные в любом тексте MiniMessage с поддержкой плейсхолдеров. Замените cat на идентификатор category, а item — на entryId предмета. Идентификаторы могут содержать подчёркивания.

Плейсхолдер	Возвращает
<discoverycodex_category_unlocked:cat>	Число открытых предметов в категории для игрока.
<discoverycodex_category_total:cat>	Число предметов в категории.
<discoverycodex_category_locked:cat>	Число закрытых предметов для игрока.
<discoverycodex_category_percent:cat>	Процент открытых предметов, от 0 до 100.
<discoverycodex_category_name:cat>	Название записи категории.
<discoverycodex_item_unlocked:item>	true или false для этого предмета.

Записи

Записей: 10, сгенерированы из исходного кода расширения.

Действия2

• Codex Global MenuOpen a codex global menu
• Discovery Codex OpenOpen a discovery codex category

Артефакты2

• Codex Unlock ArtifactStores which codex unlock triggers already fired for each player
• Fragment ArtifactStores player fragment collection data

Манифесты6

• Discovery Codex CategoryDefines a discovery codex category
• Discovery Codex Recipe CategoryDefines a discovery codex recipe category
• Fragment Collection ConfigGlobal fragment collection settings
• Fragment DefinitionA collectible fragment piece definition
• Fragment GroupA set of fragments to collect together
• Treasure Hunt DefinitionA treasure hunt with progressive hints and compass guidance

Устранение неполадок

Расширение не загружается. Codex требует расширения Basic и GUI (GuiAndDialogs). Проверьте журнал запуска TypeWriter на предмет отсутствующей зависимости.

Триггеры открытия никогда не срабатывают. В логе написано «No CodexUnlockArtifactEntry configured: skipping unlock triggers». Добавьте один артефакт Codex Unlock на опубликованную страницу. Без него триггеры намеренно пропускаются, чтобы награды не выдавались повторно после каждого перезапуска.

Триггеры открытия сработали один раз и больше не срабатывают. Так и задумано: каждый триггер срабатывает один раз на игрока, а запись хранится в артефакте. Чтобы проверить снова, используйте нового игрока или удалите его данные из артефакта.

Предметы попадают не в те слоты или последний слот пуст. itemSlotRange считает с 1 (1-25 означает слоты с 0 по 24 инвентаря). Слоты за пределами размера меню игнорируются, а предметы сверх числа слотов уходят на следующую страницу.

Рецепт показывает «Recipe not found». recipeKey должен быть ключом с пространством имён рецепта, зарегистрированного на сервере, например minecraft:iron_pickaxe. Рецепты, добавленные другими плагинами, используют собственное пространство имён.

Фрагмент не собирается. Игрок должен подобрать предмет: он должен совпадать с customItem (или displayItem, если customItem пуст), а в логе не должно быть «No FragmentArtifactEntry found». Добавьте артефакт Fragment Storage. Уже собранный фрагмент повторно не расходуется.

Группа никогда не завершается. requiredCount по умолчанию равно 0, что означает каждый фрагмент из списка fragments; число больше длины списка ограничивается длиной списка. groupId группы должен быть тем же текстом, что и fragmentGroup её фрагментов.

Маркеры в глобальном меню стоят через один слот. gap — это шаг, поэтому используйте gap 2, чтобы оставить один пустой слот между маркерами.

Связанные расширения

• GUI — движок меню, макеты и маркеры.
• Quest Codex — меню квестов; Codex является необязательным дополнением.
• UiCore — может отображать кодекс в собственном интерфейсе.