Frequently Asked Questions

Compatibility and versions

Can I use Forge, Fabric, NeoForge, or Quilt mods?

Fabric and Forge mods, mostly yes. Quilt mods are experimental, on 26.2 only. NeoForge mods are not loaded by default.

Mod	Status
Forge mods	Verified Poly Mod Loader runs Forge and FML themselves. On 26.1 and 26.2, popular Forge mods play a saved world on the client, save it and quit (40 on 26.2), and start a real dedicated server. The only mods left out are ones Forge refuses too. Features were not checked mod by mod
Fabric mods, including mods that use Mixin, MixinExtras, nested jars, or class tweakers	Verified On 26.1 and 26.2, popular Fabric mods play a saved world on the client, save it and quit (138 real mods on 26.2, plus 2 test mods), and start a real dedicated server together (100 on 26.2). Features were not checked mod by mod
Fabric mods that use Fabric Loader's internal classes (net.fabricmc.loader.impl)	Partial the parts real mods use are provided (FabricLauncherBase.getLauncher(), FabricLoaderImpl.getGameProvider()); a mod that needs the rest is left out with a diagnosis (POLY-COMPAT-111)
NeoForge mods	Blocked left out by default, with diagnostics (POLY-COMPAT-200..205). An experiment, off by default (-Dpoly.neoforge=on), runs NeoForge itself; checked only on a 26.2 server so far
Quilt mods	Experimental on 26.2 only: quilt.mod.json and the Quilt Loader API are provided. Quilt Standard Libraries (QSL) has no release for 26.x, so a mod that needs it is left out (POLY-COMPAT-114 with 308). A Quilt mod that also ships fabric.mod.json runs as a Fabric mod (310)

A blocked mod is not loaded. The reason goes to the log and to .poly/startup-report.json, and the other mods still load. See Compatibility. To use Fabric and Forge mods in one game, see Run Fabric and Forge mods together.

Do I have to rebuild my mod for every Minecraft version?

Not if it uses only the Native API. If you write "26.*" or ">=26.2 <27" in the minecraft field of poly.mod.json, the mod runs on a new version without a rebuild once Poly Mod Loader supports that version. The game layer for that version must implement every API the mod uses.

A mod that depends on game code of a specific version, such as one with transform rules (transforms), must name the exact version. That mod loads only on the versions it lists. If the version does not match, launch stops with POLY-DEPENDENCY-007.

What do I put in "minecraft" in poly.mod.json?

The mod template uses "26.*". If the mod uses only the Native API, write a wildcard or a range. If it depends on game code of a specific version, write the exact version, such as "26.2". A wrong format gives POLY-METADATA-009. poly.mod.json describes each format.

How do I run my mod on a different Minecraft version?

Set polyMinecraft=<version> in the mod project's gradle.properties, or add -PpolyMinecraft=<version> to the command. Only versions your Poly Mod Loader supports work: 26.1, 26.1.1, 26.1.2, 26.2 for Poly Mod Loader 0.2.0-beta.2. See Running tests.

Why are there no mappings?

They are not needed. Since Minecraft 26.1, Mojang ships Java Edition unobfuscated, with its original names. Poly Mod Loader's transform rules name the target classes and methods directly, using Mojang's original names and JVM descriptors. On 26.x, Fabric and NeoForge mods use the same names.

A mod that uses only the Native API uses no Minecraft names. The Native API has no Minecraft types, and Poly Mod Loader's game layer provides the implementation for each game version.

Installation and distribution

Is there an installer or a public Maven repository?

Yes.

• Players install Poly Mod Loader with the installer from the download page. It adds a Poly Mod Loader profile to the Minecraft Launcher. See Install.
• Mod developers do not need the Poly Mod Loader source. The website's Maven repository https://www.polymc.net/maven/ has the mod template, the dev.polymodloader.mod plugin, and Poly Mod Loader itself, without source code. See Get the mod template.

What is still missing is listed in Not yet available.

Where do I put the mod jar I built?

Put the jar from build/libs/ in run/client/mods/ of the Poly Mod Loader run environment (run/server/mods/ for the server). If a mod uses the same content on the server and the client, both sides need the same version of the jar. See Build, Run, Deploy.

Does Poly Mod Loader accept the Minecraft EULA?

No. Poly Mod Loader does not accept it on your behalf.

• If run/server/eula.txt does not contain eula=true, runServer fails before it starts the game and shows a guidance message. Read the EULA yourself, and if you agree, create that file yourself.
• serverBootSmokeTest starts the server in an empty directory every time, so the server stops at the EULA check. The task verifies only the log up to that point.
• worldCreateSaveTest and gameTests use the Mojang game test server, so they do not need an EULA file.

See Running tests.

I get an authentication error on online servers or Realms.

This is expected. Development runs use an offline account (PolyDev). Single player works, but online servers and Realms give an authentication error. See Requirements.

API and errors

Does the API change between versions?

It can. Every public API in Poly Mod Loader 0.2.0-beta.2 has the PREVIEW level, and the 0.1 line has no STABLE API with a compatibility promise. Changes are listed in the Changelog, and the levels are explained in API stability.

Where do error codes come from?

Poly Mod Loader reports problems as POLY-area-number codes.

• Problems in poly.mod.json (POLY-METADATA-*) are reported first by the validatePolyModJson task in build. The same checker validates the file again at launch.
• Problems at run time appear in the console and in run/<side>/logs/latest.log. If startup stops, the code follows Poly Mod Loader launch stopped in phase ….
• The reason a mod was not loaded is also written to .poly/startup-report.json.

The meaning of each code and what to do are in Error codes. Fixes by symptom are in Troubleshooting. The meaning of an existing code never changes. A new problem gets a new number.