指南框架

GuideNH 的核心是一套四段式渲染管线：资源包里的 Markdown 文件经过编译， 变成一棵文档树，再映射成 3D 场景图，最后由渲染器逐帧绘制。

资源包 Markdown（YAML frontmatter + 正文）
  └─ 编译器     guide/compiler      Markdown → 文档模型
      └─ 文档模型 guide/document     页面 / 章节 / 导航 / 锚点
          └─ 场景图 guide/scene      3D 方块 / 实体 / 标注 / 相机
              └─ 渲染  guide/render + guide/internal   逐帧绘制

门面类（guide/ 根目录 9 个）

类 职责
Guide 一本指南书。GuideRegistry 按 ID 索引它
GuideBuilder 构建 Guide 的建造者
GuidePage 单页
GuideAnchor / PageAnchor 页内锚点
PageCollection 页面集合
GuidePageChange 页面变更事件载荷
GuidePageIcon 页面图标
GuidesCommon 公共工具

文档模型（guide/document，136 文件）

页面、章节、导航元数据、分类、锚点的对象模型。 README 明确列出支持 YAML frontmatter、导航元数据、分类、锚点、 表格、脚注、Mermaid、LaTeX、图表与高亮文本。

编译管线（guide/compiler，87 文件）

把 Markdown 编译进文档模型。内建标签的注册在 guide/internal/syntax/BuiltinSyntaxContributor.java，共 119 个唯一标签 （完整清单见 MDX 标签）。

⚠️ 该文件在 guide/internal/syntax/，不在 guide/syntax/—— guide/syntax/ 是另一回事（18 个文件，语法高亮与语法贡献者接口）。

移植的 JS 生态

com/hfstudio/guidenh/libs/ 下 160 个文件、4 个包，把 unified / remark / micromark 这套 JavaScript 的 Markdown 工具链概念 移植到 Java：

包 文件数 对应 JS 生态
libs/micromark 82 micromark（Markdown 解析器）
libs/mdast 65 mdast（Markdown 抽象语法树）
libs/mdx 7 MDX（可执行 Markdown）
libs/unist 6 unist（通用语法树）

⚠️ 路径是 libs，不是 guide/libs——guide/ 下没有 libs 子目录 （实测 find src/main/java/com/hfstudio/guidenh/guide/libs 无此路径）。

这是本 mod 在架构上最不寻常的一点：它没有直接用 Java 的 Markdown 库， 而是自建了一套与 JS 同构的分层（micromark 解析 → mdast/mdx 节点 → unist 定位）。

场景图（guide/scene，140 文件）

3D 场景部分。支持方块 / 实体摆放、StructureLib 导入、Ponder 回放、 图层滑块、网格控制、标注与方块统计。

标注类（可从标签名反推）包括 BlockAnnotation / BoxAnnotation / DiamondAnnotation / ImageAnnotation / InputAnnotation / LineAnnotation / TextAnnotation / BlockAnnotationTemplate。

方块定位辅助在 guide/scene/level/GuidebookLevel.java（1154 行起有方块 UID 查找） 与 guide/scene/support/GuideBlockMatcher.java。

布局与渲染

包 文件数 职责
guide/layout 10 布局引擎
guide/editor 11 指南编辑器
guide/render 6 渲染
guide/style 6 样式 / 主题
guide/color 6 颜色
guide/sound 4 声音（<PlaySound> / <SoundArea> / <SoundLink> 标签）
guide/indices 8 索引（物品索引导航、搜索）
guide/extensions 3 扩展点
guide/navigation 2 导航
guide/latex 2 GuideLatexRenderer / GuideLatexTextureCache
guide/ui 1 UI 壳

导出

包 文件数 职责
guide/mediawiki 61 MediaWiki 导出
guide/siteexport 53 站点导出
com/hfstudio/structurelibexport 33 StructureLib 导出（平级包根，见 结构导出）
guideme/flatbuffers/scene 16 flatbuffers 生成的场景结构代码

内部实现（guide/internal，374 文件）

占全部主源（1402）的 26.7%，是最大的单一包。含场景运行时、渲染器、编辑器、 MasterScheduler 调度器、GuideOnStartup 启动流程、 GuideDevelopmentResourcePackWatcher 开发期资源包监听、 BuiltinSyntaxContributor 标签注册等。

生命周期

GuideNH（com/hfstudio/guidenh/GuideNH.java）是标准 FML 生命周期：

阶段 处理函数
preInit proxy.preInit(event)
init proxy.init(event)
postInit proxy.postInit(event)
loadComplete proxy.completeInit(event)

通过 @SidedProxy 分客户端 / 服务端：ClientProxy / CommonProxy。

相关条目