Skip to main content
Version: v1.4.0

Poly Mod Loader — Project Overview & Roadmap

Poly Mod Loader is an advanced, in-engine modding platform and bytecode virtualization layer for Minecraft: Java Edition (supporting versions 26.1, 26.1.1, 26.1.2, 26.2, and 26.3 under Java 25).

1. What is Poly Mod Loader?​

Unlike external launcher wrappers (such as Prism, CurseForge App, or Modrinth App) that merely manage profile directories and launch separate games, Poly is an in-game bytecode loader:

  • It replaces vanilla Minecraft's startup sequence and hosts a unified classloader.
  • It runs Fabric, Quilt, Forge and NeoForge mods and adapts their bytecode where needed, so Fabric and Quilt mods can run in the same game as Forge mods or as NeoForge mods. Forge and NeoForge mods do not run in the same game yet. On Minecraft 26.3, mixing loaders works since 1.2.5 (see the table below).
  • It provides its own clean Native API with declarative bytecode transforms, headless gametesting, and version-agnostic abstractions.

2. Core Pillars & Technical Differentiators​

+-----------------------------------------------------------------------------------+
|                                  Poly Mod Loader                                  |
+-----------------------------------------------------------------------------------+
|  [ Native API ]   [ Fabric Bridge ]   [ Forge Bridge ]   [ NeoForge Bridge ]      |
|  - System API     - FabricLoader API  - FML Virtualizer  - FML 11 Layer Bridge    |
|  - Lifecycle API  - QuiltLoader API   - ModLauncher Shim - Shared Mixin Engine    |
+-----------------------------------------------------------------------------------+
|                       Poly Transform Engine (ASM 9.11)                            |
|  - Declarative Bytecode Transforms  - Dynamic Host Patch Adjustments (ADR-0030)  |
|  - Unified Mixin 0.8.7 Service      - Granular Conflict Pre-flight Assessment     |
+-----------------------------------------------------------------------------------+
|                     Poly Transforming ClassLoader & JRE 25                        |
+-----------------------------------------------------------------------------------+
|                         Minecraft: Java Edition (26.x)                            |
+-----------------------------------------------------------------------------------+

1) True In-JVM Multi-Loader Concurrency​

Poly does not run separate games or heavy emulation layers. A single game classloader hosts Poly Mods together with Fabric and Quilt mods, and with Forge mods or NeoForge mods (not both in one game). Forge and NeoForge's FML services run inside Poly's managed layers, while Fabric and Quilt mods are driven through unified Mixin and ClassTweaker pipelines.

2) Pre-flight Conflict & Patch Assessment (POLY-COMPAT-224)​

When Forge or NeoForge patches a vanilla Minecraft class, traditional Fabric Mixins fail because injection targets or local variable tables differ. Poly incorporates an automated Host Patch Check (HostPatchCheck):

  • It inspects all mod mixins against the host's actual bytecode before launch.
  • If a mixin can be safely adapted (via parameter shifting, expression wrapping, or method retargeting), Poly rewrites the injection point on the fly (HostPatchAdjustments).
  • If an incompatible mixin is found, Poly isolates the conflicting mod before the JVM starts, outputting clear diagnostic codes (POLY-COMPAT-224) instead of crashing the game mid-launch.

3) Measured Performance Overhead​

  • Startup Time, Tick Time & Memory: In the measured scenarios the difference from vanilla is within measurement noise (Performance). No improvement is claimed without a measurement.
  • Graphics mods: On 26.2, popular Fabric mods including Sodium, Iris and Lithium play a world together on the client.
  • Custom Loading Screen: Fast, modern #0E131F dark overlay (PolyLoadingOverlay) with real-time mod count overlays per loader.

3. Current Project Status (Release 1.4.0)​

ComponentTarget / ScopeStatusNotes
Supported Minecraft26.1, 26.1.1, 26.1.2, 26.2, 26.3StableJava 25 required across all platforms.
Fabric Mod SupportFabric Loader 0.19.5 API / Mixin 0.8.7VerifiedOn 26.2, 138 popular Fabric mods (Sodium, Iris, Lithium and more) play a world together on the client, and 100 start a real dedicated server. 26.3 (2026-10-27, headless): 98 loaded / 73 left out on the game test server, 100 / 74 on the dedicated server.
Quilt Mod SupportQuilt Loader 0.31.x / quilt.mod.jsonVerifiedEvery Quilt-only Modrinth build on 26.1, 26.1.2 and 26.2 (114 on 26.2). 26.3 (2026-10-27, headless): dedicated server 112 loaded / 34 left out, 73 of the 91 Quilt-only builds load, and the real Quilt Loader agrees on 89 of 91.
Forge Mod SupportMinecraftForge 62.0.9 ~ 66.1.0VerifiedClient, dedicated server and game test server on 26.1, 26.1.2 and 26.2. 26.3 (2026-10-27, headless): 30 of 38 on the game test server, 33 of 41 on the dedicated server.
NeoForge Mod SupportNeoForge 26.1.0 ~ 26.3.0VerifiedRuns via NeoForge's own FML. 26.3 (2026-10-27, headless): FML loads 50 mods on the game test server and 49 on the dedicated server. Not in the same game as Forge mods (POLY-COMPAT-221).
Fabric mods next to Forge26.2 corpus (corpusFabricForge)PartialMeasured on 1.4.0: 85 foreign mods load, 81 left out. Left out with POLY-COMPAT-224: Fabric API's fabric-content-registries-v0 (drowning and fluid jumping cannot be bridged to Forge's calls) and three Fabric mods (Architectury, Balm, Lithium). fabric-biome-api-v1 is now left out with POLY-COMPAT-112 (the link check reads Forge's patched game and finds it writes ChunkGenerator.featuresPerStep as a Supplier where Forge has a ClearableLazy), instead of failing later.
Fabric mods next to NeoForge26.2 corpus (corpusFabricNeoForge)PartialMeasured on 1.4.0: 47 foreign mods load, 69 left out (1.3.0: 40 / 76). Only 3 Fabric API modules are left out with POLY-COMPAT-224: content-registries, data-generation, registry-sync. Since 1.4.0 Poly Mod Loader ships its own builds of fabric-block-api-v1 and fabric-item-api-v1 on NeoForge 26.2.0.93's hooks ("host modules", adapted from Sinytra Forgified Fabric API under Apache-2.0) and uses them in place of the originals; events-interaction, transfer, entity-events, resource-conditions and crash-report-info now load through bridges. With NeoForge 26.3: 43 / 73, 7 modules still left out (no host modules for 26.3 yet). Forgified Fabric API installed next to NeoForge no longer stops the game at start (its nested Fabric Loader plugin is excluded).
Mixing loaders on 26.3Fabric/Quilt with Forge or NeoForgePartial (1.2.5)Measured 2026-10-28, headless: every mixed-loader run of the 26.3 set passes. Fabric next to Forge 80 loaded / 86 left out, Quilt next to Forge 95 / 86, Fabric next to NeoForge 40 / 76, Quilt next to NeoForge 83 / 96. In 1.2.4 these games stopped at start. Windowed runs not done yet.
NeoForge Injection PointsScreen, Container Menu, Data AttachmentVerifiedVerified against NeoForge 26.2.0.93 patched client and vanilla 26.2.
Universal InstallerCross-platform .jarDone (1.2.4)Unified installer running across Windows, macOS, and Linux on Java 17+.
Custom Loading UIPolyLoadingOverlayDone (1.4.0)Since 1.4.0 every loader shares one early loading window on the client that looks like the game's loading screen (Mojang background, logo, progress bar, Poly cube, mods per loader); Forge and NeoForge no longer open FML's early window; not on macOS yet; -Dpoly.earlyWindow=off turns it off.
Bug Reporting FlowGitHub Issues Direct RouteDoneExceptions & crash UI direct users to official issue tracker.

4. Immediate Roadmap & Future Milestones​

Milestone A: Client-Side & NeoForge Fabric API Adaptation (In Progress)​

  • Done (2026-10-27): NeoForge injection points checked against NeoForge's patched client and the vanilla client (NeoForgeInjectionPointsTest). Fabric mods next to Forge and NeoForge measured on 26.2 with 1.2.4: next to Forge no Fabric API module is left out but four Fabric mods are; next to NeoForge 10 Fabric API modules are left out.
  • Done (1.2.5, 2026-10-28): next to Forge, Puzzles Lib's Fabric build loads again on 26.2 (88 loaded / 78 left out). Mixing loaders works on 26.3 (headless).
  • Done (1.4.0, 2026-10-30): next to NeoForge on 26.2, shipped host modules for fabric-block-api-v1 and fabric-item-api-v1, bridged 5 modules (only 3 left out with POLY-COMPAT-224), 47 foreign mods load / 69 left out (26.3: 43 / 73), and Forgified Fabric API no longer stops the game. Next to Forge on 26.2, 85 foreign mods load / 81 left out (fabric-content-registries-v0 left out with POLY-COMPAT-224, fabric-biome-api-v1 with POLY-COMPAT-112).
  • Next host modules for NeoForge: fabric-registry-sync-v0, fabric-content-registries-v0, fabric-data-generation-api-v1, then NeoForge 26.3.0.98.
  • fabric-screen-api-v1: Retarget GuiMixin:onExtractGui for NeoForge client UI mods (ModMenu, etc.).
  • fabric-menu-api-v1 & fabric-data-attachment-api-v1: Integrate NeoForge openMenu and AttachmentType extensions.
  • Rendering & Model Modules: Adapt fabric-renderer-api-v1, fabric-rendering-v1, and fabric-model-loading-api-v1 for client-side shaders and resource packs.

Milestone B: Minecraft 26.3 Real-World Corpus Verification​

  • Headless, single loader (2026-10-27): the 26.3 corpus (mod-corpus-26.3.json: 43 Fabric, 42 Forge, 44 NeoForge) and the Quilt corpus (91 Quilt-only builds) pass the headless server and game test runs, one loader at a time. (The Quilt game test server run passes once five PurpurPacks data-pack mods that carry 26.2-format data are removed; that failure is on the mods' side.)
  • Mixing loaders on 26.3: works since 1.2.5 in the headless runs (in 1.2.4 every such game stopped at start). Next to Forge, Architectury, Balm, Lithium, Puzzles Lib and three Fabric API modules are still left out there. Windowed (client) runs on 26.3 have not been done yet.
  • Hardening against 26.3-specific game changes (SDL keyboard handling, shader #include, data pack overlay formats).

Milestone C: Technical Benchmarking​

  • Publish detailed memory, tick-rate, and startup benchmarks comparing Poly against standalone loaders.

Forward Plan: Forge on NeoForge​

  • Running MinecraftForge mods on top of a NeoForge host environment (F-N0 ~ F-N8 pipeline).
Buy me a coffee