Loader Stages - Essential Mod

Overview

Essential uses a three-stage loader architecture to enable seamless in-game updates, version management, and cross-platform compatibility without requiring users to manually update mod files.

The loader is split into three stages, each with one JAR per platform. For platform details, see the Platforms documentation.

Why Three Stages?

A multi-stage loader solves several critical challenges:

In-Game Updates

Users receive updates automatically without replacing mod files.

Version Isolation

Different Minecraft versions can use different Essential versions without conflicts.

Classloader Separation

Prevents version conflicts and enables hot-swapping of code.

Minimal Footprint

Container mods are tiny (< 1MB) since they download the actual mod on demand.

Stage 0: Initial Bootstrap

Purpose

Stage 0 is the entry point that Minecraft’s mod loader executes. It’s embedded in both container mods and pinned JARs.

Responsibilities

Detect environment

Identify the Minecraft version, mod loader type (Forge/Fabric/NeoForge), and platform variant.

Extract Stage 1

Extract the Stage 1 loader from either:

The container mod JAR (for container mods)
The bundled Essential JAR (for pinned mods)

Hand off control

Pass control to Stage 1 with environment information.

File Location

Stage 0 files

loader/stage0/<platform>/build/libs/
├── loader-fabric.jar
├── loader-launchwrapper.jar
├── loader-modlauncher8.jar
└── loader-modlauncher9.jar

Stage 0 code example

Simplified Stage 0 entry point

@Mod("essential")
public class EssentialLoader {
    public EssentialLoader() {
        // Detect platform
        Platform platform = detectPlatform();
        
        // Extract stage1.jar to .minecraft/essential/loader/
        File stage1 = extractStage1(platform);
        
        // Load and invoke Stage 1
        ClassLoader stage1Loader = createIsolatedClassLoader(stage1);
        stage1Loader.loadClass("gg.essential.loader.stage1.EssentialLoader")
            .getMethod("load", Platform.class)
            .invoke(null, platform);
    }
}

Stage 1: Version Management

Purpose

Stage 1 manages Essential versions and prepares the environment for loading the actual mod.

Responsibilities

Version detection

Check what Essential version is currently installed in .minecraft/essential/.

Update check

For container mods, check Essential’s servers for the latest version and download if needed.

Extract Stage 2

Extract Stage 2 from the Essential JAR for the current Minecraft version.

Load Stage 2

Create an isolated classloader and hand off control to Stage 2.

File Location

Stage 1 files

.minecraft/essential/loader/
└── stage1.jar

Stage 1 is extracted from whichever source has the most recent version (container mod or pinned JAR).

Update Flow

Container Mod
Pinned Mod

Container mods always check for the latest Essential version on startup.

Version Isolation

Stage 1 ensures different Minecraft versions can use different Essential versions:

Essential version storage

.minecraft/essential/
├── Essential (fabric_1.20.4).jar
├── Essential (forge_1.12.2).jar
├── Essential (forge_1.16.5).jar
└── libraries/
    └── ...

Each file is specific to a Minecraft version and loader combination.

Stage 2: Mod Loading

Purpose

Stage 2 is the actual Essential Mod implementation. It loads dependencies and initializes Essential’s features.

Responsibilities

Extract libraries

Extract bundled dependencies from META-INF/jars/ to .minecraft/essential/libraries/.

Set up classloader

Create a classloader with Essential and all dependencies.

Initialize Essential

Load and initialize the main Essential mod class.

File Location

Stage 2 files

loader/stage2/<platform>/build/libs/
├── stage2-fabric.jar
├── stage2-launchwrapper.jar
├── stage2-modlauncher8.jar
└── stage2-modlauncher9.jar

Stage 2 is not updated in lockstep with Essential releases. It may be older or newer than the Essential version, as long as they remain compatible.

Library Management

Stage 2 handles Essential’s dependencies:

Dependency structure

.minecraft/essential/
├── Essential (fabric_1.20.4).jar
│   └── META-INF/jars/
│       ├── library1.jar
│       ├── library2.jar
│       └── ...
└── libraries/
    ├── library1.jar  (extracted)
    ├── library2.jar  (extracted)
    └── ...

Why extract libraries?

Extracting libraries has several benefits:

Shared across versions: Multiple Essential versions can share the same library files
Faster startup: No need to extract every launch
Smaller downloads: Updates only need to include changed libraries
Classloader flexibility: Libraries can be loaded in specific classloaders as needed

Stage Interaction Diagram

Container vs Pinned Mods

The loader stages enable two different distribution models:

Container Mod
Pinned Mod

Container Mod (essential.gg/download)

A minimal JAR that downloads Essential on first launch.Structure:

essential-fabric.jar (< 1MB)
├── Stage 0
└── Stage 1

Behavior:

Downloads latest Essential on first launch
Automatically updates to new versions
Minimal file size
Four variants (one per platform)

Use cases:

Essential Installer
essential.gg/download
Mods that embed Essential Loader

Pinned Mod (Modrinth/CurseForge)

A complete JAR with a specific Essential version.Structure:

pinned_Essential (fabric_1.20.4).jar (60-80MB)
├── Stage 0
├── Stage 1  
├── Stage 2
└── Essential Mod (specific version)

Behavior:

Uses bundled Essential version
No automatic updates (unless user opts in)
Larger file size
One variant per Minecraft version + loader

Use cases:

Modrinth distribution
CurseForge distribution
Users who want version control

Classloader Hierarchy

Each stage uses an isolated classloader to prevent version conflicts:

This isolation allows Stage 1 to be updated independently of Stage 2, and both can be updated without affecting the container mod in the mods folder.

File Locations Reference

.minecraft/mods/ folder

Container mods (< 1MB):

essential-fabric.jar
essential-forge-1.12.2.jar
essential-forge-1.16.5.jar
essential-forge-1.20.4.jar

Pinned mods (60-80MB):

pinned_Essential (fabric_1.20.4).jar
pinned_Essential (forge_1.12.2).jar

.minecraft/essential/ folder

Main Essential JARs:

Essential (fabric_1.20.4).jar
Essential (fabric_1.20.4).processed.jar (temporary)
Essential (forge_1.12.2).jar

Extracted libraries:

libraries/*.jar

.minecraft/essential/loader/ folder

Stage files:

stage1.jar (extracted from container/pinned mod)
stage2.fabric_1.20.4.jar
stage2.fabric_1.20.4.jar.meta (version info)

Building the Loader

Building All Stages

The loader is automatically built when building Essential:

./gradlew build

Loader JARs are found in loader/<stage>/<platform>/build/libs/.

Building Specific Stages

Building individual stages

# Build Stage 1 for all platforms
./gradlew :loader:stage1:build

# Build Stage 2 for Fabric
./gradlew :loader:stage2:fabric:build

# Build container mod for launchwrapper
./gradlew :loader:container:launchwrapper:build

The loader is maintained in a separate Git submodule at loader/. Run git submodule update --init --recursive after cloning.

Verifying Loader Files

To verify the authenticity of loader files:

Identify the file type

Check if it’s stage1.jar, stage2.<loader>_<version>.jar, or a container mod.

Build from source or download checksums

Either build the loader yourself or download checksums from GitHub Actions.

Compare checksums

Use sha256sum (Linux) or similar tools to verify file integrity.

See the Verification guide for detailed instructions on verifying all Essential files.

Advanced Topics

Loader stage versioning

Each stage has its own version number:

Stage 0: Embedded in container/pinned mods, updated with Essential releases
Stage 1: Extracted from the latest source (container or pinned mod)
Stage 2: Has independent versioning, stored with .meta files

The .meta file contains Stage 2’s version:

.minecraft/essential/loader/stage2.fabric_1.20.4.jar.meta

{
  "version": "1.2.3",
  "timestamp": 1234567890
}

Processed JARs

Files ending in .processed.jar are temporary transformations of the main Essential JAR:

Created by Stage 2 for compatibility
Safe to delete (regenerated on next launch)
Contain the same code with minor modifications

Hot-swapping and updates

The multi-stage architecture theoretically allows hot-swapping Essential without restarting Minecraft:

Stage 1 downloads a new Essential version
Unloads the current Stage 2 classloader
Extracts and loads the new Stage 2
Re-initializes Essential features

This is currently not implemented but the architecture supports it.

Next Steps

Platform Support

Learn about the four loader platforms Essential supports

Building Container

Build Essential Container mods from source

Building Loader

Build the Essential Loader stages

Architecture

Return to the architecture overview

Get Started

Building

Core Concepts

​Overview

​Why Three Stages?

In-Game Updates

Version Isolation

Classloader Separation

Minimal Footprint

​Stage 0: Initial Bootstrap

​Purpose

​Responsibilities

​File Location

​Stage 1: Version Management

​Purpose

​Responsibilities

​File Location

​Update Flow

​Version Isolation

​Stage 2: Mod Loading

​Purpose

​Responsibilities

​File Location

​Library Management

​Stage Interaction Diagram

​Container vs Pinned Mods

​Container Mod (essential.gg/download)

​Pinned Mod (Modrinth/CurseForge)

​Classloader Hierarchy

​File Locations Reference

​Building the Loader

​Building All Stages

​Building Specific Stages

​Verifying Loader Files

​Advanced Topics

​Next Steps

Platform Support

Building Container

Building Loader

Architecture

Build docs developers (and LLMs) love

Overview

Why Three Stages?

Stage 0: Initial Bootstrap

Purpose

Responsibilities

File Location

Stage 1: Version Management

Purpose

Responsibilities

File Location

Update Flow

Version Isolation

Stage 2: Mod Loading

Purpose

Responsibilities

File Location

Library Management

Stage Interaction Diagram

Container vs Pinned Mods

Container Mod (essential.gg/download)

Pinned Mod (Modrinth/CurseForge)

Classloader Hierarchy

File Locations Reference

Building the Loader

Building All Stages

Building Specific Stages

Verifying Loader Files

Advanced Topics

Next Steps