? 渲染复杂的多方块结构。 直接在用户界面中解析 Markdown。
? 播放视频、GIF 和图像 —— 通过 FFmpeg 在 Windows、macOS 和 Linux 上支持。
? 完全可定制的主题, 支持每本书覆盖设置、自定义颜色和章节背景,以及可选的视觉效果。
? 交互式书籍直接从磁盘编译。支持多书籍命名空间,零 JAR 打包。提供完整的命令套件用于列出和打开书籍。
sidebar search /guide list /guide open unlock_tag index hot-reload |
? 多元块投影逐步预览并组装复杂结构。
layers rotation zoom progress HUD NBT |
? Markdown 引擎在 GUI 内实时渲染完整 Markdown。
tables links spoilers items mobs sounds indentation search fulltext |
? 多媒体直接在书籍中播放视频、GIF 和图片。
JavaCV FFmpeg GIF WebP URL fullscreen ducking cache |
? 探险家日志存储在玩家 NBT 中的个人笔记本。支持笔记、实时 Markdown 预览、清单、表格和折叠内容。
notes editor preview checklists markdown NBT sync |
? 指南扫描器右键点击方块、生物、掉落物或流体,直接跳转到匹配的章节。
blocks mobs items fluids @bind: @bind_tag: choice screen |
⌨️ 指南快捷键可配置的快捷键,无需打开物品栏即可打开书籍或日志。
B N rebindable inventory-aware Curios-aware |
? 主题与背景所有 UI 元素均可通过 JSON 进行主题化,包括章节背景。
per-book colors chapterBackground color image URL effects lock |
?️ 通用图片全面支持 PNG、JPEG、BMP 和 GIF —— 图标、背景、媒体均可使用。
PNG JPEG BMP GIF local server URL |
? Curios 集成可选功能。当安装 Curios 后,书籍和日志可放置在腰带槽位并在角色模型上显示。
belt render optional |
? 模组与任务钩子JEI 绑定、书内复选框、服务器同步进度。
@bind: @bind_tag: quests UUID NBT |
? 书籍解锁门控隐藏书籍,直到任何命令源授予每个玩家的解锁标签为止。
unlock_tag KubeJS FTB Quests advancements |
? 书籍门控 |
▸ 按玩家解锁标签:在任意 book.json 中添加 unlock_tag,书籍在玩家持有对应标签前会在选择器中保持隐藏。非常适合教程书籍、终局指南或剧情锁定的内容。
▸ 命令驱动:/guide unlock <tag> 和 /guide lock <tag> 用于授予或撤销标签;两者均接受可选的玩家参数(需要 OP 等级 2)供管理员使用。/guide unlocks 列出你的活跃标签,/guide unlocks clear 一次性清除所有标签。
▸ 整合包友好:任何能发送命令的系统均可工作——KubeJS 事件、FTB Quests 奖励、进度系统或自定义脚本包。状态以 NBT 形式按玩家存储在服务器端,并在登录及每次更改后同步。
|
? 探索者日志 |
▸ 个人笔记本:guide_diary 物品打开一个存储在玩家 NBT 中的私人笔记列表。每条笔记包含标题、正文、创建/更新时间戳以及创建时的坐标和维度。笔记在重新连接、维度切换和客户端重装后依然存在;其他玩家永远无法看到它们,即使在服务器上也是如此。
▸ 编辑器与实时预览:编辑器是一个真正的多行文本框,支持光标导航、剪贴板支持(Ctrl+A/C/V/X)以及可拖动的主题滚动条。预览区以与书籍相同的方式渲染笔记——包括颜色、样式、链接、表格、分隔线、剧透和清单——并在你输入时通过 200 ms 的防抖进行刷新。
▸ 交互式清单:Markdown 风格的复选框(- [ ] / - [x])可在预览区内通过左键点击切换。状态存储在笔记本身中,并在每次点击时保存。已完成的任务会显示绿色对勾和删除线;任务颜色可通过复选框前的 & 代码前缀设置(&e- [ ]、&c- [ ])。
▸ 日志 Markdown 支持:支持 &0–&f 颜色、&l/&o/&n/&m 样式、&r 重置、外部链接 [text](https://…)、分隔线(---、&6---、&l&9---)、支持换行和拖拽滚动的表格、剧透(@spoiler: / @endspoiler)以及清单。编辑器会动态将 &x 转换为 §x,因此作者无需直接输入节符号。
▸ 网络同步:两种有效负载保持日志同步——同步有效负载(服务器 → 客户端,在登录时发送)和更新有效负载(客户端 → 服务器,在创建/更新/删除时发送)。采用最后写入获胜的冲突解决机制,无需确认往返。
|
? 指南扫描仪 |
▸ 一键查找:guide_scanner 物品解析方块、生物、掉落物或流体的注册 ID,并在 JEI 和 G 键快捷方式所使用的相同绑定映射中进行查找(@bind: / @bind_tag:)。单一匹配会立即打开章节;多个匹配会打开带有可折叠树的主题选择屏幕——一次展开一本书,章节嵌套其下,并显示章节图标。
▸ 实体射线检测:使用自定义 AABB 裁剪射线检测,以确保正确检测到小型掉落物和薄碰撞箱——原版投射物射线检测会遗漏它们。
▸ 流体回退:首先通过流体 ID 扫描水和岩浆,如果未找到流体本身的绑定,则回退到桶 ID(water_bucket / lava_bucket)。
▸ 累积索引:扫描仪从 itemToChapterRefMap 读取数据,这是一个独立的第二索引,即使书籍重载也能保留,并涵盖所有可见书籍——无需先打开书籍。
|
⌨️ 指南快捷键 |
▸ 两个热键:B 打开书籍选择器,N 打开日志。两者均绑定到 Guide 类别,并可随时在 选项 → 控制 → Guide 中重新绑定。
▸ 库存感知:每个按键仅在匹配的物品的(guide_book 或 guide_diary)位于主背包、副手或 Curios 槽位时才会触发。没有物品就没有动作——这防止了通过热键绕过书籍门控系统。
|
? 多书籍配置自主性 |
▸ 直接从磁盘编译:自动映射并从本地机器的 config/guide/books/[book_id]/ 加载指南书。不再需要将文件打包进模组 JAR 归档中。
▸ 自动生成蓝图:在首次启动时,模组会将一个完整且就绪构建的指南书模板提取到你的配置文件夹中,从而保护自定义资产在整合包更新期间不被覆盖。
▸ 整洁的书籍选择器:具有完全响应的书籍目录视口,支持活动过滤,使用 零模组 ID 冲突 干净地渲染隔离的书籍命名空间。书籍顺序可以通过每个 book.json 中的可选 index 字段进行控制。
|
⚙️ 热重载与开发者友好管线 |
▸ 运行时布局切换(/guide reload):在磁盘上编辑 Markdown 文件、布局节点、纹理或 JSON 本地化表,即可在游戏内即时重新填充指南书的内存。默认情况下所有玩家均可使用,无需 OP/作弊权限。
▸ 快捷聊天导航(/guide):一个专用的聊天指令入口,可从任意位置直接将用户路由到主书籍目录视图,消除了对物品的依赖。
▸ 书籍列表与直接打开:/guide list 打印客户端可见的所有书籍(含索引、命名空间、开发者标志和显示名称);/guide list server 显示服务器正在分发的内容;/guide open <namespace> 可通过 Tab 补全按 ID 打开任意书籍。
▸ 物品快捷指令:/guide give <book|scanner|diary> [player] 将匹配的指南书物品直接生成到背包中,若背包已满则回退至 player.drop() 掉落。包含每秒每玩家的冷却时间,并为别名和玩家提供了 Tab 补全功能。
▸ 开发者模式开关:通过 config/guide/guide-client.toml 向玩家隐藏操作手册或蓝图,同时保持其在开发者模式下可用。
|
? 高级导航与搜索光标 |
▸ 重构的搜索框:配备简洁的垂直光标(|),可在 英文和西里尔字母 键盘布局下完美执行移动序列和文本选择操作。
▸ 智能侧边栏子菜单:无缝嵌套下拉子章节(@submenu:)和折叠内容于点击事件之后,优化渲染帧率并防止布局裁剪。
▸ 不可破坏的追踪与历史记录:导航记忆会锁定侧边栏子菜单的展开状态,且文本超链接命中区域会在任何动态滚动条偏移量下精确追踪行位置。
▸ 全文搜索覆盖层:侧边栏搜索不仅扫描标题,还扫描章节内容。输入查询后,会在覆盖层中显示每个匹配项的片段,并按章节分组。点击片段可打开对应章节,滚动至匹配行并就地高亮查询词。侧边栏也会保留仅通过内容匹配的章节。
▸ 章节内搜索(Ctrl+F):类似浏览器的查找面板将在章节区域底部打开。每个匹配项均被高亮(当前激活项以不同颜色显示);可通过 ↑ / ↓ 或 Enter / Shift+Enter 在匹配项间跳转,并带有实时 N / M 计数器。包含匹配项的折叠内容会自动展开;不包含匹配项的折叠内容保持收起。搜索高亮颜色可通过 searchHighlightColor 和 searchHighlightCurrentColor 进行主题自定义。
|
? 高级内容渲染 |
▸ 自然文本缩进支持:Markdown 引擎完全尊重文本序列开头的空格和制表符块,允许结构化嵌套列表而不会导致超链接区域不同步。
▸ 直接媒体流式传输:直接从本地书籍目录渲染静态图片(@image:)和动画 GIF(@gif:),彻底消除棋盘格占位纹理故障。支持 PNG、JPEG、BMP 和 GIF(首帧)格式。
▸ 3D 物品与方块模型(@item:):在页面内联渲染旋转的 3D 物品和方块模型。尺寸按实例设置(16–128 px),对齐方式可配置(左 / 居中 / 右),平面物品和完整方块均尊重声明的尺寸。悬停可查看包含注册表 ID 和模组名称的工具提示。
▸ 整合的多方块 NBT 投影:3D 全息投影仪(PlacementProjector)和页面渲染器(StructureRenderer)直接从配置文件夹编译 .nbt 蓝图。创作者可以将多方块结构原生捆绑到他们的指南书中,无需外部数据包。
|
? 内置媒体系统 |
▸ 视频播放:使用 @video: 命令直接在指南页内播放本地和远程视频文件(mp4、avi、mkv、webm)。支持带自动缓存功能的直接 HTTP(S) 链接,并包含一个自定义播放器,具备播放/暂停、停止、重播、音量滑块、全屏以及支持拖拽进度条的寻址功能。
▸ GIF 和图片 URL 支持:在 @gif: 和 @image: 中使用直接 HTTP(S) 链接从互联网加载动画 GIF 和静态图片(PNG、JPEG)。文件会缓存在 config/guide/cache/media/ 中以供离线重复使用。
▸ 声音集成:使用 @sound: 命令嵌入可点击的声音按钮,播放来自书籍 sounds/ 文件夹的自定义音频文件。支持逐页播放并自动降低背景音乐音量。
▸ 智能背景音乐自动降低:当视频或自定义声音开始时,模组会自动暂停背景音乐,并在播放结束后恢复。
▸ 仅客户端安全:所有媒体解码器、FFmpeg 原生库下载器、JavaCV 桥接器以及纹理上传器均标注为 @OnlyIn(Dist.CLIENT)。专用服务器永远不会下载 FFmpeg 二进制文件,也不会接触仅适用于客户端的视频代码。
|
? 主题与章节背景 |
▸ 完全可主题化的 UI:每个界面元素——面板、边框、按钮、滚动条、表格、媒体播放器、投影仪——均由 JSON 主题文件定义。自定义主题放置在 config/guide/themes/(客户端或服务器端)。
▸ 单书覆盖设置:在 book.json 中设置 theme 字段以强制书籍使用特定主题;关闭书籍时将恢复全局主题。优先级:书籍主题 > 锁定主题 > 全局主题。
▸ 章节背景:主题可以通过 chapterBackground 块覆盖默认的章节背景——可以是纯色(支持调整透明度)或图片。图片可以是本地文件、服务器端文件或直接 URL(自动下载并缓存)。
▸ 内置视觉效果:可选的按主题效果:bloodEffects、forestEffects、cyberTechEffects、matrixEffects、sakuraEffects、honeyEffects。
|
? 模组与任务集成 |
▸ 实时服务器同步复选框:提供客户端到服务器的交互式任务系统。任务完成状态绑定到玩家 UUID,并安全地保存在 服务器端 NBT 结构中,防止进度文件因本地数据清除而丢失。
▸ JEI 导航就绪:使用 @bind:mod_id:item 将章节绑定到特定的物品条目,以便直接在 JEI 内触发匹配的指南页面,或点击指南物品通行证以立即调出当前配方表。
▸ Curios 腰带槽位:书本和日志通过数据驱动的标签声明与 Curios 的 belt 槽位兼容。当安装 Curios 时,装备的物品将在玩家模型上渲染,并且 B / N 快捷键可以从该槽位拾取物品,如同其在背包中一样。Curios 是一个软依赖项——即使未安装该模组,本模组也能正常加载和运行。
|
| ⌨️ Command | 描述 |
| /guide | 从任意位置打开主书籍目录——无需物品 |
| /guide reload | 热重载所有 markdown、纹理、JSON 和主题,无需重启游戏 |
| /guide list | 列出客户端可见的所有书籍。点击某行可在聊天栏插入 /guide open <namespace>;悬停查看详情 |
| /guide list server | 列出服务器当前分发的书籍。悬停显示索引、命名空间、开发者标记和磁盘路径 |
| /guide open <namespace> | 通过聊天栏按命名空间打开特定书籍。支持 Tab 补全 |
| /guide give <book|scanner|diary> [player] | 将 Guide 物品生成到你的物品栏中,或在拥有 OP 2 权限时生成到其他玩家的物品栏中。当背包已满时回退为 player.drop()。每名玩家冷却时间为 1 秒 |
| /guide unlock <tag> [player] | 授予你自己或其他玩家解锁标签(对其他玩家需 OP 2) |
| /guide lock <tag> [player] | 撤销你自己或其他玩家的解锁标签(对其他玩家需 OP 2) |
| /guide unlocks | 列出你当前持有的所有解锁标签 |
| /guide unlocks clear [player] | 清除你自己或另一名玩家(需 OP 2)的所有解锁标签。适用于测试和管理维护 |
▸ 除 /guide list server、/guide reload(服务端命令)以及针对玩家目标的 unlock / lock / give 变体外,默认情况下所有玩家均可使用其余命令——无需 OP 或作弊权限。
| ⚙️ 加载器 | ? 游戏版本 | ? 模组版本 | ☕ JDK | ? 状态 | ? 分支 |
 |
Forge |
1.20.1 |
1.8.0+ |
17 |
? 稳定版 |
forge-1.20.1 |
 |
NeoForge |
1.21.1 |
1.6.0+ |
21 |
? 稳定版 |
neoforge-1.21.1 |
▸ 两个分支的功能集完全一致——多媒体支持、Markdown 渲染、多块投影和书籍解锁机制均保持一致。唯一的小区别在于:在 Forge 上,右键点击 Curios 腰带槽位会打开已装备物品的界面(通过 ICurioItem.curioRightClick);而在 NeoForge 上,这已不再属于 Curios API 的一部分,因此请改用 N / B 键绑定。
| ? JEI | 使用 @bind:mod_id:item 将章节绑定到物品上。点击指南物品通行证可立即打开配方。可选 — 即使未安装本模组,指南也能正常工作。 |
| ? Curios | 软依赖。安装后,guide_book 和 guide_diary 可以装备在腰带槽位中;已装备的物品会在玩家模型上渲染,并通过 B / N 键绑定从该槽位拾取。一旦模组加载,该槽位会自动出现在任何玩家身上——无需手动配置。 |
| ? FFmpeg / JavaCV / JavaCPP | 通过原生 FFmpeg 二进制文件实现视频解码、转码和帧级媒体访问,由 JavaCV 封装,并通过 JavaCPP 打包以支持 Windows、macOS 和 Linux 平台。 |
| ? Media Cache | 在播放视频或声音时自动降低背景音乐音量,并支持离线媒体缓存。 |
| ? KubeJS / FTB Quests / Advancements | 书籍解锁功能挂钩于任何能够发送命令的系统。可以通过 KubeJS 事件、FTB Quests 奖励、进度函数或脚本包使用 /guide unlock <tag> 授予标签。 |
config/guide/books/<book_id>/
├── chapters/ # 内容章节
│ ├── index.md # 主索引
│ ├── introduction.md # 第一章
│ └── <language>/ # 特定语言文件
├── lang/ # 本地化
│ ├── en_us.json
│ └── <language>.json
├── models/ # 3D 模型数据
├── sounds/ # 背景音频 (.ogg)
├── videos/ # 本地视频文件
├── textures/ # UI 和图像资源
├── structures/ # 多方块 .nbt 蓝图
└── book.json # 元数据
? 示例 book.json:
{
"name": "<book_id>.book.guide",
"namespace": "<book_id>",
"default_chapter": "introduction",
"icon": "your_logo.png",
"bg_music": "background_music",
"theme": "<theme_id>",
"dev_only": false,
"index": 0,
"unlock_tag": ""
}
▸ index 为可选字段。书籍在选择器中按此值排序(数值越小越靠前)。没有 index 的书籍会排在末尾,并按命名空间排序。
▸ unlock_tag 为可选字段。留空则保持书籍公开;设置标签(例如 "secret")可隐藏该书籍,直到玩家通过 /guide unlock secret 获得该标签为止。标签是玩家独立的,并跨会话持久保存。
所有 UI 元素均可通过 JSON 进行主题定制。自定义主题位于 config/guide/themes/ 目录下——复制以下模板,调整颜色,并将其另存为新文件(例如 my_theme.json)。
有两个专用颜色同时控制 Ctrl+F 面板和全文覆盖层:searchHighlightColor(所有匹配项)和 searchHighlightCurrentColor(当前激活的匹配项)。内置调色板随每个主题提供调优后的默认值。
每个主题还可以定义自己的章节背景——一种纯色或图像,用于替换使用该主题的书籍中所有章节的默认背景。
? 示例 standard.json (config/guide/themes/standard.json):
{
"id": "standard", // 唯一主题标识符
"displayName": "guide.theme.standard", // 显示名称(纯字符串或翻译键)
"chapterBackground": { // 可选的章节背景覆盖
"type": "color", // "color" 或 "image"
"value": "0x0A0A0A", // RGB 颜色 (0xRRGGBB),当 type = "color" 时有效
"alpha": 230 // 0 = 透明,255 = 不透明
},
"colors": {
// ===== 通用 UI =====
"panelBackgroundColor": "0xCC1A1A1A", // 面板背景(书页、侧边菜单)
"panelHeaderBackgroundColor": "0xCC111111", // 面板头部背景
"borderColor": "0xFF4A4A4A", // 面板和窗口的默认边框
"borderFocusedColor": "0xFF00D0FF", // 聚焦元素的边框
"textColor": "0xFFFFFF", // 主要文本颜色
"textSecondaryColor": "0x888888", // 次要文本
"scrollbarTrackColor": "0x55111111", // 滚动条轨道背景
"scrollbarThumbColor": "0xFF8B8B8B", // 滚动条滑块
"buttonColor": "0xFF2A2A2A", // 默认按钮
"buttonHoverColor": "0xFF3A3A3A", // 悬停时的按钮
"buttonDisabledColor": "0xFF1A1A1A", // 禁用的按钮
// ===== 输入框 =====
"editBoxBackgroundColor": "0xFF000000", // 输入框背景
"editBoxBorderColor": "0xFFA0A0A0", // 输入框边框
"editBoxBorderFocusedColor": "0xFFFFFFFF", // 聚焦时的输入框边框
"editBoxTextColor": "0xFFFFFF", // 输入框文本
// ===== 搜索高亮 (Ctrl+F) =====
"searchHighlightColor": "0x80FFEB3B", // 所有匹配项高亮
"searchHighlightCurrentColor": "0xC0FF9800", // 当前激活的匹配项
// ===== 媒体播放器 =====
"mediaFrameOuterColor": "0xFF2D2D2D", // 媒体外层框架
"mediaFrameInnerColor": "0xFF4A4A4A", // 媒体内层框架
"mediaBackgroundColor": "0xFF000000", // 播放区域背景
"mediaControlPanelColor": "0xCC000000", // 控制面板背景
"mediaTextColor": "0xFFAAAAAA", // 媒体播放器文本
"mediaErrorTextColor": "0xFFFF5555", // 错误文本
"mediaTimeTextColor": "0xFFCCCCCC", // 播放时间文本
"progressBarTrackColor": "0xFF555555", // 进度条轨道背景
"progressBarFillColor": "0xFF00D0FF", // 进度条填充
"progressBarThumbColor": "0xFFFFFFFF", // 进度条滑块
"progressBarThumbOutlineColor": "0xFF000000", // 进度条滑块轮廓
// ===== 内联元素 =====
"spoilerTitleColor": "0xFFAA00", // 剧透标题
"inlineItemBackgroundColor": "0x550A0A0A", // 内联项目背景
"inlineItemBorderColor": "0x25FFFFFF", // 内联项目边框
"inlineItemTextColor": "0xFFAAAAAA", // 内联项目文本
"soundButtonBackgroundColor": "0xFF2E2E2E", // 声音按钮背景
"soundButtonBorderColor": "0xFF5A5A5A", // 声音按钮边框
"soundButtonTextColor": "0xFFFFFF", // 声音按钮文本
"questStrikethroughColor": "0x77777777" // 删除线的任务文本
// ===== 表格样式 =====
"tableHeaderBackgroundColor": "0xFF222222", // 表头背景色
"tableHeaderTextColor": "0xFFAA00", // 表头文字颜色
"tableRowBackgroundColor": "0x11000000", // 交替行背景色
"tableBorderColor": "0xFF3A3A3A", // 表格边框颜色
"tableCellTextColor": "0xFFFFFF", // 单元格文字颜色
"dividerColor": "0xFF3A3A3A", // 区块分隔线颜色
// ===== 视频标题栏 =====
"videoTitleBackgroundColor": "0xCC2D2D2D", // 视频标题面板背景色
"videoTitleBorderColor": "0xFF5A5A5A", // 视频标题面板边框颜色
"videoTitleTextColor": "0xFFFFFF", // 视频标题文字颜色
// ===== 警告与提示框 =====
"warningTextColor": "0xFF5555", // 主要警告文字颜色
"warningTextSecondaryColor": "0xFFAAAAAA", // 次要警告文字颜色
"toastBackgroundColor": "0xD0101215", // Toast 通知背景色
"toastTextColor": "0xFFFFFF", // Toast 通知文字颜色
// ===== 结构预览面板 =====
"structureFrameColor": "0x4000FFFF", // 3D 结构预览框架颜色
"structureTabActiveBackgroundColor": "0xFF555555", // 激活标签页背景色
"structureTabInactiveBackgroundColor": "0xFF222222", // 未激活标签页背景色
"structureTabActiveTextColor": "0x00FFCC", // 激活标签页文字颜色
"structureTabInactiveTextColor": "0x888888", // 未激活标签页文字颜色
"structureLayerTextColor": "0x55FF55", // 结构层级标签文字颜色
// ===== 放置投影仪 =====
"projectorPanelBackgroundColor": "0xD0101215", // 投影仪面板背景色
"projectorPanelBorderColor": "0x4000D0FF", // 投影仪面板边框颜色
"projectorTitleTextColor": "0x00D0FF", // 投影仪面板标题文字颜色
"projectorButtonBackgroundColor": "0x15FFFFFF", // 默认按钮背景色
"projectorButtonHoverBackgroundColor": "0x3000D0FF", // 鼠标悬停时按钮背景色
"projectorButtonBorderColor": "0x25FFFFFF", // 默认按钮边框颜色
"projectorButtonHoverBorderColor": "0xFF00D0FF", // 鼠标悬停时按钮边框颜色
"projectorButtonTextColor": "0xBBBBBB", // 按钮文字颜色
"projectorButtonHoverTextColor": "0xFFFFFF", // 鼠标悬停时按钮文字颜色
"projectorDoneButtonHoverBackgroundColor": "0x3000FF55", // “完成”按钮鼠标悬停背景色
"projectorDoneButtonHoverBorderColor": "0xFF00FF55", // “完成”按钮鼠标悬停边框颜色
"projectorCancelButtonHoverBackgroundColor": "0x30FF2244", // “取消”按钮鼠标悬停背景色
"projectorCancelButtonHoverBorderColor": "0xFFFF2244", // “取消”按钮鼠标悬停边框颜色
"projectorHudTextColor": "0xFFFFFF" // 投影仪 HUD 提示文字颜色
}
}
?️ 章节背景(可选)
在您的主题中添加一个 chapterBackground 块以覆盖默认背景(NeoForge 上为模糊效果,Forge 上为渐变叠加)。支持三种来源类型:
// 带透明度的纯色(0 = 完全透明,255 = 完全不透明)
"chapterBackground": {
"type": "color",
"value": "0x1A0F2E",
"alpha": 230
}
// 本地或服务器端图片(相对于当前书籍文件夹解析路径)
"chapterBackground": {
"type": "image",
"path": "textures/bg/my_bg.png"
}
// 直接 URL(后台下载,并缓存在磁盘上)
"chapterBackground": {
"type": "image",
"path": "https://example.com/background.jpg"
}
▸ 省略 chapterBackground 将保留默认设置。URL 图片首次加载时会有短暂延迟;后续打开时将使用缓存。支持 PNG、JPEG、BMP 和 GIF(仅第一帧)。
颜色采用 0xAARRGGBB 格式书写:
| 通道 | 范围 | 说明 |
| AA | 00 – FF | Alpha 通道(透明度)。FF = 完全不透明,00 = 完全透明 |
| RR | 00 – FF | 红色通道 |
| GG | 00 – FF | 绿色通道 |
| BB | 00 – FF | 蓝色通道 |
▸ 提示:将 Alpha 值设置为低于 FF(例如 80)可使面板半透明。
| Component | Minimum | Recommended | Notes |
| Minecraft | 1.20.1 · 1.21.1 | 1.20.1 or 1.21.1 | Pick the branch that matches your loader |
| Loader | Forge 47.x+
NeoForge 21.x+ | Latest stable release | Only one is required — choose per branch |
| Java | JDK 17
JDK 21 | 17 for Forge
21 for NeoForge | Version must match the loader branch |
| JEI (optional) | — | Latest for your MC build | Only needed for recipe integration via @bind: |
| Curios (optional) | — | Latest for your MC build | Only needed for the belt slot integration and on-model rendering |
▸ Guide works standalone — JEI, Curios, Quests, and other integrations are entirely optional.
Found a bug or encountered a crash? Open a ticket on the Issue Tracker.
| Info required | Example |
| Minecraft version | 1.20.1 · 1.21.1 |
| Loader + version | Forge 47.4.20+ · NeoForge 21.1.0+ |
| Guide mod version | 1.8.0 · 1.6.0-NeoForge |
| Related mods | List of mods that may interact with Guide (JEI, Curios, etc.) |
| Screenshots | Attach if the issue is layout-related |
| Crash report | Full latest.log or crash-report in a code block |
▸ The more details you provide, the faster the issue can be resolved.
| ✦ | ? Project | ? Author / Team | ⚡ Contribution |
| ? | Just Enough Items (JEI) | mezz | 游戏内配方集成 |
| ? | Curios | TheIllusiveC4 | 用于腰带集成的槽位框架 |
| ⚒️ | Minecraft Forge | LexManos · cpw | FML 生态系统 · MCP 工具 |
| ? | NeoForge | NeoForge Team | 适用于 1.21.1 的现代模组开发平台 |
| ? | JavaCV | bytedeco | 原生媒体库的跨平台 Java 封装 |
| ? | JavaCPP | bytedeco | FFmpeg / OpenCV 的原生绑定与预编译二进制文件 |
| ?️ | FFmpeg | FFmpeg Team | 视频解码、转码及流处理 |
| ? | Open Source Community | Everyone | Bug 报告、文档与支持 |
Licensed under the MIT License.
You are allowed to include Guide in your modpack.
Any modpack that uses Guide takes full responsibility for user support queries.
We only support official builds, not custom modified jars.
? Render complex multiblocks. Parse Markdown right inside the UI.
? Play video, GIFs and images — on Windows, macOS and Linux via FFmpeg.
? Fully customizable themes, per-book overrides, custom colors and chapter backgrounds, optional visual effects.
? Interactive BooksDirect-from-disk compilation. Multi-book namespaces, zero JAR packing. Full command suite for listing and opening books.
sidebar search /guide list /guide open unlock_tag index hot-reload |
? Multiblock ProjectionPreview and assemble complex structures step by step.
layers rotation zoom progress HUD NBT |
? Markdown EngineFull Markdown rendered live inside the GUI.
tables links spoilers items mobs sounds indentation search fulltext |
? MultimediaVideo, GIF and image playback directly in the book.
JavaCV FFmpeg GIF WebP URL fullscreen ducking cache |
? Explorer's JournalA personal notebook stored in the player's NBT. Notes, live Markdown preview, checklists, tables and spoilers.
notes editor preview checklists markdown NBT sync |
? Guide ScannerRight-click a block, mob, dropped item or fluid to jump straight to the matching chapter.
blocks mobs items fluids @bind: @bind_tag: choice screen |
⌨️ Guide KeybindsConfigurable hotkeys to open the book or the journal without touching the inventory.
B N rebindable inventory-aware Curios-aware |
? Themes & BackgroundsEvery UI element is themeable via JSON, including chapter backgrounds.
per-book colors chapterBackground color image URL effects lock |
?️ Universal ImagesPNG, JPEG, BMP and GIF supported everywhere — icons, backgrounds, media.
PNG JPEG BMP GIF local server URL |
? Curios IntegrationOptional. When Curios is installed, the book and journal can sit in the belt slot and appear on your model.
belt render optional |
? Mod & Quest HooksJEI bindings, in-book checkboxes, server-synced progress.
@bind: @bind_tag: quests UUID NBT |
? Book GatingHide books until a per-player unlock tag is granted by any command source.
unlock_tag KubeJS FTB Quests advancements |
? Book Gating |
▸ Per-Player Unlock Tags: Add unlock_tag to any book.json and the book stays hidden in the selector until the player holds the matching tag. Perfect for tutorial books, endgame manuals, or story-gated content.
▸ Command-Driven: /guide unlock <tag> and /guide lock <tag> grant or revoke tags; both accept an optional player argument (OP level 2) for admins. /guide unlocks lists your active tags, /guide unlocks clear wipes them all at once.
▸ Modpack-Friendly: Any system that can dispatch a command works — KubeJS events, FTB Quests rewards, advancements, or custom script packs. State is stored per-player in server-side NBT and synced on login and after every change.
|
? Explorer's Journal |
▸ Personal Notebook: The guide_diary item opens a private list of notes stored in the player's NBT. Every note holds a title, a body, a creation / update timestamp, and the coordinates + dimension where it was created. Notes survive relogs, dimension changes and client reinstalls; other players never see them, even on a server.
▸ Editor & Live Preview: The editor is a true multiline text box with cursor navigation, clipboard support (Ctrl+A/C/V/X) and a themed scrollbar you can drag. The preview renders the note the same way the book does — colors, styles, links, tables, dividers, spoilers and checklists — and refreshes with a 200 ms debounce while you type.
▸ Interactive Checklists: Markdown-style checkboxes (- [ ] / - [x]) toggle on left-click inside the preview. State is stored inside the note itself and saved on every click. Completed tasks show a green checkmark and a strikethrough; task color is set with an &-code prefix before the checkbox (&e- [ ], &c- [ ]).
▸ Journal Markdown Support: &0–&f colors, &l/&o/&n/&m styles, &r reset, external links [text](https://…), dividers (---, &6---, &l&9---), tables with wrap and drag-scroll, spoilers (@spoiler: / @endspoiler), and checklists. The editor converts &x into §x on the fly, so authors never type the section sign directly.
▸ Network Sync: Two payloads keep the journal in sync — a sync payload (server → client, sent on login) and an update payload (client → server, sent on create / update / delete). Last-write-wins conflict resolution, no confirmation roundtrip.
|
? Guide Scanner |
▸ One-Click Lookup: The guide_scanner item resolves the registry ID of a block, mob, dropped item or fluid and looks it up in the same binding map used by JEI and the G-key shortcut (@bind: / @bind_tag:). A single match opens the chapter instantly; multiple matches open a themed selection screen with a collapsible tree — one book expanded at a time, chapters nested underneath, chapter icons shown.
▸ Entity Raycast: Uses a custom AABB-clip raycast so small dropped items and thin hitboxes are detected correctly — vanilla projectile raycast misses them.
▸ Fluid Fallback: Scans water and lava by fluid ID first, then falls back to the bucket ID (water_bucket / lava_bucket) if no binding is found for the fluid itself.
▸ Cumulative Index: The scanner reads from itemToChapterRefMap, a second index that survives book reloads and covers every visible book — no need to open a book first.
|
⌨️ Guide Keybinds |
▸ Two Hotkeys: B opens the book selector and N opens the journal. Both are bound to the Guide category and can be rebound at any time in Options → Controls → Guide.
▸ Inventory-Aware: Each key only fires if the matching item (guide_book or guide_diary) is in your main inventory, off-hand, or a Curios slot. No item, no action — this prevents bypassing the book gating system with a hotkey.
|
? Multi-Book Config Autonomy |
▸ Direct-from-Disk Compilation: Automatically maps and loads guidebooks from your local machine at config/guide/books/[book_id]/. No more packing files inside mod JAR archives.
▸ Automated Blueprint Generation: On the very first launch, the mod extracts a complete, ready-to-build guidebook template into your config folder, protecting custom assets from being overwritten during modpack updates.
▸ Clean Book Selector: Features a fully responsive book catalog viewport with active filtering, rendering isolated book namespaces cleanly with zero mod-ID conflicts. Book order can be controlled via the optional index field in each book.json.
|
⚙️ Hot-Reload & Dev-Friendly Pipeline |
▸ Runtime Layout Swapping (/guide reload): Edit markdown files, layout nodes, textures, or JSON localization tables on your disk and instantly re-populate the guidebook memory in-game. Available to all players by default with no OP/cheat requirements.
▸ Quick-Access Chat Navigation (/guide): A dedicated chat handle that routes users directly to the main book catalog viewport from anywhere, removing item dependencies.
▸ Book Listing & Direct Open: /guide list prints all books visible to the client (with index, namespace, dev flag and display name); /guide list server shows what the server is distributing; /guide open <namespace> opens any book by ID with tab-completion.
▸ Item Shortcuts: /guide give <book|scanner|diary> [player] spawns the matching Guide item directly into the inventory, falling back to player.drop() when the inventory is full. Includes a 1-second per-player cooldown and tab-completion for aliases and players.
▸ Developer Mode Toggle: Hide instructional manuals or blueprints from players via config/guide/guide-client.toml while keeping them active for developers.
|
? Premium Navigation & Search Caret |
▸ Overhauled Search Box: Equipped with a clean vertical caret (|) that flawlessly executes movement sequences and text selections across both English and Cyrillic keyboard layouts.
▸ Smart Sidebar Sub-Menus: Seamlessly nests dropdown sub-chapters (@submenu:) and spoilers behind clicks, optimizing render framerates and preventing layout clipping.
▸ Unbreakable Tracking & History: Navigation memory locks the expanded state of sidebar submenus, and text hyperlink hitboxes mathematically track lines perfectly under any dynamic scrollbar offset.
▸ Full-Text Search Overlay: The sidebar search scans chapter content, not just titles. Typing a query opens an overlay with snippets around every match, grouped by chapter. Click a snippet to open the chapter, scroll to the matched line, and highlight the query in-place. The sidebar also keeps chapters that only match by content.
▸ In-Chapter Search (Ctrl+F): A browser-style find panel opens at the bottom of the chapter area. Every match is highlighted (active one in a different color); jump between matches with ↑ / ↓ or Enter / Shift+Enter, with a live N / M counter. Spoilers containing a match auto-expand; spoilers without a match stay collapsed. Search highlight colors are themeable via searchHighlightColor and searchHighlightCurrentColor.
|
? Advanced Content Rendering |
▸ Natural Text Indentation Support: The Markdown engine fully respects space and tab blocks at the start of text sequences, allowing for structured nested lists without desyncing hyperlink areas.
▸ Direct Media Streaming: Renders static images (@image:) and animated GIFs (@gif:) straight from the local book directory, completely neutralizing the checkerboard placeholder texture glitch. Supports PNG, JPEG, BMP and GIF (first frame).
▸ 3D Item & Block Models (@item:): Render rotating 3D item and block models inline in the page. Size is per-instance (16–128 px), alignment is configurable (left / center / right), and both flat items and full blocks respect the declared size. Hover for a tooltip with the registry ID and mod name.
▸ Consolidated Multi-Block NBT Projection: The 3D hologram projector (PlacementProjector) and the page renderer (StructureRenderer) compile .nbt blueprints directly from the config folder. Creators can bundle multi-block structures natively into their guides without external datapacks.
|
? Built-in Media System |
▸ Video Playback: Play local and remote video files (mp4, avi, mkv, webm) directly inside guide pages using the @video: command. Supports direct HTTP(S) links with automatic caching, and includes a custom player with play/pause, stop, replay, volume slider, fullscreen, and a draggable progress bar with seek support.
▸ GIF and Image URL Support: Use direct HTTP(S) links in @gif: and @image: to load animated GIFs and static images (PNG, JPEG) from the internet. Files are cached in config/guide/cache/media/ for offline reuse.
▸ Sound Integration: Use the @sound: command to embed clickable sound buttons that play custom audio files from the book's sounds/ folder. Supports per-page playback with automatic music ducking.
▸ Smart Background Music Ducking: When a video or custom sound starts, the mod automatically pauses background music and restores it after playback ends.
▸ Client-Only Safety: All media decoders, the FFmpeg native library downloader, the JavaCV bridge, and the texture uploader are annotated @OnlyIn(Dist.CLIENT). Dedicated servers never download FFmpeg binaries and never touch client-only video code.
|
? Themes & Chapter Backgrounds |
▸ Fully Themeable UI: Every interface element — panels, borders, buttons, scrollbars, tables, media player, projector — is defined by a JSON theme file. Custom themes are placed in config/guide/themes/ (client or server).
▸ Per-Book Overrides: Set a theme field in book.json to force a specific theme for a book; the global theme is restored when the book is closed. Priority: book theme > locked theme > global theme.
▸ Chapter Backgrounds: Themes can override the default chapter background with a chapterBackground block — a solid color (with adjustable alpha) or an image. Images can be a local file, a server-side file, or a direct URL (downloaded and cached automatically).
▸ Built-in Visual Effects: Optional per-theme effects: bloodEffects, forestEffects, cyberTechEffects, matrixEffects, sakuraEffects, honeyEffects.
|
? Mod & Quest Integration |
▸ Live Server-Synced Checkboxes: Features a client-to-server interactive quest system. Quest completions are bound to player UUIDs and securely saved inside the server-side NBT structure, protecting progression files from local data wipes.
▸ JEI Navigation Ready: Bind chapters to specific item entries using @bind:mod_id:item to trigger matching guide pages directly inside JEI, or click guide item passposts to instantly pull up active recipe sheets.
▸ Curios Belt Slot: The book and journal declare compatibility with the Curios belt slot through a data-driven tag. When Curios is installed, the equipped item is rendered on the player's model, and the B / N keybinds pick it up from there as if it were in the inventory. Curios is a soft dependency — the mod loads and runs fine without it.
|
| ⌨️ Command | Description |
| /guide | Open the main book catalog from anywhere — no item required |
| /guide reload | Hot-reload all markdown, textures, JSON and themes without restarting the game |
| /guide list | List all books visible to the client. Click a line to insert /guide open <namespace> into chat; hover for details |
| /guide list server | List books the server is currently distributing. Shows index, namespace, dev marker and disk path in hover |
| /guide open <namespace> | Open a specific book by namespace from chat. Supports tab-completion |
| /guide give <book|scanner|diary> [player] | Spawn a Guide item into your inventory, or into another player's with OP 2. Falls back to player.drop() when the inventory is full. 1-second per-player cooldown |
| /guide unlock <tag> [player] | Grant an unlock tag to yourself or another player (OP 2 for other players) |
| /guide lock <tag> [player] | Revoke an unlock tag from yourself or another player (OP 2 for other players) |
| /guide unlocks | List all unlock tags currently held by you |
| /guide unlocks clear [player] | Wipe every unlock tag from yourself, or from another player with OP 2. Useful for testing and admin housekeeping |
▸ All commands except /guide list server, /guide reload server-side, and player-targeted unlock / lock / give variants are available to all players by default — no OP or cheat requirements.
| ⚙️ Loader | ? Game | ? Version | ☕ JDK | ? Status | ? Branch |
 |
Forge |
1.20.1 |
1.8.0+ |
17 |
? Stable |
forge-1.20.1 |
 |
NeoForge |
1.21.1 |
1.6.0+ |
21 |
? Stable |
neoforge-1.21.1 |
▸ Both branches share the same feature set — multimedia, Markdown rendering, multiblock projection and book gating are on par. One small difference: on Forge, right-clicking the Curios belt slot opens the equipped item's screen (via ICurioItem.curioRightClick); on NeoForge this is no longer part of the Curios API, so use the N / B keybind instead.
| ? JEI | Bind chapters to items with @bind:mod_id:item. Click guide item passposts to instantly open recipes. Optional — Guide works fine without it. |
| ? Curios | Soft dependency. When installed, the guide_book and guide_diary can be equipped in the belt slot; the equipped item is rendered on the player's model, and the B / N keybinds pick it up from there. The slot itself appears automatically for any player once the mod is loaded — no manual configuration required. |
| ? FFmpeg / JavaCV / JavaCPP | Video decoding, transcoding, and frame-level media access through native FFmpeg binaries, wrapped by JavaCV and bundled via JavaCPP for Windows, macOS, and Linux. |
| ? Media Cache | Automatic background music ducking during video / sound playback, plus offline media caching. |
| ? KubeJS / FTB Quests / Advancements | Book gating hooks into anything that can dispatch a command. Grant tags with /guide unlock <tag> from KubeJS events, FTB Quests rewards, advancement functions, or script packs. |
config/guide/books/<book_id>/
├── chapters/ # Content sections
│ ├── index.md # Primary index
│ ├── introduction.md # First chapter
│ └── <language>/ # Language-specific files
├── lang/ # Localization
│ ├── en_us.json
│ └── <language>.json
├── models/ # 3D model data
├── sounds/ # Background audio (.ogg)
├── videos/ # Local video files
├── textures/ # UI and image assets
├── structures/ # Multi-block .nbt blueprints
└── book.json # Metadata
? Example book.json:
{
"name": "<book_id>.book.guide",
"namespace": "<book_id>",
"default_chapter": "introduction",
"icon": "your_logo.png",
"bg_music": "background_music",
"theme": "<theme_id>",
"dev_only": false,
"index": 0,
"unlock_tag": ""
}
▸ index is optional. Books are sorted by it in the selector (lower = earlier). Books without index fall to the end, sorted by namespace.
▸ unlock_tag is optional. Leave it empty to keep the book public; set a tag (e.g. "secret") to hide the book until the player receives that tag via /guide unlock secret. Tags are per-player and persist across sessions.
Every UI element is themeable via JSON. Custom themes live in config/guide/themes/ — copy the template below, tweak the colors, and save it as a new file (for example, my_theme.json).
Two dedicated colors control both the Ctrl+F panel and the full-text overlay: searchHighlightColor (all matches) and searchHighlightCurrentColor (active match). Built-in palettes ship with tuned defaults per theme.
Each theme can also define its own chapter background — a solid color or an image that replaces the default background for every chapter in books using this theme.
? Example standard.json (config/guide/themes/standard.json):
{
"id": "standard", // unique theme identifier
"displayName": "guide.theme.standard", // display name (plain string or translation key)
"chapterBackground": { // optional chapter background override
"type": "color", // "color" or "image"
"value": "0x0A0A0A", // RGB color (0xRRGGBB) when type = "color"
"alpha": 230 // 0 = transparent, 255 = opaque
},
"colors": {
// ===== General UI =====
"panelBackgroundColor": "0xCC1A1A1A", // panels background (book pages, side menus)
"panelHeaderBackgroundColor": "0xCC111111", // panel header background
"borderColor": "0xFF4A4A4A", // default border for panels and windows
"borderFocusedColor": "0xFF00D0FF", // focused element border
"textColor": "0xFFFFFF", // primary text color
"textSecondaryColor": "0x888888", // secondary text
"scrollbarTrackColor": "0x55111111", // scrollbar track background
"scrollbarThumbColor": "0xFF8B8B8B", // scrollbar thumb
"buttonColor": "0xFF2A2A2A", // default button
"buttonHoverColor": "0xFF3A3A3A", // button on hover
"buttonDisabledColor": "0xFF1A1A1A", // disabled button
// ===== Input Fields =====
"editBoxBackgroundColor": "0xFF000000", // input field background
"editBoxBorderColor": "0xFFA0A0A0", // input field border
"editBoxBorderFocusedColor": "0xFFFFFFFF", // input field border on focus
"editBoxTextColor": "0xFFFFFF", // input field text
// ===== Search Highlight (Ctrl+F) =====
"searchHighlightColor": "0x80FFEB3B", // all match highlights
"searchHighlightCurrentColor": "0xC0FF9800", // currently active match
// ===== Media Player =====
"mediaFrameOuterColor": "0xFF2D2D2D", // media outer frame
"mediaFrameInnerColor": "0xFF4A4A4A", // media inner frame
"mediaBackgroundColor": "0xFF000000", // playback area background
"mediaControlPanelColor": "0xCC000000", // control panel background
"mediaTextColor": "0xFFAAAAAA", // media player text
"mediaErrorTextColor": "0xFFFF5555", // error text
"mediaTimeTextColor": "0xFFCCCCCC", // playback time text
"progressBarTrackColor": "0xFF555555", // progress bar track background
"progressBarFillColor": "0xFF00D0FF", // progress bar fill
"progressBarThumbColor": "0xFFFFFFFF", // progress bar thumb
"progressBarThumbOutlineColor": "0xFF000000", // progress bar thumb outline
// ===== Inline Elements =====
"spoilerTitleColor": "0xFFAA00", // spoiler title
"inlineItemBackgroundColor": "0x550A0A0A", // inline item background
"inlineItemBorderColor": "0x25FFFFFF", // inline item border
"inlineItemTextColor": "0xFFAAAAAA", // inline item text
"soundButtonBackgroundColor": "0xFF2E2E2E", // sound button background
"soundButtonBorderColor": "0xFF5A5A5A", // sound button border
"soundButtonTextColor": "0xFFFFFF", // sound button text
"questStrikethroughColor": "0x77777777", // strikethrough quest text
// ===== Tables =====
"tableHeaderBackgroundColor": "0xFF222222", // table header background
"tableHeaderTextColor": "0xFFAA00", // table header text
"tableRowBackgroundColor": "0x11000000", // alternating row background
"tableBorderColor": "0xFF3A3A3A", // table borders
"tableCellTextColor": "0xFFFFFF", // table cell text
"dividerColor": "0xFF3A3A3A", // block dividers
// ===== Video Title =====
"videoTitleBackgroundColor": "0xCC2D2D2D", // video title panel background
"videoTitleBorderColor": "0xFF5A5A5A", // video title panel border
"videoTitleTextColor": "0xFFFFFF", // video title text
// ===== Warnings & Toasts =====
"warningTextColor": "0xFF5555", // primary warning text
"warningTextSecondaryColor": "0xFFAAAAAA", // secondary warning text
"toastBackgroundColor": "0xD0101215", // toast notification background
"toastTextColor": "0xFFFFFF", // toast notification text
// ===== Structure Panel =====
"structureFrameColor": "0x4000FFFF", // 3D structure preview frame
"structureTabActiveBackgroundColor": "0xFF555555", // active tab background
"structureTabInactiveBackgroundColor": "0xFF222222", // inactive tab background
"structureTabActiveTextColor": "0x00FFCC", // active tab text
"structureTabInactiveTextColor": "0x888888", // inactive tab text
"structureLayerTextColor": "0x55FF55", // structure layer label
// ===== Placement Projector =====
"projectorPanelBackgroundColor": "0xD0101215", // projector panel background
"projectorPanelBorderColor": "0x4000D0FF", // projector panel border
"projectorTitleTextColor": "0x00D0FF", // projector panel title
"projectorButtonBackgroundColor": "0x15FFFFFF", // default button background
"projectorButtonHoverBackgroundColor": "0x3000D0FF", // button background on hover
"projectorButtonBorderColor": "0x25FFFFFF", // default button border
"projectorButtonHoverBorderColor": "0xFF00D0FF", // button border on hover
"projectorButtonTextColor": "0xBBBBBB", // button text
"projectorButtonHoverTextColor": "0xFFFFFF", // button text on hover
"projectorDoneButtonHoverBackgroundColor": "0x3000FF55", // "Done" button background on hover
"projectorDoneButtonHoverBorderColor": "0xFF00FF55", // "Done" button border on hover
"projectorCancelButtonHoverBackgroundColor": "0x30FF2244", // "Cancel" button background on hover
"projectorCancelButtonHoverBorderColor": "0xFFFF2244", // "Cancel" button border on hover
"projectorHudTextColor": "0xFFFFFF" // projector HUD hint text
}
}
?️ Chapter Background (optional)
Add a chapterBackground block to your theme to override the default background (blur on NeoForge, gradient overlay on Forge). Three source types are supported:
// Solid color with alpha (0 = transparent, 255 = opaque)
"chapterBackground": {
"type": "color",
"value": "0x1A0F2E",
"alpha": 230
}
// Local or server-side image (resolved against the current book folder)
"chapterBackground": {
"type": "image",
"path": "textures/bg/my_bg.png"
}
// Direct URL (downloaded in background, cached on disk)
"chapterBackground": {
"type": "image",
"path": "https://example.com/background.jpg"
}
▸ Omit chapterBackground entirely to keep the default. URL images appear with a short delay on first load; subsequent openings use the cache. Supports PNG, JPEG, BMP and GIF (first frame).
Colors are written in 0xAARRGGBB format:
| Channel | Range | Description |
| AA | 00 – FF | Alpha channel (transparency). FF = fully opaque, 00 = fully transparent |
| RR | 00 – FF | Red channel |
| GG | 00 – FF | Green channel |
| BB | 00 – FF | Blue channel |
▸ Tip: set alpha below FF (e.g. 80) to make panels semi-transparent.
| Component | Minimum | Recommended | Notes |
| Minecraft | 1.20.1 · 1.21.1 | 1.20.1 or 1.21.1 | Pick the branch that matches your loader |
| Loader | Forge 47.x+
NeoForge 21.x+ | Latest stable release | Only one is required — choose per branch |
| Java | JDK 17
JDK 21 | 17 for Forge
21 for NeoForge | Version must match the loader branch |
| JEI (optional) | — | Latest for your MC build | Only needed for recipe integration via @bind: |
| Curios (optional) | — | Latest for your MC build | Only needed for the belt slot integration and on-model rendering |
▸ Guide works standalone — JEI, Curios, Quests, and other integrations are entirely optional.
Found a bug or encountered a crash? Open a ticket on the Issue Tracker.
| Info required | Example |
| Minecraft version | 1.20.1 · 1.21.1 |
| Loader + version | Forge 47.4.20+ · NeoForge 21.1.0+ |
| Guide mod version | 1.8.0 · 1.6.0-NeoForge |
| Related mods | List of mods that may interact with Guide (JEI, Curios, etc.) |
| Screenshots | Attach if the issue is layout-related |
| Crash report | Full latest.log or crash-report in a code block |
▸ The more details you provide, the faster the issue can be resolved.
| ✦ | ? Project | ? Author / Team | ⚡ Contribution |
| ? | Just Enough Items (JEI) | mezz | In-game recipe integration |
| ? | Curios | TheIllusiveC4 | Slot framework used for the belt integration |
| ⚒️ | Minecraft Forge | LexManos · cpw | FML ecosystem · MCP tools |
| ? | NeoForge | NeoForge Team | Modern modding platform for 1.21.1 |
| ? | JavaCV | bytedeco | Cross-platform Java wrapper for native media libraries |
| ? | JavaCPP | bytedeco | Native bindings & prebuilt binaries for FFmpeg / OpenCV |
| ?️ | FFmpeg | FFmpeg Team | Video decoding, transcoding & stream handling |
| ? | Open Source Community | Everyone | Bug reports, docs, and support |
Licensed under the MIT License.
You are allowed to include Guide in your modpack.
Any modpack that uses Guide takes full responsibility for user support queries.
We only support official builds, not custom modified jars.
评论 0
登录后参与评分
还没有评论,来抢沙发吧