Ageratum

模组

· 作者 Gu-ZT

一款适用于 Minecraft NeoForge 的指南书模组

0 本站下载 0 关注 更新于 17 小时前

最新 26.1.2-0.0.1+build.153 · 26.1.2 · NeoForge

一键开服(送7天)

Ageratum

Ageratum Logo

一款面向 Minecraft NeoForge 的指南书模组,旨在为其他模组提供游戏内指南。Ageratum 支持丰富的 Markdown 渲染、国际化(i18n)本地化以及可扩展的自定义语法/组件系统。

Documentation

功能

核心 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 文档中描述的注册方法:

  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 {
    // 请在此处使用你自己的 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)

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源