v26.0.0-alpha.5.1 - Critical NeoForge Fixes

MCDebugLauncher v26.0.0-alpha.5.1

Release Date: 2026-08-01

Critical Fixes

This hotfix release addresses critical issues in Alpha 5 that prevented NeoForge 21.10+ instances from launching correctly.

Fixed

1. NeoForge version selection now prioritizes stable releases

   • Previous: Alphabetical sorting caused 21.10.0-beta to be selected over 21.10.64
   • Fixed: Semantic version comparison ensures stable releases are selected before pre-releases
   • Impact: mdl create --loader neoforge --loader-version latest now correctly installs the newest stable version

2. NeoForge patched client path corrected

   • Previous: Looked for net/neoforged/neoforge/<version>/neoforge-<version>-client.jar (incorrect)
   • Fixed: Now uses correct Maven path net/neoforged/minecraft-client-patched/<version>/minecraft-client-patched-<version>.jar
   • Impact: Eliminates "NeoForge patched client not found" warnings and ensures deobfuscated classes are available

3. Version mismatch detection

   • Added runtime check to detect when instance.json and version.json versions don't match
   • Provides clear error message instead of cryptic "Missing main class" errors
   • Helps users identify when instance recreation is needed

Changed

• Code quality: Removed 24 unused import warnings
• Total warnings reduced from 58 to 34

Upgrading from Alpha 5

Important: If you created NeoForge instances with Alpha 5, you should recreate them with Alpha 5.1:

# Backup your worlds first if needed
mdl backup create <instance-name> world-backup

# Remove the old instance
rm -rf "%APPDATA%\mdl\instances\<instance-name>"

# Recreate with correct version
mdl create <instance-name> --mc-version 1.21.10 --loader neoforge --loader-version latest

Installation

Windows (x64)

1. Download mdl-v26.0-alpha.5.1-windows-x64.zip
2. Extract to a directory in your PATH (e.g., C:\Program Files\mdl\)
3. Or run mdl setup to add to PATH automatically

Verify Installation

mdl --version
# Should output: mdl 26.0.0-alpha.5.1

Testing

All 18 unit tests pass. Manual testing confirms:

• NeoForge 21.10.64 instances create correctly
• Patched client is found at correct Maven path
• Launch proceeds without "Missing main class" errors
• Version mismatch detection triggers correctly

Known Issues

• NeoForge extra JAR (client-<neoform>-extra.jar) may still show warnings but doesn't prevent launch
• Some dead code warnings remain (reserved for future features)

Technical Details

Root Causes Fixed

1. Version Selection Algorithm

   • Old: versions.first() after alphabetical sort
   • New: Semantic version comparison with stable > pre-release priority
   • Implementation: Custom compare_versions() function in src/loader/neoforge.rs

2. Patched Client Path

   • NeoForge official installer outputs to net/neoforged/minecraft-client-patched/
   • Previous code used legacy path from pre-installer implementation
   • Fix: Updated path construction in src/instance/launcher.rs

Commits in This Release

• edc37f1 Fix NeoForge version selection and mismatch detection
• 2da8606 Clean up unused imports and variables
• b5bf224 Fix NeoForge patched client path
• ae395f6 Bump version to 26.0.0-alpha.5.1

Links

• GitHub Repository
• Full Changelog
• Issue Tracker

License

Apache License 2.0 - See LICENSE file for details

v26.0 Alpha 5

MCDebugLauncher v26.0 Alpha 5 - Release Summary

Release Date

2026-07-31

Version Information

• Version Number: v26.0.0-alpha.5
• Binary Size: 9.2 MB
• Branch: bugfix/neoforge-classpath-and-features
• Commits: 3 commits
• Test Status: ✅ All Passed (16/16 tests)

---

🔧 Key Fixes

1. NeoForge Fatal Startup Error Resolution

Problem Description:

Fatal Startup Error: Failed to create entrypoint object
net.neoforged.fml.startup.FatalStartupException: 
Missing main class net.minecraft.client.main.Main from the game content loader

Root Cause:

• NeoForge relies on the patched client JAR (deobfuscation + binary patches) generated by the installer
• MDL skips the vanilla client JAR for NeoForge instances
• If the patched client is missing or corrupted, core Minecraft classes become unavailable
• This issue is more likely to occur in multi-mod environments

Solution:

• Added fallback logic within the build_classpath() function
• Automatically append the vanilla client JAR to the classpath when a missing patched client is detected
• Guarantee consistent availability of core classes such as net.minecraft.client.main.Main
• Log warnings to facilitate debugging

Code Location: src/instance/launcher.rs Lines 514-524

---

✨ New Features

2. Automatic Update System

Commands:

mdl update --check    # Only check for updates
mdl update            # Interactive update

Feature Highlights:

• ✅ GitHub API integration for automatic latest release detection
• ✅ Semantic version comparison (supports alpha/beta tags)
• ✅ Automatic download of new binary builds
• ✅ Automatic backup creation (.exe.bak) prior to updates
• ✅ Batch script generation for safe replacement on Windows
• ✅ Manual download link provided upon network failures

Implementation File: src/util/selfupdate.rs (192 lines)

3. Environment Variable Registration

Command:

mdl setup    # Add MDL to PATH

Feature Highlights:

• ✅ Automatically add MDL to system PATH (Windows)
• ✅ PowerShell integration for environment variable modification
• ✅ Duplicate entry detection to avoid redundant additions
• ✅ Automatic update check during setup
• ✅ Cross-platform awareness (manual configuration prompt for non-Windows systems)

Usage Scenario:
After running mdl setup once, the mdl command can be invoked directly in any terminal without specifying the full file path.

4. Mod Display in Window Title (Existing Feature Validation)

Feature Description:

• Terminal window title: MDL: <Instance Name> [Mod1, Mod2, ...]
• Game window title: Identical format (via the --title argument)

Example:

Loaded 2 mod(s) in 'bc-test':
  - Fabric API (0.119.4+1.21.4)
  - MinecraftBC (2.0.0)

[Window Title]: MDL: bc-test [Fabric API, MinecraftBC]

Purpose: Quickly identify the corresponding instance and mod environment for each window during multi-instance testing.

---

📊 Technical Statistics

Code Changes

• Modified Files: 4
• New Lines Added: 274 lines
• New Module: src/util/selfupdate.rs

Affected Components

• src/instance/launcher.rs - NeoForge classpath logic
• src/main.rs - New update and setup commands
• src/util/mod.rs - Register selfupdate module
• src/util/selfupdate.rs - Full self-update implementation

Dependencies

No new dependencies added; existing dependencies used:

• reqwest - HTTP requests
• tokio::fs - Asynchronous file operations
• serde_json - GitHub API parsing
• anyhow - Error handling

---

🧪 Test Validation

Automated Tests

running 16 tests
✅ All tests passed

Manual Testing

• ✅ NeoForge 1.21.1 instances launch normally
• ✅ Version checking for update command works as intended
• ✅ Setup command successfully adds PATH entry
• ✅ Mod list displayed correctly within window titles
• ✅ Fabric/Forge instances remain unaffected

---

📦 Release Assets

Release Package Contents

release/mdl-v26.0-alpha.5-windows-x64/
├── mdl.exe                (9.2 MB)
├── README.md              (4.2 KB)
├── README_CN.md           (3.7 KB)
├── CHANGELOG.md           (3.9 KB)
├── LICENSE                (620 B)
└── BUGFIXES_ALPHA5.md     (5.6 KB)

Git Information

• Branch: bugfix/neoforge-classpath-and-features
• Based On: v26.0-alpha.4 (tag: v26.0-alpha.4)
• Commits:
  1. d49635e - Fix NeoForge classpath bug and add self-update features
  2. 4452d19 - Bump version to 26.0.0-alpha.5
  3. 84f2536 - Add detailed documentation for Alpha 5 fixes

---

📝 User Migration Guide

For Existing Users

• ✅ No Breaking Changes
• ✅ Existing instances function without modification
• ✅ New commands are optional enhancements
• 💡 It is recommended to run mdl setup once for convenient PATH access

Upgrade Steps

# Method 1: Manual Replacement (Auto-update unavailable in current Alpha 5)
1. Download mdl-v26.0-alpha.5-windows-x64.zip
2. Extract and replace the existing mdl.exe
3. Run mdl setup (Optional)

# Method 2: Automatic Update for Future Versions
mdl update

---

🔮 Future Roadmap

Alpha 6 Plans

• Performance optimization (loading speed for large modpacks)
• Cache improvements to reduce repeated downloads
• Memory consumption optimization

Beta 1 Targets

• TUI interface (interactive terminal interface)
• Or GUI wrapper (Under consideration)

Long-Term Goals

• Cross-platform binary distribution (Linux, macOS)
• Plugin system supporting custom mod loaders
• Modrinth/CurseForge integration for automated mod downloads
• Instance template and cloning functionality

---

🙏 Acknowledgements

This release resolves the critical NeoForge startup issue reported by the community and implements the user-requested automatic update system. Feedback from all testers is greatly appreciated.

---

📞 Support

• Issue Reports: GitHub Issues
• Documentation: README.md, README_CN.md
• Technical Details: docs/BUGFIXES_ALPHA5.md

---

Version: v26.0.0-alpha.5
Release Date: 2026-07-31
Next Version: v26.0.0-alpha.6 (Planned)

v26.0 Alpha 3

What's Changed

Bug Fixes

Fabric classpath / library download

• Loader libraries (intermediary, ASM 9.7.x, fabric-loader itself) are now downloaded at launch time when not already cached. Previously only path resolution was attempted, causing silent skips and resulting in ClassNotFoundException on startup and Fabric's duplicate-library rejection.
• Added support for Fabric/Quilt-style library entries that carry only a Maven repository base URL rather than a full per-artifact download record.
• Fabric intermediary mappings are now written to version.json and downloaded explicitly during mdl create, fixing the method_30611 crash observed with any mod including fabric-api alone.

NeoForge mainClass inheritance

• VersionJson.mainClass is now treated as optional. Installer-produced JSONs that omit the field no longer cause a deserialization panic; the launcher falls back to the base Minecraft version JSON.

Agent server

• Fixed LaunchOptions::default() call in the agent HTTP executor after the struct gained new fields in Alpha 2.

New Features

Game window title

• The Minecraft window title is set to MDL: <instance> [mod1, mod2, ...] via the --title argument (Minecraft 1.14+), making it easy to identify which test session a game window belongs to.

Asset mirror support

• Set the environment variable MDL_ASSETS_MIRROR to a CDN base URL (e.g. https://bmclapi2.bangbang93.com) to override the default Mojang asset server. Useful in regions where resources.download.minecraft.net is unreliable.

mdl agent single-instance lock

• A second mdl agent invocation now exits immediately with a clear message showing the existing process PID and interface address, instead of failing with a raw port-binding error.

Fabric API auto-install

• mdl create --loader fabric now automatically downloads and installs the latest compatible Fabric API from Modrinth into the instance mods/ directory. Non-fatal: logs a warning if the download fails.

---

Full Changelog: v26.0-alpha.2...v26.0-alpha.3

v26.0 Alpha 2

Pre-release build of MCDebugLauncher v26.0 Alpha 2.

Highlights

• NeoForge fixed: launch now delegates the deobfuscation + binary-patch pipeline to the official installer via --install-client. Patched client and universal JARs bypass coordinate-based deduplication, and game arguments are passed verbatim without an incorrect --gameJar injection. Verified launching to the main menu on Minecraft 1.21.1.
• Java auto-provisioning: a suitable JDK/JRE is resolved from the cache, then the system, and finally auto-downloaded from Adoptium when missing or too old.
• On-demand asset download: the asset index and objects are fetched into the shared cache during launch when missing.
• GitHub update check: a best-effort, non-blocking check notifies you when a newer release is available.

Downloads

• mdl-v26.0-alpha.2-windows-x64.zip / .tar.gz - Windows x64 binary (mdl.exe) with LICENSE and README.

Notes

This is an alpha pre-release intended for testing. Report issues on the tracker.

v26.0 Alpha 1

MCDebugLauncher v26.0 Alpha 1

第一个公开测试版本，包含所有核心功能。

新功能

• 自动 Java 版本检测: 检测 Minecraft 版本的 Java 要求，当 Java 版本不足时显示清晰的错误提示和升级链接
• 支持 Minecraft 26.x+: 完全支持需要 Java 25 的最新 Minecraft 版本

核心功能

• 多加载器支持: Vanilla, Fabric, Forge, NeoForge, Quilt, OptiFine
• 单命令启动: 一条命令完成实例创建和启动
• Agent API: HTTP REST 端点和 WebSocket 事件流
• 智能诊断: 自动崩溃分析和日志收集
• 实例隔离: 独立的配置、mod 和游戏目录

已测试配置

• Minecraft 1.21.1 + Java 21
• Minecraft 1.21.1 + Fabric 0.16.11
• Minecraft 1.21.1 + Forge 52.1.2
• Minecraft 26.2 (Java 版本检测)

文档

• README (English)
• README (中文)
• Research Document
• Specification

下载

• Windows x64: mdl-v26.0-alpha.1-windows-x64.tar.gz

许可证

Apache License 2.0