Introduction to Poly Mod Loader

Poly Mod Loader is a Minecraft: Java Edition mod loader built to run Fabric, Forge, NeoForge and Quilt mods together. All four run today. You can put Fabric, Forge and Quilt mods in one mods folder and play; NeoForge mods do not run in the same game as Fabric, Quilt or Forge mods yet.

Before the game starts, it checks your mods. Mods that cannot run are left out, and the log says which one and why, so the rest still start.

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

Stable release

Poly Mod Loader 1.0.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. 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
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), also next to Fabric mods. 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.2 and 26.2, also next to Fabric and Forge mods. Tested 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
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). 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. Not yet in the same game as Fabric or Quilt mods: then the NeoForge mods are left out with the reason (POLY-COMPAT-216). With Forge mods, Forge runs and the NeoForge mods are left out. Each mod's features were not checked one by one
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
Installer	.exe for Windows, .jar for 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.