Guide
- By
An interactive in-game guidebook mod featuring smooth UI rendering, Markdown parsing, and 3D multiblock previews.
Curse Maven Snippet
What's new
📘 Version 1.7.0 (NeoForge) — Cumulative Update: Journal, Scanner, Keybinds, In-Game Customization Editor, CurseForge Compliance, Opt-In FFmpeg
This is a cumulative release for CurseForge. It includes all features and fixes from the previously unreleased 1.6.0 update (Journal, Scanner, Keybinds, Curios) plus everything new in 1.7.0 (In-Game Customization Editor, Maven Central compliance, opt-in native downloads).
🛠️ Changes:
• CurseForge Compliance (Maven Central) — Native media libraries (FFmpeg, JavaCV) are no longer fetched from personal GitHub repositories. They are now downloaded directly from the official Maven Central repository (
repo1.maven.org), fully complying with mod hosting security guidelines.• Opt-in Native Downloads — A new client config option
allow_native_downloads (default: false) has been added to guide-client.toml. Video playback requires the user to explicitly enable this option and restart the game, which then downloads the required FFmpeg binaries in the background.•
/guide unlocks clear [player] — Clears every unlock tag the player currently holds in one command. Without arguments, wipes your own tags; with a player argument (OP level 2), clears someone else's.•
/guide give <item> [player] — Spawns a Guide item straight into the inventory by short alias (book, scanner, diary). Falls back to player.drop() when the inventory is full. Includes a 1-second per-player cooldown and tab-completion.• Guide Scanner Item — A new item that scans the world and opens the matching chapter. Right-click on a block, mob, dropped item, or fluid — the scanner resolves the registry ID and looks it up in the same binding map used by JEI and the G-key shortcut. If a match is found in a single book, the chapter opens instantly; if multiple, a themed selection screen appears with a collapsible tree. The scanner has an animated 6-frame icon.
• Scanner Binding Map —
GuideNavigator now maintains a second cumulative index (itemToChapterRefMap) that stores book namespace, chapter file, chapter title and chapter icon. It survives across book reloads.• Explorer's Journal Item — A personal notebook stored entirely in-game. Create, edit, search and delete notes from a themed UI. Each note stores title, body, timestamp, coordinates and dimension. Saved to the player's NBT (
GuideDiary) and synced to the client on login.• Journal Editor & Live Preview — Two tabs: Editor and Preview. The editor is a true multi-line text box with cursor navigation, clipboard support, automatic scrolling and a themed scrollbar. The preview renders the note exactly like a chapter page and refreshes live with a 200 ms debounce.
• Journal Checklists — Markdown-style checkboxes (
- [ ] / - [x]) are interactive inside the note preview. Left-click to toggle; the state is stored in the note's NBT and survives relogs.• Journal Markdown Support — Color codes, styles, external links, dividers, Markdown tables with per-column wrap, spoilers and checklists. The editor converts
&x codes into §x on the fly.• Journal Network Sync — Two payloads keep the journal in sync:
SyncDiaryPayload (server → client) and UpdateDiaryPayload (client → server). Last-write-wins.• Guide Keybinds — Two configurable hotkeys:
B opens the book selector and N opens the journal. Both are inventory-aware and only work if the matching item is in the inventory, off-hand or a Curios slot.• Curios Integration —
guide_book and guide_diary now declare compatibility with the Curios belt slot through a data-driven tag. Curios is an optional dependency.• In-Game Customization Screen — A new
CustomizationScreen (560×340) with a sidebar of 12 tabs (4 implemented), a book selector, and scissor clipping. Layout is recomputed from winW/winH, so all buttons fit at GUI scale 2, 3 and 4.• Icon Tab — Pick from 5 item presets or from an image gallery in
config/guide/user/icons/. PNG, JPG, JPEG, GIF and BMP are accepted. Icons are rendered with UV-based scaling directly on the GPU.• Icon Rendering — Fit-To-Slot — Any image size is accepted. Large images are downscaled with aspect preserved; small images are drawn at native size and centered.
• Cursor Tab — Full cursor editor in
config/guide/user/cursors/. Per-book cursor override with fallback chain: book.json > user UI choice for this book > global (_global) > default.• Cursor Scale (1×–4×) — A single button cycles cursor size. Scaling is nearest-neighbor.
• Cursor Hotspot — Center or manual X/Y in original image pixels. X/Y fields save on the fly.
• Global Cursor Fallback — A
_global fallback can be set in customization.json for any book without its own override.• URL Downloads For Icons & Cursors — Both tabs ship with a URL field and a Download button. Files are fetched through
MediaDownloadManager and validated by magic bytes.• Cursor Overrides In
book.json — Five new optional fields: cursor, cursor_selector, cursor_diary, cursor_scale, cursor_hotspot.• Theme Tab — Full list of 70 theme fields with an HSV picker, alpha slider, hex input, live preview and 6 effect toggles. Built-in themes are read-only with a 🔒 tooltip.
• Background Tab — Three modes: Color, File and URL. Background overrides are stored per-book and resolved with the
user: prefix.• Themed Effect Toggles (Radio Mode) — Six theme effects can be toggled. Only one active at a time. Effects are stored per book and per theme.
• CustomizationStore — A single JSON file at
config/guide/user/customization.json holds icon, cursor, cursorScale, cursorHotspot, theme, effects, background.• CustomizationResolver — Resolves the effective theme for UI through
ThemeManager.getStable() and for gameplay rendering through ThemeManager.getCurrent().• ThemeManager Additions —
getStable(), withOverrides(), withEffects(), ThemeAccent, getThemesDir(), isValidThemeId().• Create Custom Theme — A Create Theme button writes the current editor state to
config/guide/themes/<id>.json. Reserved ids, existing files and taken ids are rejected.• Delete Custom Theme — Local themes can be deleted from the Theme Tab. Built-in and server themes show the ✕ greyed out.
• Live Color Preview — Dragging the HSV picker recolors the whole editor immediately. The preview is non-destructive.
• Per-Book Theme Overrides With Migration — Overrides are stored as
theme.<book>.<themeId>.<field>. Old files are migrated silently.• Per-Book Per-Theme Effect Overrides — Effects are stored as
effects.<book>.<themeId>.<effect> and follow the same migration path.• Read-Only Themes By Source — Editability is decided by
ThemeSource (BUILTIN/SERVER/LOCAL). LOCAL themes are fully editable.• Reserved Theme IDs — The seven built-in ids are reserved and cannot be created or removed.
• Theme Inheritance For Selector & Diary — The book selector and diary follow the theme context of the last opened book.
• Per-Book Theme Forcing In book.json — New
theme_selector and theme_diary fields.• Status In Buttons — Apply, Reset and Refresh show their result directly in the button label, reverting after roughly two seconds.
• Icon Prefixes —
item:, texture:, user: prefixes are now supported. Unprefixed strings still work through the legacy heuristic.• URL Mode in Background Tab — The URL box uses the reworked
GuideEditBox. Switching to a different URL re-downloads the preview.• GuideEditBox — Editable Mode — The shared edit box now supports an
editable flag.• Custom Tooltips — Custom tooltips use
font.split() with edge detection and flip to the opposite side when needed.• HTTP User-Agent Headers —
MediaDownloadManager sends proper User-Agent and Accept headers.• Localization — Roughly 150 new keys across
en_us.json and ru_ru.json.• Hooks in Existing Classes —
GuideScreen, BookSelectorScreen, ThemeManager, ModCommands and DiaryScreen now read from CustomizationStore.
🐛 Fixes:
• Curios Was Required on NeoForge — Curios was incorrectly declared as a hard dependency in
neoforge.mods.toml. The deprecated mandatory=false field is ignored on NeoForge 21.x; the dependency now uses type="optional". The mod loads and runs without Curios. JEI was fixed the same way.• Curios Belt Rendering — Equipped items are now visible on the player's model when placed in a Curios belt slot. Rendering is client-side only.
• Block Size in
@item: — The @item:modid:block,size,align directive now respects the size parameter for block items exactly like flat items.• Dedicated Server Crash on Media Load — JavaCV / FFmpeg native libraries were being initialized on dedicated servers at startup, causing
UnsatisfiedLinkError and a hard crash. All media decoders, the native downloader, the JavaCV bridge and the texture uploader are now marked @OnlyIn(Dist.CLIENT).• Edit Box Placeholder Overlap — Placeholders are now drawn only while the field is empty.
• Edit Box Double Border — The custom frame is drawn precisely over the vanilla one, so only the theme border is visible.
• Journal Content Touching the Scrollbar — The content area now reserves consistent right-side padding.
• Journal Tables with Many Columns — The sizing pass performs an emergency proportional shrink after the normal pass.
• Journal Spoiler Toggle Reset Scroll — Spoiler state is kept between rebuilds and toggling no longer forces a full rebuild.
• Journal Checklist State Lost on Reopen — Checklist states are now stored inside the note itself (
GuideDiary.Notes[N].quests) and saved on every toggle.• Journal Note Title Not Formatted in List — Titles are now passed through the same formatter as chapter text.
• Missing FFmpeg Chat Warning — If a player tries to play a video while FFmpeg is missing or disabled, the mod displays a clear localized message explaining how to enable video support.
• Theme Manager NPE On Startup —
RESERVED_IDS was declared below INSTANCE. Static fields were reordered.• Picker Jitter on Theme Switch — The HSV picker now reads through
ThemeManager.getStable().• Effect Buttons Not Resetting — The override is now read first and inverted afterwards.
• Effects Were Selector-Only — Effects are now applied in every Guide screen.
• Builtin Themes Were Editable — Editability is now decided by theme source.
• Layout Broke at GUI Scale 3/4 — Button positions are computed from
winW/winH with per-tab scissor clipping.• Icons Looked Blurry — Icon rendering no longer calls
resizeSubRectTo; the GPU filters the texture cleanly.• Icon/Cursor Refresh Didn't Rebuild The Grid — The grid is rebuilt after every scan.
• Texture Leak On Refresh — Old GPU textures are released before every rescan.
• Cursor Hotspot X/Y Not Saved While Typing — Values are now saved as soon as the number changes.
• Cursor Not Applied Live In Customization —
CustomizationScreen applies the cursor on init and after every change in the Cursor tab.• Cursor Tooltips Cut Off / Wrong Style — Tooltips use
font.split() and flip to the opposite side when needed.• Cursor Tooltip Y Disappeared — The custom tooltip hitbox now covers the full control row.
• Bad PNG Signature When Loading URL Images — Files are checked by magic bytes before decoding; short errors are shown in the UI.
• JEI Integration Silently Swallowed Errors — Both paths now log through
Guide-JEI with the failing item stack.• HTML Color Codes in Button Status — Status values now use
§a, §c and §7 prefixes.• Local Backgrounds Not Applying — Local files are now read from
config/guide/user/backgrounds/ with the user: prefix.•
switchBook Reset State With One Book — It now returns early if size() <= 1.• Background Cache Outlived Its File —
GuideScreen.clearBackgroundCache() releases every loaded background texture and is called from Refresh and Reset.• URL Preview Stuck On First Link — The preview now tracks the source URL and re-downloads when the input changes.
• File Preview Read On Every Frame — The texture is cached per selected file and released when the selection changes.
• Background Tab Ignored Theme Changes —
BackgroundTab.onThemeChanged() releases both preview caches and re-syncs the override.• Book Theme Applied Multiple Times —
pushBookTheme checks against getCurrentThemeId() so the transition completes cleanly.• Customization Screen Shake Moved The Background — The backdrop is now drawn before the shake pose.
• Duplicate Modals Under The Create Dialog — The hex readout and picker are skipped while a modal is open.
🧹 Removed / Cleaned:
•
ThemeSelectScreen.java Removed — Its functionality moved into CustomizationScreen. The guide.theme.select.title key was dropped along with it.• Hardcoded Russian Strings Removed — All tabs now use
Component.translatable. Theme.getFieldLabel() resolves through guide.customization.theme.field.*.• Hardcoded
READONLY_THEMES Removed — Editability now comes from ThemeSource (BUILTIN/SERVER/LOCAL).All Relations
- All Relations
- Embedded Library
- Optional Dependency
- Required Dependency
- Tool
- Incompatible
- Include
