Guide

[CHANGELOG] Hotfix: Version 1.2.1 (NeoForge)

Reduced Package Size & External Media Hosting

🛠️ Changes:

• Reduced JAR Size — Removed unused native libraries (opencv, tesseract, leptonica, etc.) from the mod resources, keeping only the essential JavaCV/FFmpeg components for Windows. This significantly reduces the mod file size, making it compatible with platforms that have strict upload limits.
• External Video Hosting — Demo videos are now hosted externally (e.g., GitHub) and referenced via direct URL in the guidebook, eliminating the need to bundle video files inside the mod.
• Updated Library Extractor — Adjusted JavaCvResourceExtractor to copy only the five necessary JARs (ffmpeg, javacpp, javacv and their Windows natives) instead of the full suite.
• Build Configuration Cleanup — Removed platform-specific native libraries for Linux and macOS from build.gradle, focusing on Windows to streamline the distribution.

[CHANGELOG] Hotfix: Version 1.4.1 (Forge)

Reduced Package Size & External Media Hosting

🛠️ Changes:

• Reduced JAR Size — Removed unused native libraries (opencv, tesseract, leptonica, etc.) from the mod resources, keeping only the essential JavaCV/FFmpeg components for Windows. This significantly reduces the mod file size, making it compatible with platforms that have strict upload limits.
• External Video Hosting — Demo videos are now hosted externally (e.g., GitHub) and referenced via direct URL in the guidebook, eliminating the need to bundle video files inside the mod.
• Updated Library Extractor — Adjusted JavaCvResourceExtractor to copy only the five necessary JARs (ffmpeg, javacpp, javacv and their Windows natives) instead of the full suite.
• Build Configuration Cleanup — Removed platform-specific native libraries for Linux and macOS from build.gradle, focusing on Windows to streamline the distribution.

[CHANGELOG] Version: 1.2.0 (NeoForge)

Multimedia Update — Full in-game media support: video, GIFs, and images from local files and URLs.

🎬 New Features:

• In-Book Video Playback Engine — Built a custom multimedia pipeline using JavaCV/FFmpeg for seamless decoding of local and remote video files (mp4, avi, mkv, webm) directly inside guide pages via @video:. The engine operates in a separate classloader to bypass ModLauncher restrictions, with low-latency options for smooth playback.
• Dynamic URL Media Downloader — Introduced MediaDownloadManager for asynchronous fetching of videos, GIFs, and images from direct HTTP(S) links. Features persistent caching in config/guide/cache/media/, automatic file extension detection, content type validation, and a configurable maximum file size (default 200 MB).
• Enhanced Video Player UI — Created a feature-rich embedded player with play/pause, stop, replay, volume slider (0–100% in 5% steps), fullscreen mode, and a draggable progress bar with seek support. The control panel is fully localized and adapts to GUI scale for consistent appearance.
• Animated GIF URL Support — Extended @gif: to accept direct links to .gif files. GIFs are downloaded in the background and displayed with correct frame timing and transparency handling.
• Image URL Support — Enabled @image: to load pictures from direct links (PNG, JPEG). While loading, a placeholder with localized "Loading..." text is shown, then the image appears with preserved transparency.
• Auto-Pause on Focus Loss — Video playback automatically pauses when the Minecraft window loses focus, conserving resources. Playback can be resumed manually after returning.
• Background Music Ducking — When a video starts, the mod temporarily silences vanilla and guide background music, and restores it after the video stops or ends, if music was enabled before.

🛠️ Improvements & Fixes:

• GIF Decoding Overhaul — Rewrote the GIF frame composition logic to correctly handle disposal methods (clear, restore to previous) and alpha transparency. This eliminates artifacts like black pixels, ghost frames, and frame accumulation in GIFs with partial updates.
• Video Seek and Volume Persistence — Fixed issues where seeking jumped to the beginning and volume reset to 100% on replay. The player now preserves volume state and allows precise seeking within the video.
• Localization and Cleanup — Replaced hardcoded Russian strings with localization keys across the media UI. Added new keys to ru_ru and en_us JSON files.
• Memory and Resource Management — Improved resource cleanup for video players and GIF textures when changing chapters or closing the book, preventing memory leaks and stale textures.
• JavaCV Packaging — Introduced automatic extraction of JavaCV/FFmpeg libraries from the mod JAR into a runtime directory, eliminating the need for users to manually copy native binaries. This was achieved via a resource extractor invoked at startup.
• NeoForge Compatibility — Fully adapted the multimedia system for NeoForge 1.21.1, achieving complete feature parity with the Forge 1.4.0 branch while maintaining server-safe client/server isolation.

[CHANGELOG] Version: 1.4.0 (Forge)

Multimedia Update — Full in-game media support: video, GIFs, and images from local files and URLs.

🎬 New Features:

• In-Book Video Playback Engine — Built a custom multimedia pipeline using JavaCV/FFmpeg for seamless decoding of local and remote video files (mp4, avi, mkv, webm) directly inside guide pages via @video:. The engine operates in a separate classloader to bypass ModLauncher restrictions, with low-latency options for smooth playback.
• Dynamic URL Media Downloader — Introduced MediaDownloadManager for asynchronous fetching of videos, GIFs, and images from direct HTTP(S) links. Features persistent caching in config/guide/cache/media/, automatic file extension detection, content type validation, and a configurable maximum file size (default 200 MB).
• Enhanced Video Player UI — Created a feature-rich embedded player with play/pause, stop, replay, volume slider (0–100% in 5% steps), fullscreen mode, and a draggable progress bar with seek support. The control panel is fully localized and adapts to GUI scale for consistent appearance.
• Animated GIF URL Support — Extended @gif: to accept direct links to .gif files. GIFs are downloaded in the background and displayed with correct frame timing and transparency handling.
• Image URL Support — Enabled @image: to load pictures from direct links (PNG, JPEG). While loading, a placeholder with localized "Loading..." text is shown, then the image appears with preserved transparency.
• Auto-Pause on Focus Loss — Video playback automatically pauses when the Minecraft window loses focus, conserving resources. Playback can be resumed manually after returning.
• Background Music Ducking — When a video starts, the mod temporarily silences vanilla and guide background music, and restores it after the video stops or ends, if music was enabled before.

🛠️ Improvements & Fixes:

• GIF Decoding Overhaul — Rewrote the GIF frame composition logic to correctly handle disposal methods (clear, restore to previous) and alpha transparency. This eliminates artifacts like black pixels, ghost frames, and frame accumulation in GIFs with partial updates.
• Video Seek and Volume Persistence — Fixed issues where seeking jumped to the beginning and volume reset to 100% on replay. The player now preserves volume state and allows precise seeking within the video.
• Localization and Cleanup — Replaced hardcoded Russian strings with localization keys across the media UI. Added new keys to ru_ru and en_us JSON files.
• Memory and Resource Management — Improved resource cleanup for video players and GIF textures when changing chapters or closing the book, preventing memory leaks and stale textures.
• JavaCV Packaging — Introduced automatic extraction of JavaCV/FFmpeg libraries from the mod JAR into a runtime directory, eliminating the need for users to manually copy native binaries. This was achieved via a resource extractor invoked at startup.

[CHANGELOG] Version: 1.0.1 (NeoForge)

Complete client/server decoupling for NeoForge 1.21.1 — first stable build that runs on dedicated servers without a single crash, achieving full feature parity with the Forge branch using native modern APIs.

Core Architecture & Server Safety:

• Client/Server Isolation Wall — Every GUI component, renderer, and projection handler is now strictly confined to the client side, ensuring the server never attempts to load Screen and eliminating startup crashes entirely.

• Proxied Screen Opening — A lightweight client-side opener class safely handles book interface creation without leaking client types into common paths, removing all BootstrapMethodError threats.

• Fixed AutomaticEventSubscriber Scanning — All client-only subscribers (commands, key mappings, GUI events) now explicitly declare value = Dist.CLIENT, preventing the NeoForge built-in scanner from loading them on dedicated servers.

• FMLEnvironment-Aware Guards — Invocations from shared items are wrapped with clean FMLEnvironment.dist.isClient() checks, acting as a final safety net against accidental server-side classloading.

• Modern Network Layer — The quest synchronization system has been migrated to CustomPacketPayload and PayloadRegistrar, ensuring seamless multiplayer sync without legacy channel overhead.

What This Means for NeoForge Community:

✅ NeoForge 1.21.1 servers launch with Guide without any errors — full dedicated server support is here.

✅ Absolute feature parity with the Forge branch — everything that works on the client works here, including holographic projections, interactive mob previews, and dynamic audio.

✅ Ready for large modpacks and public servers; the mod is no longer client-only and can be safely distributed.

[CHANGELOG] Version: 1.3.2 (Forge)

Complete client/server architecture separation — dedicated server compatibility finally achieved for Forge 1.20.1, eliminating all startup crashes while keeping every client feature intact.

Core Architecture & Server Safety:

• Full Client/Server Decoupling — Every screen, renderer, and input handler now strictly lives behind client-only boundaries. The server no longer attempts to load GUI classes, preventing the infamous Screen loading crash on startup.

• Safe Screen Opener Proxy — A dedicated client-side bridge now handles opening the book interface without ever exposing screen subclasses to common server code, completely removing BootstrapMethodError risks.

• Clean Event Bus Registrations — Removed all manual client-side registrations from the mod constructor and switched entirely to automatic EventBusSubscriber with explicit client-side distribution flags, ensuring projection and rendering hooks never load on dedicated servers.

• DistExecutor-Free Item Logic — Replaced ambiguous DistExecutor calls in book items with direct safe invocations to the client-only opener, guaranteeing zero classloading violations when the book is used on a server.

• Persistent Multiplayer Sync — Quest states, favorites, and network synchronization remain fully functional through the existing SimpleChannel pipeline, keeping multiplayer compatibility robust.

What This Means for Players & Server Owners:

✅ Forge 1.20.1 servers no longer crash when Guide is installed — the mod is now fully dedicated-server safe.

✅ All client-side features (animated GIFs, 3D mobs, soundscapes, placement projector) continue to work flawlessly in singleplayer and for connected clients on multiplayer servers.

✅ The mod can be safely added to any modpack without requiring server-side workarounds or removal of the JAR.

[CHANGELOG] Version: 1.0.0-NeoForge

Complete low-level architectural migration and deep core integration with the NeoForge 1.21.1 ecosystem, achieving absolute feature parity with the Forge branch while utilizing native modern engine pipelines.

Core Kernel & API Integration:

• Native NeoForge Event Bus Re-wiring — Completely refactored the mod's event architecture to hook directly into NeoForge's decoupled Mod and Forge buses. Extracted all registration sequences into modern deferred registries, eliminating legacy system overhead and ensuring clean initialization profiles.

• Modern Pipeline Synchronization — Rebuilt the 3D projection subsystem to align with NeoForge's rewritten RenderLevelStageEvent. Remapped world-space rendering passes to hook cleanly into the modern Stage.AFTER_PARTICLES pipeline, maintaining visual integrity across variable render distances without shader conflicts.

• Delta-Tracker Adaptation — Adapted the world assistant animation and raytracing threads to utilize NeoForge's modern DeltaTracker parameters for partial-tick calculations, ensuring butter-smooth camera-relative billboard transformations and animations at any framerate.

• Isolated GUI Graphics Hook — Migrated the entire screen-space interface, bossbars, and HUD modules to RenderGuiEvent.Post. Reconfigured all 2D text layout algorithms to natively utilize the modern GuiGraphics context, dropping deprecated blit systems.

Platform Feature Parity & Porting:

• Asynchronous GUI Icon Rasterization — Integrated a lightweight item-rendering proxy into the HUD thread, leveraging modern NeoForge item rendering. It extracts ItemStack data directly from cached BlockState structures to stream high-definition 2D or 3D block icons straight to the screen.

• Ray-Traced Hologram Interaction — Ported the precise vector-based intersection algorithm (AABB.clip) using native NeoForge player interaction range properties. It evaluates line-of-sight rays from player coordinates inside air blocks, enabling instant, error-free target block tracking.

• Direct OpenAL Audio Engine — Transferred the independent file-system streaming engine (GuideSoundManager) to handle disk-based asset loading seamlessly alongside NeoForge's resource packs, eliminating null-pointer exceptions and overlap bugs during page ticks.

• World-Anchor Placement Assistant — Successfully ported the client-side hologram projection framework (PlacementProjector) with full multi-axis rotation remapping, real-time progress calculations, error highlighting, and depth-stencil optimizations.

• EntityBlock Structural Wireframes — Maintained full contextual outline support for non-solid containers (chests, shulker boxes, banners, skulls) with precise tint configurations, now fully synchronized with NeoForge's render types.

[CHANGELOG] Version: 1.3.1

Feature-targeted release introducing a synchronized HUD projection engine for real-time item tracking and localized block tooltips.

New Features:

• Ray-Traced Hologram Interaction Tracker — Developed a precise vector-based intersection algorithm that projects a line-of-sight ray from the player's eye coordinates using the client's current block-reach distance. It accurately evaluates bounding-box intersections (AABB.clip) with phantom blocks in the world projection, completely bypassing vanilla raytrace limitations inside air blocks.

• Dynamic Crosshair HUD Overlays — Engineered an adaptive screen-space tooltip overlay positioned securely beneath the BossBar layer. When the raytracer detects a target block within the hologram boundary, the HUD dynamically displays its registered identity along with a localized prefix, eliminating the need to cross-reference сметы in a separate GUI.

• Vector-Stabilized Axis Alignment — Resolved an inherent 2D/3D matrix desynchronization where flat-sprite blocks (torches, saplings, flowers) would render offset or overlap adjacent text elements. Implemented a dedicated positional correction pass (getVisualFixY) that evaluates the underlying block hierarchy and dynamically shifts the Y-axis projection to ensure pixel-perfect center alignment with typography.

• Asynchronous GUI Icon Rasterization — Integrated a lightweight item-rendering proxy into the HUD rendering thread. It extracts the matching ItemStack definition directly from the hologram's cached BlockState and streams its high-definition 2D texture or 3D block model directly into the interface canvas immediately preceding the text layout.

• Old-School Paragraph Color Parsing — Re-engineered text processing for modern Minecraft lifecycles (1.19+ up to 1.21.1) where standard translation components drop vanilla paragraph markers. It bypasses string-sanitization layers via raw resource localization, enabling proper hardware-level parsing of nested color codes (§7, §e) directly out of the JSON language pack.

Improvements & Fixes:

• Zero-Interference HUD Layering — Optimized the layout matrices within the GUI render event, shifting the current block info panel to a fixed offset (barY + barH + 16). This prevents visual collision with the progress bars, completed-structure macros, or sub-hotbar screen widgets.

• Isolated Translation Bundles — Added new schema nodes (guide.projector.hud.current_block) across all supported language configuration packs, cleanly handling parameterized string injection (%s) for localized block titles without hardcoded values.