Ageratum

Ageratum

Мод-справочник для Minecraft NeoForge, созданный, чтобы давать внутриигровые руководства для других модов. Ageratum предлагает богатый рендеринг Markdown, локализацию i18n и расширяемую систему пользовательского синтаксиса и компонентов.

Документация

Возможности

Базовая поддержка Markdown

✅ Блочные элементы

• Заголовки ATX (# ~ ######) и заголовки Setext (подчёркиванием)
• Абзацы и переносы строк
• Упорядоченные, неупорядоченные списки и списки задач (многоуровневая вложенность)
• Цитаты (многоуровневая вложенность)
• Блоки кода с ограждением (обратные кавычки и тильды) и блоки кода с отступом
• Горизонтальные линии
• Таблицы с настройкой выравнивания
• Изображения (ссылки внутри пространства имён)

✅ Строчные элементы

• жирный, курсив, зачёркнутый
• Строчные фрагменты кода (поддержка нескольких обратных кавычек)
• Ссылки и автоссылки
• Поддержка экранирующих символов
• Пользовательские теги цвета
• События наведения и клика (теги `и`)

✅ Продвинутые возможности

• Определения ссылок и синтаксис ссылок по определению
• Автоматическое разворачивание ссылок
• Номера строк в блоках кода
• Выравнивание столбцов таблицы (по левому краю/по центру/по правому краю)

Интернационализация (i18n)

• Документы организованы по ageratum/<language_code>/ (например, en_us, zh_cn)
• По умолчанию используется en_us, если локализованная версия отсутствует
• Полная поддержка многобайтовых символов (китайский, японский и т. д.)

Синтаксис расширений

Два блочных синтаксиса расширений для пользовательских компонентов:

1. Синтаксис с двоеточиями

::: info
Это информационное окно.
:::

::: tip
Это подсказка.
:::

::: warning
Это предупреждение.
:::

::: danger
Это опасное предупреждение.
:::

2. Синтаксис с тегами

<namespace:component key="value" param=123>
Содержимое блока поддерживает синтаксис Markdown.
</namespace:component>

<namespace:component/>
Самозакрывающаяся форма без содержимого.

Пространство имён можно опустить (по умолчанию ageratum:).

Встроенные компоненты расширения

• ageratum:info — синий информационный блок
• ageratum:tip — зелёный блок с подсказкой
• ageratum:warning — оранжевый блок предупреждения
• ageratum:danger — красный блок опасности

События наведения и клика

Поддерживается интерактивный текст, позволяющий игрокам наводить курсор для подсказок или кликать для выполнения действий.

События наведения (``)

Показывать текст подсказки при наведении на текст:

<hover type="SHOW_TEXT" data="This is the tooltip">Hover over me</hover>

Поддерживаемые типы:

• SHOW_TEXT — показать подсказку с обычным текстом (data — содержимое подсказки)

События клика (``)

Выполнять действие при клике на текст:

<click type="OPEN_URL" data="https://example.com">Click to open link</click>
<click type="COPY_TO_CLIPBOARD" data="Text to copy">Click to copy</click>
<click type="SUGGEST_COMMAND" data="/say hello">Click to suggest command</click>

Поддерживаемые типы:

• OPEN_URL — открыть URL (data — полный URL)
• COPY_TO_CLIPBOARD — скопировать текст в буфер обмена (data — текст для копирования)
• SUGGEST_COMMAND — предложить команду в чате (data — текст команды)

Комбинирование стилей

Можно комбинировать несколько стилей в одном тексте:

<hover type="SHOW_TEXT" data="This is a tooltip"><click type="OPEN_URL" data="https://example.com">Click and hover on me!</click></hover>

Компонент рецепта (``)

Используйте расширение recipe, чтобы отображать рецепты прямо внутри документов Markdown:

<recipe id="minecraft:acacia_boat"/>

• id: обязательный, ResourceLocation целевого рецепта
• Встроенная поддержка: RecipeType.CRAFTING (рецепты верстака)
• Поведение отрисовки: каждый слот входа отображает первый подходящий предмет из своего Ingredient
• Поведение при отсутствии данных: если клиентский уровень недоступен, рецепт отсутствует или не найдена подходящая фабрика, компонент отрисовывается без видимой высоты

Вы можете зарегистрировать дополнительные фабрики компонентов рецептов через AgeratumRegistries.RECIPE_COMPONENT_FACTORIES:

public static final DeferredHolder<MDRecipeComponent.RecipeComponentFactory<?>, MDRecipeComponent.RecipeComponentFactory<?>> SMELTING =
    AgeratumRegistries.RECIPE_COMPONENT_FACTORIES.register(
        "smelting",
        () -> MDRecipeComponent.RecipeComponentFactory.create(RecipeType.SMELTING, MDSmeltingRecipeComponent::new)
    );

Компонент NBT структуры (``)

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

<structure id="minecraft:village/plains/houses/plains_small_house_1"/>

<structure id="./test.nbt"/>

• id / path: обязательный, ResourceLocation целевого файла структуры
• maxDepth: необязательный, максимальная глубина раскрытия, по умолчанию 2
• maxEntries: необязательный, максимальное количество ключей/элементов списка, показываемых на каждом уровне, по умолчанию 12
• Поддерживаются относительные пути, разрешаемые относительно каталога текущего документа, включая файлы .nbt, размещённые рядом с документом Markdown внутри ресурспака; в режиме предпросмотра соответствующий файл загружается из run/ageratum_review/
• Компонент сначала показывает метаданные структуры, такие как размер, палитра, количество блоков и количество сущностей, затем отрисовывает превью блоков сверху, а после — ограниченное по глубине дерево NBT
• При наведении на блок в превью показывается его ID блока, координаты в структуре, индекс в палитре и наличие NBT блочной сущности

Предзагрузка и кэширование

• Автоматически сканирует и предварительно разбирает документы Markdown в списки MDComponent при загрузке ресурсов
• Открывает кэшированные компоненты сразу, без задержки на разбор
• Автоматически обновляет кэш при перезагрузке ресурсов

Открытие руководства на разных сторонах

// Клиент: открыть напрямую
Ageratum.openGuide(ResourceLocation location);

// Сервер: уведомить клиент через сетевой пакет
Ageratum.

openGuide(ResourceLocation location);

Структура проекта

Расположение каталогов

src/main/java/dev/anvilcraft/resource/ageratum/
├── Ageratum.java                           // Главный класс мода + регистрация команд
├── GuideDocumentLoader.java                // Утилиты загрузки документов
├── GuideDocumentCache.java                 // Кэш предзагрузки и слушатель перезагрузки
│
├── client/
│   ├── AgeratumClient.java                 // Клиентские хуки (зарезервировано)
│   ├── gui/
│   │   └── GuideScreen.java                // GUI для чтения руководства
│   └── feat/markdown/
│       ├── MarkdownParser.java             // Блочный парсер Markdown
│       ├── BuiltinExtensionComponents.java // Регистрация встроенных расширений
│       ├── BlockExtensionState.java        // Машина состояний блочных расширений
│       ├── SelfClosingBlockExtensionState.java
│       ├── ExtensionParamParser.java       // Утилита разбора параметров
│       ├── MDExtensionContext.java         // Контекст выполнения расширений
│       ├── MDExtensionComponentFactory.java // Интерфейс фабрики расширений
│       └── component/
│           ├── MDComponent.java            // Базовый класс + встроенный парсинг
│           ├── MDTextComponent.java        // Обычные текстовые абзацы
│           ├── MDHeaderComponent.java      // Заголовки
│           ├── MDCodeBlockComponent.java   // Блоки кода
│           ├── MDListComponent.java        // Списки (вкл. списки задач)
│           ├── MDQuoteComponent.java       // Цитаты
│           ├── MDTableComponent.java       // Таблицы
│           ├── MDImageComponent.java       // Изображения
│           ├── MDHorizontalRuleComponent.java
│           └── MDNoticeBoxComponent.java   // Контейнер блока уведомлений
│
└── network/
    ├── AgeratumNetwork.java                // Регистрация и диспетчеризация сети
    └── OpenGuidePayload.java               // Сетевой пакет открытия руководства

Принципы проектирования

• Разделение ответственности: каждый класс отвечает за одну задачу
• Никаких раздутых классов: самые длинные файлы ~400 строк, все внутренние классы вынесены
• Подробная документация: китайский Javadoc для всех публичных API, встроенные комментарии для сложной логики
• Расширяемость: регистрируйте собственные типы блоков через registerExtensionComponent()

Руководство по использованию

Игрокам

Открывайте руководства клиентской командой:

/ageratum <namespace> [file]

Примеры:
/ageratum ageratum                  # Открывает ageratum:en_us/index.md
/ageratum mymod guide              # Открывает mymod:en_us/guide.md
/ageratum mymod zh_cn/tutorial     # Открывает mymod:zh_cn/tutorial.md

Поддерживается автодополнение по Tab для пространств имён и имён файлов.

Разработчикам

Регистрация собственного расширения

Используйте методы регистрации, описанные в документации NeoForge:

1. DeferredRegister (рекомендуется)
2. RegisterEvent (продвинутое использование)

public static final DeferredRegister<MDExtensionComponentFactory> EXT_COMPONENT_FACTORIES =
    AgeratumRegistries.createExtensionComponentFactoryRegister("your_modid");

public static final DeferredHolder<MDExtensionComponentFactory, MDExtensionComponentFactory> CUSTOM =
    EXT_COMPONENT_FACTORIES.register(
        "custom", () ->
            context -> new MyComponent(context.renderedContent(), context.params())
    );

// В конструкторе вашего мода
EXT_COMPONENT_FACTORIES.

register(modEventBus);

Регистрация собственного парсера встроенных стилей

Парсеры встроенных стилей регистрируются через INLINE_STYLE_PARSER_REGISTRY_KEY. MDComponent обращается к этому реестру и находит совпадения по позиции + приоритету парсера.

package com.example.mymod.client.markdown;

import dev.anvilcraft.resource.ageratum.client.feat.markdown.component.MDInlineStyleParser;
import dev.anvilcraft.resource.ageratum.client.registries.AgeratumRegistries;
import net.minecraft.network.chat.Style;
import net.neoforged.neoforge.registries.DeferredHolder;
import net.neoforged.neoforge.registries.DeferredRegister;

import java.util.regex.Pattern;

public final class MyInlineStyleParsers {
    // Use your own modid here, not ageratum
    public static final DeferredRegister<MDInlineStyleParser> INLINE_STYLE_PARSERS = DeferredRegister.create(
        AgeratumRegistries.INLINE_STYLE_PARSER_REGISTRY_KEY,
        "mymod"
    );

    // Example tag: <rainbow>text</rainbow>
    public static final DeferredHolder<MDInlineStyleParser, MDInlineStyleParser> RAINBOW =
        INLINE_STYLE_PARSERS.register(
            "rainbow",
            () -> MDInlineStyleParser.create(
                100, // smaller value = higher precedence at same position
                Pattern.compile("<rainbow>"),
                "</rainbow>",
                (Style parentStyle, java.util.regex.Matcher matcher) -> parentStyle.withColor(0xFF55FF)
            )
        );

    private MyInlineStyleParsers() {
    }
}

Зарегистрируй его в своём client init:

public class MyModClient {
    public MyModClient(IEventBus modEventBus) {
        MyInlineStyleParsers.INLINE_STYLE_PARSERS.register(modEventBus);
    }
}

Использование в Markdown:

normal text <rainbow>colored text</rainbow> normal text

Полное руководство: docs/inline-style-parser-example.en.md.

Добавление документации

Создай в ресурспаке:

assets/<namespace>/ageratum/<language>/index.md
assets/<namespace>/ageratum/en_us/index.md
assets/<namespace>/ageratum/zh_cn/index.md

Лицензия

• Код, если не указано иное, распространяется по нашему файлу LICENSE (LGPL-3.0)
• Не-кодовые ассеты (находятся здесь) распространяются по нашему файлу ASSET_LICENSE (ARR)