🌉 LegacyBridge

A bridge between legacy Minecraft mods and newer adventures.

LegacyBridge is a free, open-source project exploring the conversion of Minecraft Forge 1.16.5 mods to Forge 1.20.1.

Its goal is to bring more older content forward through carefully implemented transformations and compatibility adapters, while explaining clearly when a mod cannot be converted.

Experimental Beta — not a universal converter. The current public workflow supports a narrow simple-content subset. Most complex mods, and many apparently simple mods, are not supported yet. Successful conversion does not guarantee correct gameplay.

✨ What it does today

• Adds a Convert mods button to the client main menu.
• Scans candidate JARs without loading or executing the original mod classes.
• Analyzes metadata, bytecode and resources.
• Converts inputs that fully match the supported profile.
• Shows individual results, errors and compatibility reports.
• Records changes in a TransformationLog.
• Keeps converted files in staging until you approve installation.
• Prepares approved mods for the next game launch.
• Includes English and Brazilian Portuguese interface text.

Only one LegacyBridge.jar is required. It contains the conversion engine, runtime, interface and finite mapping/API data used by the public supported profile.

No separate mapping pack is required for that profile.

📦 Currently supported content

The public simple-content-v1 profile requires a strictly checked Forge DeferredRegister registration pattern.

Within that pattern, it covers:

• Plain items, plain STONE blocks and BlockItems with limited basic properties.
• Vanilla shaped and shapeless crafting recipes.
• Restricted item and block tags.
• Translations and static PNG textures.
• Simple vanilla-template models and blockstates.
• Sound aliases referencing selected vanilla sounds — not custom audio files.
• Limited creative-tab membership.

Accepted mod IDs, registry names and resource locations are preserved. Necessary changes are documented in the transformation report.

Legacy MISC creative membership maps to the target Ingredients tab; exact legacy ordering is not guaranteed.

This profile rebuilds a limited registration graph. It does not preserve arbitrary Java behavior. Unsupported code or resources block conversion instead of producing a partially converted mod.

🚧 What is not supported yet

The public conversion profile does not support:

• General tools, armor or custom item/block subclasses.
• Entities, TileEntities or BlockEntities.
• World generation or dimensions.
• Networking or capabilities.
• Custom GUIs, renderers or shaders.
• Mixins, coremods, access transformers or reflection.
• Arbitrary event handlers or general mod dependencies.
• Loot tables or custom recipe serializers.
• Animated textures or custom audio.

Developer experiments are not additional compatibility available through the player interface.

LegacyBridge does not migrate old worlds, hot-load mods into a running session or connect 1.16.5 clients to 1.20.1 servers.

⚙️ Requirements

• Minecraft 1.20.1
• Forge 47.4.23
• Java 17

Source reference: Minecraft 1.16.5 with Forge 36.2.42.

Other Forge patches are not blanket-certified. Fabric and NeoForge are not supported targets.

🚀 Installation and conversion

1. Create a separate test instance. Keep important worlds backed up.
2. Place LegacyBridge.jar in its mods folder.
3. Place original legacy mods directly in: <gameDir>/legacybridge/input
4. Launch Minecraft and open Convert mods.
5. Refresh the list, inspect candidates and select what to convert.
6. Leave the optional mapping field blank for the included supported profile.
7. Review each result and its reports.
8. Continue converting, or explicitly Apply approved results.
9. Close Minecraft and reopen it through your launcher.

Do not put original 1.16.5 mods in the target instance’s mods folder. Forge may reject them before the conversion menu opens.

Converted mods remain separate JARs and require LegacyBridge at runtime.

Continuing conversion does not change the currently loaded mods. Applying results prepares them for the next launch.

“Apply and close” is not automatic restart: you must reopen the game yourself. Do not force-close Minecraft during installation, and keep the legacybridge/transactions recovery data.

🧪 Validation and limitations

Analysis, conversion, bytecode validation, game startup and correct gameplay are separate milestones.

The current candidate has headless validation, but fresh native client/server and gameplay qualification for its exact artifact remains pending. Earlier fixture results do not certify every later build.

The same public JAR includes the server runtime; the conversion interface is client-only. Current-artifact dedicated-server qualification remains pending.

Fully offline gameplay, arbitrary modpacks and existing-world compatibility are not certified. Use disposable instances while testing.

🤝 Help build the bridge

Contributions are welcome! Useful ways to help include:

• Small, original fixtures demonstrating a specific feature.
• Verified comparisons between the source and target APIs.
• Conversion rules and adapters with positive and negative tests.
• Reproducible client, server and multiplayer behavior checks.
• Better diagnostics, translations and documentation.

When reporting a problem, include the exact mod version, Minecraft/Forge versions and relevant conversion diagnostics. Share public source links or authorized minimal reproductions.

Please do not upload private JARs, authentication tokens or unredacted personal logs.

💚 Free and open source

LegacyBridge is released under GPL-3.0-only with a narrow Minecraft/Forge linking exception.

There is no purchase requirement, revenue share, royalty or mandatory donation. Third-party components retain their own licenses.

Converting another author's mod does not grant permission to redistribute its code or assets, and does not automatically change its license.

🔗 Links

• Source code
• Report an issue
• Contribution guide
• Exact supported profile
• Project status