Introduction to Poly Mod Loader

Poly Mod Loader is a Minecraft: Java Edition mod loader that runs Fabric, NeoForge, Forge, Quilt and Poly mods from one mods folder. Install it once, choose the Poly Mod Loader profile in the official Minecraft Launcher, and drop your mod .jar files into mods/.

• One loader at a time — Supported. Fabric, NeoForge, Forge, Quilt and Poly mods all run on Minecraft 26.1, 26.1.1, 26.1.2, 26.2, 26.3.
• Mixing loaders — Partial. Fabric and Quilt mods run together, and you can also put Fabric or Quilt mods in the same mods/ folder with Forge mods or with NeoForge mods. A Fabric or Quilt mod whose mixins do not fit that loader's patches is left out before the game starts (POLY-COMPAT-224), and the title screen shows how many were left out (Run Fabric and Forge mods together). Forge and NeoForge mods do not run in the same game yet (POLY-COMPAT-221). On Minecraft 26.3, mixing loaders works since 1.2.5 (in 1.2.4 the game stopped at start).
• Clear startup checks. Before the game starts, Poly Mod Loader checks every mod in mods/. Mods that cannot run are left out with a POLY-… code and reason in logs/latest.log, so the rest of your mods still start cleanly.

Poly Mod Loader 1.4.0 runs Minecraft 26.1, 26.1.1, 26.1.2, 26.2, 26.3. The examples in these docs use Minecraft 26.2.

Stable release

Poly Mod Loader 1.4.0 is a stable release. Back up worlds you care about before you add new mods.

Where to start

To play with mods, you only need the installer. No programming is involved.

InstallDownload the installer, add the profile to the Minecraft Launcher, and add modsSupported versions and loadersWhich Minecraft versions and which kinds of mods runFabric and Forge togetherPut both kinds of mods in one game: what works and what does not yetPlayer FAQWhich mods work, servers, world backups, removing it

To make mods, you write a Poly Mod: a mod made with Poly Mod Loader's own API, the Native API.

RequirementsThe JDK and Minecraft files you need to make modsCreate your first Poly ModBuild Crystal Garden, a mod with growing crystals, from an empty project to passing game testsNative APIThe most-used code and rules, by areaError codesWhat the POLY-… codes mean and what to do

What runs today

Mods	Status
Fabric mods	Supported. Fabric mods run the way they do in Fabric Loader on 26.1, 26.1.1, 26.1.2, 26.2, 26.3. Tested on 26.1 and 26.2 with popular Fabric mods: 138 on 26.2, Sodium, Iris, JEI and Fabric API among them, load a saved world together, save it and quit, and 100 start a real dedicated server. Each mod's features were not checked one by one
NeoForge mods	Supported. NeoForge itself runs inside Poly Mod Loader with its own loader, FML (NeoForge 26.1.0.19-beta on 26.1, 26.1.1.15-beta on 26.1.1, 26.1.2.122 on 26.1.2, 26.2.0.93 on 26.2, 26.3.0.98 on 26.3). Its files are downloaded on the first start. Tested on 26.1, 26.1.2 and 26.2 with popular NeoForge mods: 54 on 26.2, Sodium and Iris among them, load a saved world, save it and quit, and on a server they create and save a world and start a real dedicated server. The installed launcher profile and server run them too. A mod is only left out if NeoForge cannot run it either. Each mod's features were not checked one by one
Forge mods	Supported. Forge itself runs inside Poly Mod Loader (Forge 62.0.9 on 26.1, 64.1.5 on 26.1.2, 65.1.5 on 26.2, 66.1.0 on 26.3), and its files are downloaded on the first start. Tested on 26.1 and 26.2 with popular Forge mods: 40 on 26.2 load a saved world, save it and quit, and on a server they create and save a world and start a real dedicated server. A mod is only left out if Forge would refuse it too. Each mod's features were not checked one by one
Quilt mods	Supported on 26.1, 26.1.1, 26.1.2, 26.2, 26.3, also next to Fabric mods. Tested on 26.1, 26.1.2 and 26.2 with every Quilt-only build on Modrinth for each version (114 on 26.2) on the client, the game test server and the dedicated server, and compared with real Quilt Loader: a mod is only left out if it would not load or run under Quilt Loader either. Mods that need the Quilt Standard Libraries (QSL) are left out, because QSL has no release for 26.x. A mod that also ships a Fabric version runs as a Fabric mod. Each mod's features were not checked one by one
Mixing loaders	Partial. Fabric and Quilt mods can be placed in mods/ alongside Forge mods or alongside NeoForge mods. A Fabric or Quilt mod whose mixins do not fit that loader's patches is left out before the game starts (POLY-COMPAT-224, with a count on the title screen); on 26.2, next to Forge no Fabric API module is left out but Architectury, Balm and Lithium are (1.2.5, 2026-10-28: 88 mods of the other loaders load, 78 are left out), and next to NeoForge 10 Fabric API modules are left out (2026-10-27: 40 load with 40 NeoForge mods, 76 are left out); each run creates a world, passes GameTest and saves it on the game test server. Forge and NeoForge mods do not run in the same game yet (POLY-COMPAT-221). On Minecraft 26.3 since 1.2.5 (headless, 2026-10-28); in 1.2.4 the game stopped at start
Poly Mods	Supported, in single player and on dedicated servers

Install and play	Status
Minecraft versions	26.1, 26.1.1, 26.1.2, 26.2, 26.3
Installer	.jar for Windows, macOS, and Linux. It adds a profile to the official Minecraft Launcher, and it can also set up a dedicated server
Client and dedicated server	Both start through Poly Mod Loader. Tested automatically: the client by opening a saved world, the dedicated server up to Minecraft's EULA check

Technical details per loader (Mixin, nested jars, how NeoForge runs) are in Compatibility. What is missing is in Not yet available.

For mod developers

Every public API is at the PREVIEW level, so it can change between versions. Mod developers start from the mod template, and Gradle downloads Poly Mod Loader from the website's Maven repository; see Get the mod template. Mods are built with Java 25.

What a Poly Mod can do

A Poly Mod adds content through the Native API instead of the game's internal classes. The Native API has no Minecraft types; Poly Mod Loader's game layer implements it for each game version.

ContentBlocks (state properties, block entities, menus), items and data components, food, projectiles, status effects, game rules, sounds, particlesMobs and gameplayAI goals, box models and animations, mounts, natural spawning, damage events, advancementsWorldWorld storage, task scheduling, code biomes and terrain generators, data dimensions and structures, forced chunk loadingClientKey bindings, HUD, mod screens, block entity rendering, post-processing shaders, dynamic texturesNetworking and operationsPayload channels, synced data, commands and permissions, reload listeners, data versions, automatic world backupsIn-game testsRun the tests a mod registers on the Mojang game test server, without a window

What the developer side has today

Item	Status
Poly Mods	poly.mod.json validation, dependency resolution, common/client/server entrypoints
Native API	Content, world and entities, commands, networking, client, resources and operations, in-game tests (all PREVIEW)
Class transformation	Up-front planning, descriptor and bytecode precondition checks, conflict rejection, transform cache

Design principles

• Game types stay hidden: A mod sees only poly-game-api. Poly Mod Loader's game layer (poly-game-v26_2) implements it for each game version.
• Failures come with error codes: An invalid declaration fails in its entrypoint with a POLY-… code, listed in the error code table.
• Declared transformations only: Game code is changed only by declared rules. Rules that conflict are refused and written to a report.
• Performance claims come from measurements: see Performance.