Skip to main content

​
Overview

This quickstart guide will walk you through integrating Essential Loader with your mod on LaunchWrapper (Forge 1.8.9 - 1.12.2). The process involves adding the loader as a dependency, configuring your build script, and creating a metadata file.
This guide focuses on LaunchWrapper integration. For Fabric or ModLauncher, see the Integration Guides.

​
Prerequisites

Before you begin, ensure you have:
  • A Minecraft mod project for Forge 1.8.9 - 1.12.2
  • Gradle or Gradle Kotlin DSL as your build system
  • Basic understanding of Minecraft mod development

​
Integration Steps

1

Add the Essential repository

First, add the Essential Maven repository to your build script where Essential Loader is hosted.
build.gradle.kts
repositories {
    maven("https://repo.essential.gg/repository/maven-public/")
}
If you’re using Groovy Gradle instead of Kotlin DSL, use maven { url 'https://repo.essential.gg/repository/maven-public/' } instead.
2

Configure the embed configuration

Create a custom Gradle configuration for embedding Essential Loader into your mod jar.
build.gradle.kts
val embed by configurations.creating
configurations.implementation.get().extendsFrom(embed)

dependencies {
    embed("gg.essential:loader-launchwrapper:1.3.2")
}
This configuration ensures that Essential Loader is available at compile time and will be embedded into your mod jar at build time.
3

Embed the loader and set the Tweaker

Modify your jar task to embed Essential Loader and set it as the TweakClass in your manifest.
build.gradle.kts
tasks.jar {
    // Embed the contents of the Essential Loader jar into your mod jar
    dependsOn(embed)
    from(embed.files.map { zipTree(it) })
    
    // Set Essential Loader as the Tweaker for your mod
    manifest.attributes(mapOf(
        "TweakClass" to "gg.essential.loader.stage0.EssentialSetupTweaker"
    ))
}
If you already have a custom Tweaker, you can have it extend EssentialSetupTweaker instead. If you previously used the Mixin Tweaker, you can replace it with Essential Loader—it will automatically initialize Mixin for any mod with a MixinConfigs attribute.
4

Create the essential.mod.json file

Create a file named essential.mod.json in your src/main/resources folder. This file defines metadata about your mod and specifies which libraries it includes.
{
    "id": "your_mod_id_goes_here",
    "version": "1.0.0",
    "jars": [
        {
            "id": "com.example:examplelib",
            "version": "0.1.0",
            "file": "META-INF/jars/examplelib-0.1.0.jar"
        }
    ]
}
  • id: Your unique mod identifier
  • version: Your mod version (can be templated from Gradle)
  • jars: Array of Jar-in-Jar dependencies your mod includes
5

(Optional) Automate Jar-in-Jar dependencies

For mods with multiple dependencies, automate the generation of the jars section and the inclusion of libraries.
build.gradle.kts
val jij by configurations.creating
configurations.implementation.get().extendsFrom(jij)

dependencies {
    // Add all dependencies you wish to jar-in-jar to the custom `jij` configuration
    jij("com.example:examplelib:0.1.0")
}

tasks.processResources {
    val expansions = mapOf(
        "version" to version,
        "jars" to provider {
            jij.resolvedConfiguration.resolvedArtifacts.joinToString(",\n") { artifact ->
                val id = artifact.moduleVersion.id
                """
                    {
                        "id": "${id.group}:${id.name}",
                        "version": "${id.version}",
                        "file": "META-INF/jars/${artifact.file.name}"
                    }
                """.trimIndent()
            }
        },
    )
    inputs.property("expansions", expansions)
    filesMatching("essential.mod.json") {
        expand(expansions)
    }
}

tasks.jar {
    dependsOn(jij)
    from(jij.files) {
        into("META-INF/jars")
    }
}
Then use the template version of essential.mod.json shown in Step 4.
This automation ensures that your essential.mod.json always stays in sync with your actual dependencies, reducing maintenance burden.
6

Build and test

Build your mod and test it in your development environment.
./gradlew build
Launch Minecraft with your mod installed. Essential Loader will:
  1. Bootstrap from Stage 0 (embedded in your jar)
  2. Load Stage 1 (also embedded)
  3. Extract and load Stage 2
  4. Initialize your mod with proper dependency management
Check the Minecraft logs to verify Essential Loader loaded successfully:
[EssentialLoader] Loading stage1...
[EssentialLoader] Loading stage2...

​
Adding Mixin 0.8.x Support

One of Essential Loader’s key features is bringing Mixin 0.8.x support to legacy Forge versions. Here’s how to add it:
1

Add Mixin as a Jar-in-Jar dependency

build.gradle.kts
dependencies {
    jij("gg.essential:mixin:0.2.0+mixin.0.8.7")
}
Essential Loader will automatically initialize Mixin for any mod with a MixinConfigs manifest attribute. You don’t need to manually call any initialization code.
2

(Optional) Add MixinExtras

MixinExtras can be added the same way:
build.gradle.kts
dependencies {
    // Essential Loader will automatically initialize it; no need to call MixinExtrasBootstrap
    // annotationProcessor is necessary to generate refmaps
    jij(annotationProcessor("io.github.llamalad7:mixinextras-common:0.4.1")!!)
    
    // Or if you've previously used Essential's relocated MixinExtras:
    // jij(annotationProcessor("gg.essential.lib:mixinextras:0.4.0")!!)
}
3

Configure Mixin annotation processor

Ensure your build system is configured for Mixin’s annotation processor and refmap generation. This is done the same way as with stock Mixin 0.8.x or 0.7.10—Essential Loader only affects runtime behavior.Refer to the SpongePowered Mixin documentation for annotation processor setup.

​
Example Configuration

Here’s a complete example of a build.gradle.kts file with Essential Loader integration: 
repositories {
    maven("https://repo.essential.gg/repository/maven-public/")
}

val embed by configurations.creating
val jij by configurations.creating
configurations.implementation.get().extendsFrom(embed, jij)

dependencies {
    // Embed Essential Loader
    embed("gg.essential:loader-launchwrapper:1.3.2")
    
    // Jar-in-Jar dependencies
    jij("gg.essential:mixin:0.2.0+mixin.0.8.7")
    jij(annotationProcessor("io.github.llamalad7:mixinextras-common:0.4.1")!!)
    jij("com.example:examplelib:0.1.0")
}

tasks.processResources {
    val expansions = mapOf(
        "version" to version,
        "jars" to provider {
            jij.resolvedConfiguration.resolvedArtifacts.joinToString(",\n") { artifact ->
                val id = artifact.moduleVersion.id
                """
                    {
                        "id": "${id.group}:${id.name}",
                        "version": "${id.version}",
                        "file": "META-INF/jars/${artifact.file.name}"
                    }
                """.trimIndent()
            }
        },
    )
    inputs.property("expansions", expansions)
    filesMatching("essential.mod.json") {
        expand(expansions)
    }
}

tasks.jar {
    // Embed Essential Loader
    dependsOn(embed)
    from(embed.files.map { zipTree(it) })
    
    // Include Jar-in-Jar dependencies
    dependsOn(jij)
    from(jij.files) {
        into("META-INF/jars")
    }
    
    // Set Essential Loader as the Tweaker
    manifest.attributes(mapOf(
        "TweakClass" to "gg.essential.loader.stage0.EssentialSetupTweaker",
        "MixinConfigs" to "yourmod.mixins.json"
    ))
}

​
Troubleshooting

Check that:
  • The TweakClass manifest attribute is set correctly
  • Essential Loader jar is properly embedded in your mod jar (check META-INF/MANIFEST.MF and jar contents)
  • You’re testing on a supported Minecraft version (1.8.9 - 1.12.2 for LaunchWrapper)
Essential Loader automatically resolves Jar-in-Jar conflicts by selecting the most recent version. If you’re experiencing issues:
  • Ensure all dependencies in essential.mod.json have correct version numbers
  • Check that dependency jars are actually present in META-INF/jars/
  • Review the Minecraft logs for version resolution messages
Verify that:
  • Mixin is included as a Jar-in-Jar dependency
  • The MixinConfigs manifest attribute is set (if using Mixin)
  • Your Mixin configuration JSON file exists in resources
  • Annotation processors are properly configured in your build script
Common issues:
  • Missing repository: Ensure https://repo.essential.gg/repository/maven-public/ is added to repositories
  • Version mismatch: Check that you’re using a valid Essential Loader version
  • Template expansion errors: Verify your essential.mod.json template syntax matches the examples

​
Next Steps

Now that you have Essential Loader integrated with your mod:

Core Concepts

Learn about the three-stage architecture and how each stage works

Platform-Specific Guides

Deep dive into LaunchWrapper, Fabric, or ModLauncher integration

Container Mods

Learn about offline deployments and version pinning

Auto-Update Configuration

Configure automatic updates and update channels
For Fabric or ModLauncher integration, the process is different. Check the Integration Guides for platform-specific instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us