Journey Mode is a premium Minecraft utility mod that introduces a Terraria-style research and progression system. Permanent item unlocks, dynamic crafting recipe-tree analysis, customizable JSON thresholds, and a robust global save profile system ensure that unlocks persist across multiple single-player worlds and multiplayer servers.

This is the first stable release of Journey Mode for Minecraft 1.16.5 (Forge and Fabric loaders) targeting Java 8 compatibility.

Journey Mode is a premium Minecraft utility mod that introduces a Terraria-style research and progression system. Permanent item unlocks, dynamic crafting recipe-tree analysis, customizable JSON thresholds, and a robust global save profile system ensure that unlocks persist across multiple single-player worlds and multiplayer servers.

This is the first stable release of Journey Mode for Minecraft 1.19.2 (Forge and Fabric loaders) targeting Java 17 compatibility.

Journey Mode is a premium Minecraft utility mod that introduces a Terraria-style research and progression system. Permanent item unlocks, dynamic crafting recipe-tree analysis, customizable JSON thresholds, and a robust global save profile system ensure that unlocks persist across multiple single-player worlds and multiplayer servers.

This is the first stable release of Journey Mode for Minecraft 1.20.1 (Forge and Fabric loaders) targeting Java 17 compatibility.

🚀 Complete Mod Reconstruction & Porting

• Experimental Recovery & Revamp: Previous experimental builds of both NeoForge and Fabric were broken due to the introduction of a complex multi-module architecture. We have completely revamped and reconstructed both loader projects back from the 1.4.0 codebase, which was the last verified stable build before introducing multi-module setups.
• 100% Bug-Free Native JARs: Both the Fabric 1.21.1 and NeoForge 1.21.1 mods are now compiled natively and work perfectly without any runtime bugs or crashes.
• Native NBT Saved Data Persistence: User player data is no longer saved in an external JSON file. Progress and unlocks are persisted natively inside standard level NBT attachments, resolving server portability and synchronization issues.
• Fabric 1.21.1 Native Port: Fully implemented the Fabric version inside the Fabric/ directory with 100% feature-parity.
• Enforced Gradle Mappings Isolation: Re-configured Gradle scripts to run official Mojang mappings (mappings loom.officialMojangMappings()) natively alongside Fabric Loader 0.19.2, ensuring perfect compile-time type-safety.
• Safe Container Mixins: Ported screen mixins (HandledScreenMixin.java) to inject cleanly on top of AbstractContainerScreen in the Mojmap environment.
• dimension-swap Immune Core: Fabric player unlock attachments utilize a robust static JVM map tracking handler inside GlobalDataHandler.java, keeping player data fully safe across dimension boundaries or deaths without relying on heavy platform serialization systems.

Journey Mode Fabric v1.0.0 - Initial Release

Release Date: October 31, 2025

🎉 Welcome to Journey Mode for Fabric!

This is the first Fabric release of Journey Mode, bringing all the features you love to the Fabric mod loader!

🏗️ Multi-Loader Architecture

Journey Mode now supports both Fabric and NeoForge thanks to our multi-loader architecture:

• ✅ 90% shared code - Same features across all loaders
• ✅ Common module - Platform-agnostic game logic
• ✅ Fabric module - Thin wrapper for Fabric-specific APIs

📦 Compatibility

Supported Versions

• ✅ Minecraft: All 1.21.x versions (1.21, 1.21.1, 1.21.2, 1.21.3, 1.21.4, and future 1.21.x)
• ✅ Fabric Loader: 0.15.0 or later
• ✅ Fabric API: Required
• ✅ Java: 21 or later

Version Range

• Minecraft: >=1.21 <1.22 - Works with all 1.21.x versions
• Single JAR - One file works across the entire 1.21 family!

🎮 Features

All features from the NeoForge version are included:

Core Gameplay

• 📦 Item Collection Tracking - Deposit items to unlock them permanently
• ♾️ Infinite Access - Retrieve unlimited copies of unlocked items
• 🎯 Smart Thresholds - Dynamic unlock requirements based on recipe complexity
• 💾 Persistent Storage - Your progress is saved with your player data

Journey Mode Toggle

• /journeymode on|off - Enable or disable Journey Mode per player
• Default: Enabled for all players
• Disabled players cannot open GUI or deposit items

Configuration System

• 📝 JSON-based configs in config/Journey Mode/
• blacklist.json - Prevent specific items from being unlockable
• custom_thresholds.json - Override unlock requirements per item
• Hot-reload support without server restart

Dynamic Thresholds

• Stack size 1 items (tools, armor): 1 item required
• Raw materials (ores, wood): Full stack (64) required
• Crafted items (Depth 1): 50% of stack (32) required
• Crafted items (Depth 2): 25% of stack (16) required
• Complex items (Depth 3+): Only 1 item required
• Recipe depth automatically calculated

User Interface

• 🎨 Dual-Tab GUI - Deposit tab and Journey tab
• 🔍 Search Function - Quickly find unlocked items
• 📊 Smart Sorting - Items sorted by unlock time
• ⌨️ Configurable Keybind - Press J to open (rebindable)
• 🖱️ Click to Retrieve:
  • Left-click: Get 1 item
  • Shift + Left-click: Get 64 items

📦 Installation

Requirements

1. Minecraft 1.21.x (any version from 1.21 to 1.21.x)
2. Fabric Loader 0.15.0+ - Download
3. Fabric API - Download
4. Java 21+ - Usually included with Minecraft

Steps

1. Install Fabric Loader for Minecraft 1.21.x
2. Download Fabric API and place in mods folder
3. Download journeymode_fab-1.0.0.jar from this release
4. Place both JARs in your .minecraft/mods folder
5. Launch Minecraft with Fabric

🆚 Fabric vs NeoForge

Both versions have identical features thanks to the shared common module:

• Same gameplay mechanics
• Same configuration system
• Same UI and controls
• Same save data format

Choose based on your preferred mod loader!

🔧 Technical Details

Architecture

• Common Module: Pure Java code with Gson serialization
• Fabric Module: Uses Fabric API for loader integration
• Service Loader Pattern: Automatic platform detection

Implementation

• Fabric Lifecycle Events for mod initialization
• Fabric Networking API for client-server communication
• Fabric Screen API for GUI rendering
• Component-based player data storage

Dependencies

• Fabric Loader: >=0.15.0
• Fabric API: Required (any recent version)
• Common module: Bundled in JAR

📝 Known Limitations

This is the initial Fabric release. Future updates may include:

• Full parity testing with NeoForge version
• Fabric-specific optimizations
• Additional Fabric integrations

🚀 What's Next?

Future Plans:

• Fabric 1.20.1, 1.19.2, 1.16.5 support
• Forge ports for older versions
• Cross-loader compatibility testing

📋 Full Changelog

Added

• ✅ Initial Fabric port for 1.21.x family
• ✅ All features from NeoForge version
• ✅ Fabric-specific implementations for networking, GUI, events
• ✅ Fabric API integration
• ✅ Multi-version support (1.21 to 1.21.x)

Technical

• Fabric Loader 0.16.5 target
• Fabric API 0.105.0+1.21.1
• Shared common module with NeoForge version
• Minimal Fabric-specific code (10% of total codebase)

---

Questions or issues? Report them on the GitHub Issues page!

Want to try NeoForge instead? Check out Journey Mode v1.6.0 for NeoForge

Journey Mode v1.6.0 - Full 1.21.x Family Support

Release Date: October 31, 2025

📦 Compatibility Update

This release extends compatibility to the entire Minecraft 1.21 family!

Supported Versions

• ✅ Minecraft 1.21
• ✅ Minecraft 1.21.1
• ✅ Minecraft 1.21.2
• ✅ Minecraft 1.21.3
• ✅ Minecraft 1.21.4
• ✅ And all future 1.21.x versions up to 1.22

Version Range

• Minecraft: [1.21, 1.22) - Works with all 1.21.x versions
• NeoForge: [21.1, 21.2) - Compatible with NeoForge 21.1+

🎯 What This Means

• Single JAR: One file works across all 1.21.x versions
• No Code Changes: Same features and functionality as v1.5.0
• Drop-in Upgrade: Replace your v1.5.0 JAR with this one
• Future-Proof: Automatically supports new 1.21.x releases

📝 Features (Same as v1.5.0)

All features from the multi-loader architecture update are included:

• ✅ Multi-loader architecture foundation
• ✅ Deposit slot properly hidden in Journey tab
• ✅ Fixed AttachmentType serialization
• ✅ Journey Mode toggle system (/journeymode on|off)
• ✅ JSON configuration (blacklist, custom thresholds)
• ✅ Dynamic unlock thresholds based on recipe depth
• ✅ Search and sorting in Journey tab
• ✅ Configurable keybind

📦 Installation

Requirements

• Minecraft: Any 1.21.x version (1.21, 1.21.1, 1.21.2, etc.)
• NeoForge: 21.1.72 or later
• Java: 21 or later

Steps

1. Download journeymode-1.6.0.jar from this release
2. Place in your .minecraft/mods folder
3. Launch Minecraft with NeoForge 1.21.x

⬆️ Upgrading from v1.5.0

• ✅ Drop-in replacement - No changes needed
• ✅ Config files - Fully compatible
• ✅ Player data - Automatically migrates
• ✅ All features - Work exactly as before

Simply replace the old JAR with the new one!

🔧 Technical Details

Changed

• Updated minecraft_version_range from [1.21.1, 1.22) to [1.21, 1.22)
• Tested compatibility across 1.21.x versions
• No API changes - pure compatibility extension

No Code Changes

• All code from v1.5.0 is unchanged
• Same multi-loader architecture
• Same bug fixes and features

🚀 What's Next?

Coming Soon: Fabric port for 1.21.x family (v1.0.0)

• Same features as NeoForge version
• Leverages shared common module
• Multi-version support from day one

---

Questions or issues? Report them on the GitHub Issues page!

Journey Mode v1.5.0 - Multi-Loader Architecture

Release Date: October 31, 2025

🏗️ Major Architectural Changes - Phase 2 Complete

Journey Mode has been completely restructured with a multi-loader architecture, setting the foundation for future Fabric and Forge ports!

Architecture Highlights

• ✅ 90/10 Split: 90% of code is now platform-agnostic, 10% loader-specific
• ✅ Common Module: Pure Java code with zero loader dependencies
• ✅ Platform Abstraction: Clean separation between game logic and platform APIs
• ✅ Service Loader Pattern: Automatic platform detection at runtime
• ✅ Future-Proof: Ready for Fabric and Forge ports in Phase 3

Project Structure

journey-mode/
├── common/                    # Platform-agnostic code (90%)
│   └── Core logic: JourneyData, ConfigHandler, ThresholdCalculator, UnlockLogic
├── neoforge-1.21.1/          # NeoForge-specific wrappers (10%)
│   └── Platform implementation, GUI, networking, events

🐛 Bug Fixes

Fixed: Deposit Slot Visibility in Journey Tab

• Problem: Deposit slot was visible and clickable in the Journey tab
• Solution: Created ConditionalSlot class with isActive() override
• Result: Slot is now properly hidden and disabled when Journey tab is active
• Impact: Prevents accidental item placement in wrong tab

Fixed: AttachmentType Serialization Error

• Problem: AttachmentType.Builder$1.buildException error on player data load
• Solution: Rewrote Codec using Codec.STRING.xmap() for proper JSON serialization
• Result: Player data now saves and loads correctly without errors
• Impact: No more crashes or data loss on player login

🎯 Benefits for Users

• Same Features: All functionality from v1.4.0 is preserved
• Better Stability: Fixed critical serialization and UI bugs
• Future Updates: Easier to add new features and support more loaders
• Cleaner Code: More maintainable and reliable

🔧 Technical Details

Common Module Components

• JourneyData.java - Pure Java data model with Gson serialization
• ConfigHandler.java - Platform-agnostic config management
• ThresholdCalculator.java - Recipe depth calculation logic
• UnlockLogic.java - Business logic for deposits and unlocks
• PlatformHelper.java - Platform abstraction interface

NeoForge Platform Components

• NeoForgeDataHandler.java - AttachmentType wrapper with fixed Codec
• NeoForgePlatformImpl.java - Platform implementation
• ConditionalSlot - Tab-aware slot with enable/disable logic

📦 Installation

Requirements

• Minecraft 1.21.1
• NeoForge 21.1.72 or later
• Java 21 or later

Steps

1. Download journeymode-1.5.0.jar from this release
2. Place in your .minecraft/mods folder
3. Launch Minecraft with NeoForge 1.21.1

⬆️ Upgrading from v1.4.0

• ✅ Drop-in replacement - No changes needed
• ✅ Config files - Fully compatible
• ✅ Player data - Automatically migrates
• ✅ All features - Work exactly as before

🚀 What's Next?

Phase 3: Multi-version support (Fabric and Forge ports)

• Fabric 1.21.1, 1.20.1, 1.19.2, 1.16.5
• Forge 1.20.1, 1.19.2, 1.16.5, 1.12.2
• NeoForge 1.20.1

The new architecture makes these ports much easier to implement!

📝 Full Changelog

Added

• Multi-loader architecture with common + platform modules
• ConditionalSlot class for tab-aware slot control
• Service loader pattern for platform detection
• Proper Gson-based serialization in common module

Fixed

• Deposit slot visibility in Journey tab (now properly hidden)
• AttachmentType Codec serialization errors
• Item slot interaction in wrong tab

Changed

• Project structure reorganized into multi-module Gradle project
• Core logic moved to platform-agnostic common module
• NeoForge-specific code isolated to platform module
• Codec implementation rewritten for reliability

Technical

• Build output: neoforge-1.21.1/build/libs/journeymode-1.5.0.jar
• Common module uses only Java + Gson dependencies
• Platform detection via META-INF/services/
• Cleaner separation of concerns

---

Questions or issues? Report them on the GitHub Issues page!

Phase 1 Complete

• Toggle system: /journeymode on|off
• JSON config: blacklist.json & custom_thresholds.json
• Hot-reload support
• Improved UX with localized messages

📋 Changelog

Version 1.3.4

Release Date: October 30, 2025

Major Feature

• ⌨️ Configurable Keybind: Journey Mode menu key is now customizable!
  • Default key: J (unchanged)
  • Configurable in: Options → Controls → Key Binds → Journey Mode
  • Can rebind to any key you prefer
  • Appears in dedicated "Journey Mode" category in controls menu

Technical Implementation

• Added KeyMapping for proper Minecraft keybind integration
• Registered keybind in RegisterKeyMappingsEvent
• Replaced hardcoded GLFW_KEY_J with KeyMapping.consumeClick()
• Added localization for keybind name and category
• Keybind state is saved in Minecraft's options.txt

User Experience

• Navigate to Options → Controls → Key Binds
• Scroll to "Journey Mode" category
• Click on "Open Journey Mode Menu" binding
• Press your desired key to rebind
• Changes save automatically

📋 Changelog

Version 1.3.3

Release Date: October 30, 2025

Bug Fix

• 🔧 Fixed Slot Outlines: Slot borders/backgrounds now match actual slot positions
  • Updated inventory slot outlines: y=84 → y=110
  • Updated hotbar slot outlines: y=142 → y=168
  • Outlines now perfectly align with clickable slot areas
  • Visual consistency restored

---

Version 1.3.2

Release Date: October 30, 2025

Major Improvements

• 🎨 Dynamic GUI Height: Increased GUI height to 204 pixels for proper spacing
  • Search box, inventory label, and all slots now have adequate room
  • No more overlapping elements in any tab
  • Clean, professional layout with breathing room

Layout Changes

• GUI height: 180px → 204px (24 pixels taller)
• Inventory slots: y=110 (was y=98)
• Hotbar slots: y=168 (was y=156)
• Inventory label: imageHeight - 104 (was - 80)
• Search box: y=86 (unchanged, now with proper spacing)

Visual Improvements

• Proper spacing between search box and inventory label
• Inventory label no longer overlaps with slots
• Search box no longer overlaps with inventory slots
• Consistent spacing throughout the GUI

---

Version 1.3.1

Release Date: October 30, 2025

Bug Fixes

• 🔧 Fixed GUI Layout Issues:

  • Moved inventory slots down by 14 pixels to match taller GUI (180px height)
  • Fixed "Inventory" label overlapping with slots in Deposit tab
  • Fixed search box overlapping with inventory slots in Journey tab
  • Search box now positioned at y+86 (above inventory)
  • Inventory label now at proper position (imageHeight - 80)

• 🔧 Fixed Item Loss on GUI Close:

  • Items left in deposit slot are now returned to player inventory when GUI closes
  • Added removed() override to handle cleanup
  • Prevents accidental item loss if you close GUI without submitting

Technical Changes

• Inventory slots moved from y=84/142 to y=98/156
• Search box moved from y=72 to y=86
• Inventory label Y position updated from -94 to -80
• Added proper cleanup in screen removed() method

---

Version 1.3.0

Release Date: October 30, 2025

Major Features

• 🔍 Item Search: Search box in Journey tab to quickly find unlocked items
  • Real-time filtering as you type
  • Case-insensitive search
  • Matches item display names
  • Shows "No items match search" when no results
• 📊 Smart Sorting: Items automatically sorted by unlock time
  • Most recently unlocked items appear first
  • Easier to find your latest unlocks
  • Combined with search for powerful item finding

Technical Improvements

• Added unlock timestamp tracking to JourneyDataAttachment
  • Stores millisecond timestamp when each item is unlocked
  • Persistent across game sessions via Codec serialization
• Enhanced SyncJourneyDataPacket to sync timestamps
• Added getUnlockedItemsSorted() method for timestamp-based sorting
• Search box appears only in Journey tab (auto-hides in Deposit tab)

User Experience

• Search box positioned below item grid (bottom of Journey tab)
• Type to filter items instantly
• Scroll wheel works with filtered results
• Item tooltips work correctly with search/sort

---

Version 1.2.0

Release Date: October 30, 2025

Major UI/UX Improvements

• 🔘 Submit Button: Items no longer auto-deposit - click "Submit" button to confirm
  • Green button appears when item is in deposit slot
  • Prevents accidental deposits
  • Shows clear visual feedback
• 📊 Live Item Info: When item is placed in deposit slot (before submitting):
  • Shows required threshold for that specific item
  • Shows current collected count vs. required
  • Shows progress percentage
  • Displays "Already Unlocked!" for unlocked items
• 🚫 Unlocked Item Protection: Cannot deposit items that are already unlocked
  • Shows green checkmark if item is already unlocked
  • Prevents wasting items on already-unlocked entries
• 🎯 Better Title Positioning: "Journey Mode" title moved higher to avoid tab overlap

Bug Fixes

• Fixed title overlapping with tabs
• Items no longer disappear when placed in deposit slot
• Clear visual feedback for all deposit states

User Experience

• Place item in slot → See requirements and progress → Click Submit → Item deposited
• Much clearer what's needed for each item type
• No more confusion about dynamic thresholds

📋 Changelog

Version 1.1.0

Release Date: October 30, 2025

Major Features

• 🎯 Dynamic Unlock Thresholds: Unlock requirements now adapt to each item!
  • Stack size 1 items (tools, armor, etc.): Require only 1 item
  • Raw materials (ores, wood, etc.): Require full stack size (64 for most, 16 for ender pearls)
  • Crafted items (Depth 1): Require 50% of stack size (32 for most items)
  • Crafted items (Depth 2): Require 25% of stack size (16 for most items)
  • Complex items (Depth 3+): Require only 1 item
• 🔍 Recipe Depth Analysis: Automatically calculates crafting complexity
  • Depth 0: Raw materials with no recipe
  • Depth 1: Items crafted from raw materials
  • Depth 2+: Items requiring multiple crafting steps
  • Handles cyclic recipes and multiple recipe paths

Implementation Details

• Added RecipeDepthCalculator class for analyzing recipe complexity
• Caches recipe depths for performance
• Detects and breaks recipe cycles
• Finds minimum depth when multiple recipes exist
• Dynamic threshold calculation per item

UI Changes

• Updated deposit tab to show "Dynamic per item" threshold
• Improved unlock messages to show required count
• Better progress messages showing current/needed amounts

Examples

• Diamond Pickaxe (stack 1): 1 required ✨
• Iron Ore (raw, stack 64): 64 required
• Iron Ingot (depth 1, stack 64): 32 required
• Iron Block (depth 2, stack 64): 16 required
• Redstone Comparator (depth 3+, stack 64): 1 required ✨

---

Version 1.0.1

Release Date: October 30, 2025

Bug Fixes

• 🐛 Fixed GUI Rendering Issues:
  • Added proper slot outlines for all inventory slots (now visible with dark borders)
  • Fixed text overlap - moved "Journey Mode" title above tabs
  • Fixed deposit tab instruction text positioning
  • Added proper borders and backgrounds for Journey tab item slots
• 🔄 Fixed Data Synchronization:
  • Unlocked item count now properly updates on client
  • Added SyncJourneyDataPacket for server-to-client data sync
  • Data syncs when menu opens and after each deposit
  • Journey tab now correctly shows unlocked items count

Technical Changes

• Added SyncJourneyDataPacket for client-server data sync
• Added updateFromSync() method to JourneyDataAttachment
• Enhanced renderBg() to draw slot backgrounds with borders
• Improved screen layout and text positioning
• Updated network packet registration

---

Version 1.0.0 (Initial Release)

Release Date: October 30, 2025

Features

• ✨ Core Journey Mode System: Track item collection and unlock infinite access after depositing 30 items
• 🎨 Dual-Tab GUI:
  • Deposit tab with single slot for item deposits
  • Journey tab displaying all unlocked items in a scrollable grid
• 🔄 Client-Server Networking: Synced item unlocking and retrieval system
• 💾 Data Persistence: Player data attachment with Codec serialization for save/load
• ⌨️ Keybind: Press J to open Journey Mode menu
• 📊 Progress Tracking: Visual feedback showing collection progress and unlock status
• 🎁 Infinite Item Retrieval: Click items in Journey tab to retrieve them (1x or 64x with Shift)

Technical Implementation

• NeoForge 1.21.1 compatibility (NeoForge 21.1.72)
• Custom AttachmentType for player data storage
• Custom MenuType and screen for GUI
• Network packet system for client-server communication
• Event system for player data cloning and menu opening

Known Limitations

• Unlock threshold is hardcoded to 30 items (no config file yet)
• Player data clone on death/respawn needs improvement
• GUI uses placeholder rendering (no custom texture file)
• No item filtering or search in Journey tab