藿香 · 我的世界Mod

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

藿香蓟

这是一个为 Minecraft NeoForge 设计的指南书模组，旨在为其他模组提供游戏内指南。藿香蓟提供丰富的 Markdown 渲染、i18n 本地化以及可扩展的自定义语法/组件系统。

文档

功能特性

核心 Markdown 支持

✅ 块级元素

ATX 标题（# ~ ######）和 Setext 标题（下划线样式）
段落和换行
有序列表、无序列表和任务列表（支持多级嵌套）
引用块（支持多级嵌套）
围栏代码块（反引号和波浪线）和缩进代码块
水平分割线
支持对齐设置的表格
图片（支持命名空间本地引用）

✅ 行内元素

粗体、斜体、删除线
行内代码跨度（支持多反引号）
链接和自动链接
转义字符支持
自定义颜色标签
悬停和点击事件（<hover> 和 <click> 标签）

✅ 高级功能

引用链接定义和引用链接语法
自动链接扩展
代码块行号
表格列对齐（左对齐/居中/右对齐）

国际化（i18n）

文档按 ageratum/<语言代码>/ 目录组织（例如 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>`）

悬停在文本上时显示提示文本：

<hover type="SHOW_TEXT" data="这是提示文本">悬停在我上方</hover>

支持的类型：

SHOW_TEXT - 显示纯文本提示（data 为提示内容）

点击事件（`<click>`）

点击文本时执行操作：

<click type="OPEN_URL" data="https://example.com">点击打开链接</click>
<click type="COPY_TO_CLIPBOARD" data="要复制的文本">点击复制</click>
<click type="SUGGEST_COMMAND" data="/say hello">点击建议命令</click>

支持的类型：

OPEN_URL - 打开一个 URL（data 为完整 URL）
COPY_TO_CLIPBOARD - 将文本复制到剪贴板（data 为要复制的文本）
SUGGEST_COMMAND - 在聊天中建议一条命令（data 为命令文本）

组合样式

你可以在同一文本中组合多种样式：

<hover type="SHOW_TEXT" data="这是一个提示"><click type="OPEN_URL" data="https://example.com">点击并悬停在我上方！</click></hover>

配方组件（`<recipe/>`）

使用 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 树：

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

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

id / path：必填，目标结构文件的 ResourceLocation
maxDepth：可选，最大展开深度，默认 2
maxEntries：可选，每层显示的最大键/列表条目数，默认 12
支持相对路径，相对于当前文档目录解析，包括资源包中位于 Markdown 文档旁边的 .nbt 文件；在预览模式下，从 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 行，所有内部类均已提取
全面文档：所有公共 API 均有中文 Javadoc，复杂逻辑有行内注释
可扩展性：通过 registerExtensionComponent() 注册自定义块类型

使用指南

玩家

使用客户端命令打开指南：

/ageratum <命名空间> [文件]

示例：
/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 文档中描述的注册方法：

DeferredRegister（推荐）
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 {
    // 这里使用你自己的 modid，而不是 ageratum
    public static final DeferredRegister<MDInlineStyleParser> INLINE_STYLE_PARSERS = DeferredRegister.create(
        AgeratumRegistries.INLINE_STYLE_PARSER_REGISTRY_KEY,
        "mymod"
    );

    // 示例标签：<rainbow>text</rainbow>
    public static final DeferredHolder<MDInlineStyleParser, MDInlineStyleParser> RAINBOW =
        INLINE_STYLE_PARSERS.register(
            "rainbow",
            () -> MDInlineStyleParser.create(
                100, // 较小的值 = 在相同位置具有更高优先级
                Pattern.compile("<rainbow>"),
                "</rainbow>",
                (Style parentStyle, java.util.regex.Matcher matcher) -> parentStyle.withColor(0xFF55FF)
            )
        );

    private MyInlineStyleParsers() {
    }
}

在客户端初始化中注册：

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/<命名空间>/ageratum/<语言>/index.md
assets/<命名空间>/ageratum/en_us/index.md
assets/<命名空间>/ageratum/zh_cn/index.md

许可证

除非另有说明，代码默认遵循我们的 LICENSE 文件（LGPL-3.0）
非代码资产（位于此处）遵循我们的 ASSET_LICENSE 文件（ARR）