FAQ

Frequently asked questions about Retromod. If your question isn’t here, check the other docs or open an issue.

Is Retromod safe?

Yes, within the usual caveats for running any third-party mod:

  • The code is open source under the MIT license, so you can read every line before running it.
  • Retromod includes a build check that flags whether the running build is the unmodified official one (informational only).
  • It modifies bytecode and nothing else. Retromod doesn’t talk to the network, doesn’t touch files outside your game directory, and doesn’t collect telemetry.
  • Transformation happens in-process: the transformer runs inside Minecraft’s JVM at mod load time. There’s no separate daemon, no autostart, no system integration.

The one real caveat: Retromod does modify other mods’ bytecode. If one of those mods does something shady, Retromod can’t know; it just rewrites the names. Install mods from sources you trust.

Does Retromod need internet access?

No, and it won’t reach for it on its own. Retromod is offline by default as a safety choice. With factory settings, the mod runtime makes zero outbound network calls: no silent downloads, no telemetry, no update checks, no analytics, no error reporting. It works fine on an air-gapped machine.

Two optional features can use the network if you turn them on:

  • Modrinth native-version lookup checks whether a mod you’re about to transform already has a version that supports your MC natively, so you can grab the official build instead. Off by default; enable by setting check_for_native_versions: true in config/retromod/config.json.
  • The CLI API-archive download (retromod archive download <loader> <mc-version>) fetches an old Fabric / NeoForge / Forge API JAR from Maven so the embedder can pull classes out of it. It’s interactive: it prompts you with the source URL before any HTTP request and won’t proceed without a y. Skip the prompt for scripts with --yes.

That’s the entire surface. Anything else you see in the network panel during a Retromod-using session is coming from Minecraft itself, your mod loader, or one of the mods being transformed, not from Retromod.

Why MIT license?

A few reasons:

  • It’s what modding culture expects. Most Fabric and NeoForge mods are MIT or similarly permissive, and making Retromod fit the ecosystem was the priority.
  • Modpack authors can ship it without asking. No attribution clause to trip up, no viral license to worry about.
  • Forks and derivatives are fine. If somebody wants to build a different mod-compatibility layer on top of Retromod’s shim engine, go for it.

The signature verifier exists precisely because the license is permissive: it lets users tell the original from derivatives without restricting anyone’s right to make derivatives.

Does it work on servers?

Yes. Server-side-only mods work exactly the same way client-side mods do: Retromod transforms their bytecode, patches their metadata, and the server loads them.

One nicety here. If a mod is server-only, clients connecting to the server don’t need Retromod themselves. The server handles the transformation, and clients just see a vanilla-looking server that happens to have some extra behavior. Install Retromod on the server, leave clients alone.

Mods that have both client and server components need Retromod on both sides.

Does it work with server software like Paper / Spigot / Bukkit / Purpur?

Not yet. Retromod targets the mod loaders: Fabric, NeoForge, and Forge. Server software like Paper, Spigot, Bukkit, and Purpur runs plugins rather than mods, and the plugin format and APIs (Bukkit API, NMS) are a different shape from the mod APIs Retromod is built around. Dropping Retromod into a Paper server’s plugins/ folder won’t do anything.

Plugin support is planned, but development on it hasn’t started yet. The mod-loader side is now stable as of 1.0.0, and plugin support is the next major project after that. There’s no committed timeline yet.

If you run a Paper/Spigot/Bukkit/Purpur server and want this, opening a GitHub issue describing your specific use case is the most useful way to weigh in on the priority.

Does it work with modpacks?

Yes, and modpacks are one of the best use cases. Drop Retromod into the pack’s mods/ folder (or configure your pack launcher to include it), put your old mods in retromod-input/, and on first launch everything gets transformed and moved to mods/.

For CurseForge / Modrinth / ATLauncher packs specifically: include Retromod as a regular mod dependency, and add a post-install step (if your launcher supports it) that copies old mods into retromod-input/ instead of mods/. Or skip the auto-install and tell users to use the in-game file picker.

How does Retromod handle a mod’s dependencies? Old version or new?

Use the newest version of the dependency, the one built for the MC version you’re running. Retromod’s job is to bridge the old mod’s calls onto the current library, not to drag an ancient library forward.

  • For library mods (Fabric API, Architectury, Cloth Config, GeckoLib, etc.), install the current native build for your target MC, exactly as you would for any modern setup. The old mod calls the library’s old API, and Retromod’s shims and bridge polyfills remap those calls to the new API. It’s the same mechanism that lets an old mod run against today’s Fabric API.
  • Bundled (JiJ) dependencies are handled automatically. A library shipped inside the mod JAR rides along and gets transformed with it. You generally don’t need to install those separately; if you do, use the newest standalone build.

Don’t go hunting for ancient builds of a library to match an old mod. That just gives you two old things to translate instead of one, and a library built for 1.20.1 has its own pile of removed-API problems on 26.1.

Where this is still occasionally rough is a library that renamed its package and reshaped its API between the old and new versions. The worked example is Cardinal Components, which moved from dev.onyxstudios.cca (5.x) to org.ladysnake.cca (6.x): an old mod references dev.onyxstudios.cca.* while modern CCA provides org.ladysnake.cca.*. Retromod now bridges that package move. The public api/ surface that kept its shape (the large majority) is redirected automatically, so install modern CCA and let Retromod line up the names; downgrading to old CCA is not the answer. The exception is the handful of classes CCA 6 removed rather than moved, chiefly the item-component API, which CCA dropped because Minecraft 1.20.5+ replaced it with vanilla data components. A mod built around old CCA item components needs that newer API and can’t be bridged by a rename alone.

So the rule of thumb is: install the newest version of every dependency, just like a normal modern install, and let Retromod carry the old mod across to it.

Can I commercialize a modpack using Retromod?

Yes. MIT license, no strings attached. You can:

  • Bundle Retromod in a paid modpack.
  • Include it in a donation-required server pack.
  • Redistribute it under whatever branding your pack uses.
  • Modify it for your needs.

You have to preserve the copyright notice and MIT license text somewhere in the distribution. That’s the only requirement, and a LICENSE file alongside the JAR (or a mention in the pack’s credits) is enough.

What Minecraft versions are supported?

  • Target: Minecraft 1.20 through 26.2, with a host jar for every version in between (Fabric and Forge hosts start at 1.20, NeoForge at 1.20.1; NeoForge skipped the 26.1 and 26.1.1 patches, so its 26.x jars are 26.1.2 and 26.2). As of the 1.2.0 snapshots all three loaders ship 26.2 jars: Fabric, NeoForge, and Forge (Forge 65.x has released for 26.2, and the Forge 26.2 jar is verified in-game). This is the version your transformed mods run on. On 26.2, use the OpenGL renderer (see below).
  • Source: mods built for 1.12.2 and newer. That’s the version the mod was originally released for. (1.12.2 specifically is transform-level so far: the mod gets translated and scanned, but full in-game loading is still ahead, targeted for 1.2.0 final.)

So you can take a Fabric mod built for 1.20.1 and run it on 26.1.2, or a mod built for 1.16.5 and run it on 26.1.2. 1.12.2 is the oldest source we currently support.

Older source versions (pre-1.12.2) aren’t supported because the mod ecosystem shifts fundamentally around that point: Forge API differences, mixin maturity, and so on. That’s future work.

Newer target versions will be added as Minecraft releases them. Retromod is built around 26.1 specifically because it’s the first fully unobfuscated MC release, which makes the mapping work straightforward.

On MC 26.2, should I use OpenGL or Vulkan?

Use OpenGL. MC 26.2 added a Vulkan renderer and made it the default, but translated old mods often render incorrectly (or crash) on Vulkan because they do OpenGL-era rendering. 26.2 still ships the OpenGL backend, and that’s what old mods need. Retromod sets preferredGraphicsBackend:"opengl" automatically the first time it runs on a 26.2+ client (it won’t override a backend you chose yourself), so most people are already on OpenGL. To set or confirm it manually: Options → Video Settings → Graphics API → OpenGL. On macOS it’s moot (Minecraft runs OpenGL-over-Metal regardless). OpenGL is expected to be removed in 26.3 (see Troubleshooting and the roadmap).

What does it mean if the build isn’t VERIFIED?

Retromod compares the running build’s code against a hash embedded at release time. VERIFIED means it matches: the bytecode is unchanged from what was published (it doesn’t prove the build is genuine, since the hash has no secret key; it means the hash checks out). MODIFIED means it doesn’t match: a fork, a repack, a launcher that re-bundled it, or (rarely) a corrupted download. UNKNOWN is a dev/source build with no hash embedded. It’s informational only and never blocks anything. For a real check, compare your file’s SHA-256 against the one on the releases page.

See Authenticity for the full breakdown of what each status means.

Does Retromod work with OptiFine / Sodium / Iris?

Partial compatibility. Sodium and Iris are mostly fine since they target modern MC APIs, which Retromod doesn’t interfere with. OptiFine is trickier because it transforms the game in ways that overlap with what Retromod does; there’s a dedicated compat/OptiFineCompat.java that handles some of the friction, but YMMV. Test with your specific rendering mod combo before committing to it.

Is there a list of mods that work?

Yes, three of them:

  • The Compatibility DB: community reports with badges (Diamond → Borked), the exact versions used, and details, ProtonDB-style. Add your own with the report form linked there.
  • The compatibility list covers mods confirmed to load after transformation, grouped by the MC version they were built for, plus a recommended multi-mod test setup.
  • Mods That Can’t Be Translated is the “no” list and the rules behind it (rendering replacements, coremods, deep-integration mods like Create).

Neither is exhaustive; the modding ecosystem is enormous and largely community-tested. If you confirm a mod works (or doesn’t), an issue noting the mod, its version, your MC version, and the result genuinely helps. That collective testing is how the lists grow.

Will it work for [specific mod]?

Try it and see. Simple content-only mods (items, blocks, recipes) almost always work. Mods that hook MC’s internals for rendering, physics, or networking are hit-or-miss. Mods with extensive reflection or dynamic classloading may need remap_reflection enabled (it’s on by default).

The best way to find out is to drop the mod in retromod-input/, launch, and check config/retromod/verify-reports/ for that mod. If verification passes, odds are good. If it doesn’t, the report tells you what’s missing.

Is there a Discord / Matrix / forum?

Not yet. Right now all discussion happens on the GitHub issue tracker. For bugs and feature requests, open an issue. For general questions, open a discussion.

Can I contribute?

Please do. See Contributing for the workflow and the set of skills (under .claude/skills/) that walk you through common tasks like adding a shim or a polyfill.