Skip to main content
The Fabric platform is used wherever fabric-loader is used, regardless of Minecraft version. Essential Loader leverages Fabric’s built-in features while adding dynamic mod loading capabilities.

​
Features

  • Cross-Version Support: Works across the entire range of Fabric-supported Minecraft versions
  • Built-in JiJ: Leverages Fabric’s native Jar-in-Jar support
  • First-Party Mixin: Uses Fabric’s built-in Mixin support
  • Automatic Version Selection: Picks the latest version when multiple mods bundle the same dependency
  • Fake Mod Support: Dynamically loaded mods appear as normal mods in ModMenu

​
Setup

1

Add Essential Repository

Add the Essential Maven repository to your build script:
build.gradle.kts
repositories {
    maven("https://repo.essential.gg/repository/maven-public/")
}
2

Add Essential Loader as JiJ Mod

Include Essential Loader as a Jar-in-Jar dependency in your fabric.mod.json:
fabric.mod.json
{
  "schemaVersion": 1,
  "id": "yourmod",
  "version": "1.0.0",
  "name": "Your Mod",
  "description": "Your mod description",
  "environment": "client",
  "entrypoints": {
    "client": ["com.yourmod.YourMod::init"]
  },
  "mixins": ["yourmod.mixins.json"],
  "jars": [
    {
      "file": "META-INF/jars/loader-fabric-1.0.0.jar"
    }
  ]
}
3

Configure Build Script

Include the Essential Loader jar in your mod:
build.gradle.kts
val includeLoader by configurations.creating
configurations.implementation.get().extendsFrom(includeLoader)

dependencies {
    includeLoader("gg.essential:loader-fabric:1.3.2")
}

tasks.jar {
    dependsOn(includeLoader)
    from(includeLoader.files) {
        into("META-INF/jars")
    }
}

​
Platform Details

​
Background

Fabric-loader works across the entire range of supported Minecraft versions. Unlike LaunchWrapper, fabric-loader was designed from the ground up as a mod loader with excellent support for:
  • Version selection (automatically picks latest)
  • Jar-in-Jar mod bundling
  • First-party Mixin support
  • Comprehensive mod metadata
The only feature Fabric is missing for Essential Loader’s use case is the ability to chain-load mods or have custom code do mod discovery. Fabric always discovers all mods before running any third-party code.

​
Entrypoint

Essential Loader uses Fabric’s built-in preLaunch entrypoint:
fabric.mod.json
{
  "schemaVersion": 1,
  "id": "essential-loader",
  "version": "1.0.0",
  "environment": "client",
  "entrypoints": {
    "preLaunch": [
      "gg.essential.loader.stage0.EssentialSetupPreLaunch"
    ]
  }
}
This entrypoint runs early enough to perform dynamic mod loading before the main game initialization.

​
Fake Mods

Essential Loader creates “fake mods” for dynamically loaded mods to make them appear as normal mods in the Fabric ecosystem.

​
How It Works

1

Instantiate Mod Metadata

Essential Loader uses fabric-loader internals to instantiate mod metadata for dynamically loaded mods. This allows them to appear as normal mods in ModMenu and other mod lists.
2

Register with Fabric

The fake mod is registered with Fabric’s mod system, making it visible to:
  • ModMenu
  • Mod dependency systems
  • Other mods querying for loaded mods
3

Handle Entrypoints (Best Effort)

Declared entrypoints in the dynamically loaded mod are registered if the fake mod creation succeeds.
If fake mod creation fails, the dynamically loaded mod will generally still function correctly, but won’t show up in ModMenu and its entrypoints won’t be registered.

​
Fallback Strategy

Because fake mod creation makes heavy use of fabric-loader internals (which may break with updates), it’s kept optional. If it fails, the mod should not rely on Fabric entrypoints and should use alternative initialization methods (e.g., Essential uses a custom mixin for its init entrypoint).

​
Jar-in-Jar Handling

By the time Essential Loader runs, fabric-loader has already loaded all mods. Essential Loader must handle JiJ mods inside dynamically loaded mods itself.

​
Version Handling

If the JiJ mod has not been loaded:
→ Load it normally ✓

​
Essential Dependencies Generation

When an older version of a JiJ mod is already loaded, Essential Loader cannot easily replace it. Instead, it dynamically generates a new “Essential Dependencies” mod in the mods folder and prompts the user to restart.
1

Detect Version Conflict

Essential Loader detects that an older version of a JiJ dependency is already loaded.
2

Generate Dependencies Mod

A new jar file is created in the .minecraft/mods folder containing the newer version.
3

Prompt User Restart

The user is prompted to restart the game.
4

Load Updated Version

On next boot, fabric-loader discovers the generated jar and loads the updated version instead of the old one.
This solution doesn’t rely on fabric-loader internals at all, making it very stable. However, it does mean the user may need to manually restart on each update of the JiJ mod.

​
Platform-Specific Considerations

​
Class Loading

Dynamically loaded mods are added to Fabric’s class loader during the preLaunch phase. This ensures they’re available before main game initialization.

​
Stability

Because Essential Loader uses fabric-loader internals for fake mod creation, this functionality is particularly likely to break with fabric-loader updates. Always test with new fabric-loader versions.

​
Best Practices

  1. Don’t Rely on Fabric Entrypoints: Dynamically loaded mods should use alternative initialization methods (e.g., mixins) rather than relying on Fabric’s entrypoint system.
  2. Test Version Conflicts: Test your mod with various versions of dependencies to ensure the JiJ handling works correctly.
  3. Graceful Degradation: Design your mod to work even if fake mod creation fails.

​
Complete Example

Here’s a complete example of integrating Essential Loader with a Fabric mod:

​
fabric.mod.json

{
  "schemaVersion": 1,
  "id": "yourmod",
  "version": "1.0.0",
  "name": "Your Mod",
  "description": "An example mod using Essential Loader",
  "environment": "client",
  "entrypoints": {
    "client": ["com.yourmod.YourMod::init"]
  },
  "mixins": ["yourmod.mixins.json"],
  "depends": {
    "fabricloader": ">=0.14.0",
    "minecraft": ">=1.16"
  },
  "jars": [
    {
      "file": "META-INF/jars/loader-fabric-1.3.2.jar"
    }
  ]
}

​
build.gradle.kts

repositories {
    maven("https://repo.essential.gg/repository/maven-public/")
    maven("https://maven.fabricmc.net/")
}

val includeLoader by configurations.creating
configurations.implementation.get().extendsFrom(includeLoader)

dependencies {
    // Fabric
    minecraft("com.mojang:minecraft:1.20.1")
    mappings("net.fabricmc:yarn:1.20.1+build.10:v2")
    modImplementation("net.fabricmc:fabric-loader:0.15.0")
    
    // Essential Loader
    includeLoader("gg.essential:loader-fabric:1.3.2")
}

tasks.jar {
    dependsOn(includeLoader)
    from(includeLoader.files) {
        into("META-INF/jars")
    }
}

​
Troubleshooting

​
Mod Not Showing in ModMenu

If your dynamically loaded mod doesn’t appear in ModMenu, fake mod creation may have failed. Check the logs for errors related to fabric-loader internals.
Workaround: Use custom initialization methods (e.g., mixins) instead of relying on Fabric entrypoints.

​
Version Conflicts Requiring Restart

This is expected behavior when an older version of a JiJ dependency is already loaded. The user will be prompted to restart, and the newer version will load on next boot.

​
Fabric Loader Updates Breaking Fake Mods

Fake mod creation uses fabric-loader internals and may break with updates. This is a known limitation. Essential Loader attempts to gracefully degrade when this happens.

Build docs developers (and LLMs) love

Get started for freeTalk to us