Overview
The Essential Loader is split into three distinct stages, each with specific responsibilities. This staged approach allows Essential to:- Support multiple Minecraft versions with minimal code duplication
- Handle different mod loader platforms (Fabric, Forge/LaunchWrapper, ModLauncher)
- Update components independently
- Maintain compatibility across a wide range of environments
For detailed technical documentation, refer to
loader/docs/stages.md in the Essential Loader repository.Stage architecture
Each stage has one jar file per platform (Fabric, LaunchWrapper, ModLauncher8, ModLauncher9). The stages are loaded sequentially, with each stage preparing the environment for the next.Stage progression
Stage 1: Initial loading
The first stage is loaded by the mod loader and initializes the Essential loading process.
Stage 2: Platform abstraction
The second stage provides platform-specific compatibility and prepares the environment.
Stage 1: Bootstrap
Purpose
Stage 1 is the entry point for Essential. It’s the code that the mod loader (Fabric, Forge, etc.) directly loads and executes.Responsibilities
- Initial detection and validation
- Determining which version of Essential to load
- Extracting and preparing Stage 2
- Handling version conflicts between multiple Essential sources
File location
In your.minecraft folder:
Source location
Stage 1 is extracted from:- Container mods in
.minecraft/mods/folder - Main Essential jar in
.minecraft/essential/folder - Whichever source has the most recent version is used
Platform variants
| Platform | Description |
|---|---|
fabric | For all Fabric mod loader versions |
launchwrapper | For Forge on MC 1.8.9 and 1.12.2 |
modlauncher8 | For Forge on MC 1.16.5 |
modlauncher9 | For Forge on MC 1.17+ |
Stage 1 handles version conflicts by comparing the Essential versions from different sources and using the newest one.
Stage 2: Platform layer
Purpose
Stage 2 provides platform-specific compatibility and abstractions, allowing the core Essential mod to work across different environments without platform-specific code.Responsibilities
- Platform-specific initialization
- Class loading and transformation setup
- Compatibility layer for different mod loaders
- Preparing the environment for Essential core
File location
In your.minecraft folder:
stage2.forge_1-12-2.jar
In the repository (after building):
Version independence
Stage 2 files typically include a.meta file with version information:
Location note
Although Stage 2 files are located in thestage1 folder, this is because Stage 1 is responsible for loading Stage 2. The file itself is still Stage 2 of the loader architecture.
Stage 3: Essential core
While not explicitly detailed in the available documentation, Stage 3 represents the actual Essential mod itself.Purpose
Stage 3 is the complete Essential mod that provides all user-facing features.Responsibilities
- Essential’s core functionality
- Minecraft GUI integration
- Cosmetics, social features, and other Essential features
- Interaction with Minecraft’s code
Loading
Stage 3 is loaded by Stage 2 after the platform environment has been properly prepared.Building loader stages
The Essential Loader stages are automatically built when building Essential:Building specific stages
To build a specific stage and platform:<platform> with: fabric, launchwrapper, modlauncher8, or modlauncher9.
Output locations
After building, find the jar files at:The latest Essential Loader version is included in the pinned jar files, so building Essential automatically builds the loader.
How stages work together
Loading sequence
Version handling
The multi-stage architecture allows for sophisticated version management:- Stage 1: Must match the container/mod file version
- Stage 2: Can be updated independently, cached separately
- Stage 3: Can be updated via in-game updates or container downloads
Platform abstraction
The stages work together to abstract platform differences:LaunchWrapper (MC 1.8.9, 1.12.2)
- Uses older Forge loading mechanism
- Stage 2 provides LaunchWrapper-specific compatibility
ModLauncher 8 (MC 1.16.5)
- Newer Forge loading system
- Stage 2 handles ModLauncher 8 specifics
ModLauncher 9 (MC 1.17+)
- Latest Forge loading system
- Stage 2 provides ModLauncher 9 compatibility
Fabric (all versions)
- Different mod loading paradigm from Forge
- Stage 2 provides Fabric-specific integration
For comprehensive details about platforms, see
loader/docs/platforms.md in the Essential Loader repository.Debugging loader stages
Checking stage versions
You can verify which stages are loaded:Common issues
Stage version mismatch- Delete the
loaderfolder and let Essential re-extract - Ensure you’re using compatible Essential versions
- Verify you’re using the correct mod file for your mod loader
- Check that you have the right Minecraft version
- Stage 2 updates independently; this is usually fine
- Only rebuild if experiencing compatibility issues
Advanced: Verifying stages
To verify the authenticity of loader stages, see the Verifying checksums guide, specifically:- Stage 1: Section on “Files in the .minecraft/essential/loader folder”
- Stage 2: Same section, with notes about
.metafiles
Remember that Stage 2 versions are independent of Essential versions, so you may need to check the loader repository specifically for older Stage 2 versions.