Ageratum
一款面向 Minecraft NeoForge 的指南书模组,旨在为其他模组提供游戏内指南。Ageratum 支持丰富的 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 结构文件的摘要、自上而下的方块预览以及有界 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 <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
命名空间和文件名支持标签补全。
开发者
注册自定义扩展
使用 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/<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)
Ageratum
A guidebook mod for Minecraft NeoForge, designed to provide in-game guides for other mods. Ageratum offers rich Markdown
rendering, i18n localization, and an extensible custom syntax/component system.
Features
Core Markdown Support
✅ Block Elements
- ATX headings (
# ~ ######) and Setext headings (underline style)
- Paragraphs and line breaks
- Ordered, unordered, and task lists (multi-level nesting)
- Blockquotes (multi-level nesting)
- Fenced code blocks (backticks and tildes) and indented code blocks
- Horizontal rules
- Tables with alignment settings
- Images (namespace-local references)
✅ Inline Elements
- bold, italic,
strikethrough
- Inline code spans (multi-backtick support)
- Links and autolinks
- Escape character support
- Custom color tags
- Hover and Click Events (
<hover> and <click> tags)
✅ Advanced Features
- Reference link definitions and reference link syntax
- Automatic link expansion
- Code block line numbers
- Table column alignment (left/center/right)
Internationalization (i18n)
- Documents organized by
ageratum/<language_code>/ (e.g., en_us, zh_cn)
- Default fallback to
en_us if localized version missing
- Full support for multi-byte characters (Chinese, Japanese, etc.)
Extension Syntax
Two block-level extension syntaxes for custom components:
1. Colon Syntax
::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: danger
This is a danger warning.
:::
2. Tag Syntax
<namespace:component key="value" param=123>
Block content supports Markdown syntax.
</namespace:component>
<namespace:component/>
Self-closing form without content.
Namespace can be omitted (defaults to ageratum:).
Built-in Extension Components
ageratum:info - Blue info box
ageratum:tip - Green tip box
ageratum:warning - Orange warning box
ageratum:danger - Red danger box
Hover and Click Events
Support interactive text that allows players to hover for tooltips or click to perform actions.
Hover Events (<hover>)
Display tooltip text when hovering over text:
<hover type="SHOW_TEXT" data="This is the tooltip">Hover over me</hover>
Supported Types:
SHOW_TEXT - Display plain text tooltip (data is the tooltip content)
Click Events (<click>)
Execute an action when clicking on text:
<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>
Supported Types:
OPEN_URL - Open a URL (data is the complete URL)
COPY_TO_CLIPBOARD - Copy text to clipboard (data is the text to copy)
SUGGEST_COMMAND - Suggest a command in chat (data is the command text)
Combining Styles
You can combine multiple styles in the same text:
<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 Component (<recipe/>)
Use the recipe extension to render recipes directly inside Markdown documents:
<recipe id="minecraft:acacia_boat"/>
id: required, target recipe ResourceLocation
- Built-in support:
RecipeType.CRAFTING (crafting table recipes)
- Rendering behavior: each input slot displays the first candidate item from its
Ingredient
- Fallback behavior: if client level is unavailable, recipe is missing, or no factory matches, the component renders with no visible height
You can register additional recipe component factories through 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)
);
Structure NBT Component (<structure/>)
Use the structure extension to render a summary, top-down block preview, and bounded NBT tree for .nbt structure files directly inside documents:
<structure id="minecraft:village/plains/houses/plains_small_house_1"/>
<structure id="./test.nbt"/>
id / path: required, target structure file ResourceLocation
maxDepth: optional, maximum expansion depth, default 2
maxEntries: optional, maximum number of keys/list entries shown per level, default 12
- Relative paths are supported and resolved against the current document directory, including
.nbt files placed next to the Markdown document inside the resource pack; in preview mode the matching file is loaded from run/ageratum_review/
- The component first shows structure metadata such as size, palette, block count, and entity count, then renders a top-down block preview followed by a depth-limited NBT tree
- Hovering a block in the preview shows its block ID, structure coordinates, palette index, and whether it carries block-entity NBT
Preloading & Caching
- Automatically scans and pre-parses Markdown documents to
MDComponent lists on resource load
- Opens cached components immediately without parsing delay
- Auto-refreshes cache on resource reload
Cross-side Guide Opening
// Client: open directly
Ageratum.openGuide(ResourceLocation location);
// Server: notify client via network packet
Ageratum.
openGuide(ResourceLocation location);
Project Structure
Directory Layout
src/main/java/dev/anvilcraft/resource/ageratum/
├── Ageratum.java // Main mod class + command registration
├── GuideDocumentLoader.java // Document loading utils
├── GuideDocumentCache.java // Preload cache & reload listener
│
├── client/
│ ├── AgeratumClient.java // Client hooks (reserved)
│ ├── gui/
│ │ └── GuideScreen.java // Guide reading GUI
│ └── feat/markdown/
│ ├── MarkdownParser.java // Markdown block-level parser
│ ├── BuiltinExtensionComponents.java // Built-in extension registration
│ ├── BlockExtensionState.java // Block extension state machine
│ ├── SelfClosingBlockExtensionState.java
│ ├── ExtensionParamParser.java // Parameter parsing utility
│ ├── MDExtensionContext.java // Extension execution context
│ ├── MDExtensionComponentFactory.java // Extension factory interface
│ └── component/
│ ├── MDComponent.java // Base class + inline parsing
│ ├── MDTextComponent.java // Plain text paragraphs
│ ├── MDHeaderComponent.java // Headings
│ ├── MDCodeBlockComponent.java // Code blocks
│ ├── MDListComponent.java // Lists (inc. task lists)
│ ├── MDQuoteComponent.java // Blockquotes
│ ├── MDTableComponent.java // Tables
│ ├── MDImageComponent.java // Images
│ ├── MDHorizontalRuleComponent.java
│ └── MDNoticeBoxComponent.java // Notice box container
│
└── network/
├── AgeratumNetwork.java // Network registration & dispatch
└── OpenGuidePayload.java // Guide open network packet
Design Principles
- Separation of Concerns: Each class handles a single responsibility
- No Oversized Classes: Longest files ~400 lines, all inner classes extracted
- Comprehensive Documentation: Chinese Javadoc for all public APIs, inline comments for complex logic
- Extensibility: Register custom block types via
registerExtensionComponent()
Usage Guide
Players
Open guides with client command:
/ageratum <namespace> [file]
Examples:
/ageratum ageratum # Opens ageratum:en_us/index.md
/ageratum mymod guide # Opens mymod:en_us/guide.md
/ageratum mymod zh_cn/tutorial # Opens mymod:zh_cn/tutorial.md
Tab completion supported for namespaces and file names.
Developers
Register Custom Extension
Use registration methods described in NeoForge docs:
DeferredRegister (recommended)
RegisterEvent (advanced usage)
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())
);
// In your mod constructor
EXT_COMPONENT_FACTORIES.
register(modEventBus);
Register Custom Inline Style Parser
Inline style parsers are registered through INLINE_STYLE_PARSER_REGISTRY_KEY. MDComponent queries this registry and resolves matches by
position + parser priority.
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() {
}
}
Register it in your client init:
public class MyModClient {
public MyModClient(IEventBus modEventBus) {
MyInlineStyleParsers.INLINE_STYLE_PARSERS.register(modEventBus);
}
}
Markdown usage:
normal text <rainbow>colored text</rainbow> normal text
See full guide: docs/inline-style-parser-example.en.md.
Add Documentation
Create in resource pack:
assets/<namespace>/ageratum/<language>/index.md
assets/<namespace>/ageratum/en_us/index.md
assets/<namespace>/ageratum/zh_cn/index.md
License
- Code unless otherwise stated default to our LICENSE file(LGPL-3.0)
- Non-Code assets (Located here) go by our ASSET_LICENSE file(ARR)
评论 0
登录后参与评分
还没有评论,来抢沙发吧