Skip to main content

​
Overview

Essential supports an unprecedented range of Minecraft versions from 1.8.9 to 1.21.x using a single unified codebase. This is achieved through a sophisticated build system that transforms code to match each version’s API.

​
Supported Versions

Essential currently supports the following Minecraft versions:
  • 1.8.9-forge
  • 1.12.2-forge
These versions use Forge with LaunchWrapper and require special handling for LWJGL2 compatibility.
  • 1.16.2-forge, 1.16.2-fabric
  • 1.17.1-forge, 1.17.1-fabric
Introduction of Fabric support and transition to ModLauncher on Forge.
  • 1.18.1-fabric, 1.18.2-fabric, 1.18.2-forge
  • 1.19-fabric, 1.19.2-fabric/forge, 1.19.3-fabric/forge, 1.19.4-fabric/forge
Full dual-loader support with improved performance features.
  • 1.20-fabric through 1.20.6 (fabric/forge/neoforge)
  • 1.21.1 through 1.21.11 (fabric/forge/neoforge)
Adds NeoForge support starting from 1.20.4.
Some Minecraft versions share the same Essential codebase. See the Version Aliases section for details.

​
How It Works

​
Preprocessor System

Essential uses a preprocessor-based approach to handle API differences between Minecraft versions: 
//#if MC >= 11600
import net.minecraft.client.gui.screen.Screen;
//#else
import net.minecraft.client.gui.GuiScreen;
//#endif

public class MyGui extends 
//#if MC >= 11600
    Screen
//#else
    GuiScreen
//#endif
{
    // Implementation
}
The preprocessor evaluates these conditions at build time, generating version-specific source code.

​
Mapping Transformations

Minecraft’s obfuscation and API changes between versions are handled through mapping files:
versions/1.12.2-1.8.9.txt
net.minecraft.util.text.TextFormatting → net.minecraft.util.EnumChatFormatting
net.minecraft.entity.Entity getDataManager() → getDataWatcher()
net.minecraft.client.gui.GuiSlot func_192638_a_() → drawSelectionBox()
Simple name mappings for similar APIs.
These mapping files are generated and maintained by Essential’s multi-version tooling. They transform the modern API calls to work with older Minecraft versions.

​
Main Version Strategy

Essential uses 1.12.2 as the main development version:
1

Write code for 1.12.2

Developers write code targeting the 1.12.2 API. This is the “source of truth” for the codebase.
2

Transform upward

The build system transforms 1.12.2 code to work with newer versions (1.16.2+) by applying mappings and preprocessor directives.
3

Transform downward

Similarly, code is transformed downward to support 1.8.9 by reverting API changes.
Building any version other than 1.12.2 requires all versions between it and 1.12.2 to be set up, as the transformation chain must be complete.

​
Version Aliases

Not every Minecraft version requires a unique Essential build. The versions/aliases.txt file defines compatible versions:
versions/aliases.txt
1.21.10-fabric → 1.21.9-fabric
1.21.8-neoforge → 1.21.7-neoforge
1.21.8-forge → 1.21.7-forge
1.21.8-fabric → 1.21.7-fabric
1.21.2-fabric → 1.21.3-fabric
1.21-fabric → 1.21.1-fabric
1.18-fabric → 1.18.1-fabric
1.19.1-fabric → 1.19.2-fabric
1.16.5-forge → 1.16.2-forge
1.16.5-fabric → 1.16.2-fabric
When Minecraft releases a minor update that doesn’t break mod compatibility, Essential can reuse the same build.
When building or running Essential:
  1. The loader checks which Essential version is compatible with the current Minecraft version
  2. If an alias exists, it uses the aliased version’s JAR
  3. This reduces build time and storage requirements
For example, Minecraft 1.16.5 users receive the same Essential JAR as 1.16.2 users.

​
Version-Specific Code

While most code is shared, some features require version-specific implementations:

​
Directory Structure

Version-specific implementations
versions/
├── 1.8.9-forge/src/main/java/gg/essential/mixins/
│   ├── transformers/client/
│   ├── transformers/compatibility/
│   └── transformers/feature/
├── 1.21.11-fabric/src/main/java/gg/essential/mixins/
│   └── transformers/feature/gamerules/
Version directories typically only contain mixins and compatibility patches. The vast majority of code lives in the shared src/main directory.

​
Common Version-Specific Cases

Patches for specific Minecraft bugs or compatibility issues with other mods:
versions/1.8.9-forge/.../Mixin_FixResourcePackCrash.java
@Mixin(ResourcePackRepository.class)
public class Mixin_FixResourcePackCrash {
    // Fix a crash in 1.8.9's resource pack loading
}
Features that work differently across versions:
versions/1.8.9-forge/.../Mixin_NameplateIcon_Render.java
@Mixin(RendererLivingEntity.class)
public class Mixin_NameplateIcon_Render {
    // 1.8.9-specific nameplate rendering
}
Patches for compatibility with version-specific mods:
.../modcompat/oldanimationsmod/MixinCustomLayerBipedArmor.java
@Mixin(CustomLayerBipedArmor.class)
public class MixinCustomLayerBipedArmor {
    // Compat with OldAnimationsMod (1.8.9 only)
}

​
Dependencies and Libraries

Different Minecraft versions require different supporting libraries:

​
SLF4J Support

build.gradle.kts
// Minecraft 1.17-1.19.2 ship SLF4J 1.x
// Only 1.19.3+ ships SLF4J 2.x
if (platform.mcVersion < 11903) {
    implementation(bundle(project(":slf4j-to-log4j"))!!)
}

​
Performance Optimizations

build.gradle.kts
// ImmediatelyFast is only compatible with 1.18+
if (platform.mcVersion >= 11800) {
    implementation(bundle(project(":immediatelyfast"))!!)
}

​
LWJGL3 Backport

Older Minecraft versions (1.8.9-1.12.2) use LWJGL2. Essential includes an LWJGL3 backport for modern features:
build.gradle.kts
implementation(bundle(project(":lwjgl3"))!!)
runtimeOnly(bundle(project(":lwjgl3:impl"))!!)

​
Build Process

​
Building All Versions

Building all versions
./gradlew build
This builds Essential for every supported Minecraft version. The first build may take 10-60 minutes depending on your system.

​
Building Specific Versions

Building a specific version
./gradlew :1.12.2-forge:build
./gradlew :1.21.11-fabric:build
Building any version other than the main version (1.12.2) requires all intermediate versions to be set up, so time savings may vary.

​
Build Output

Built JARs are located in versions/<MC-Version>/build/libs/: 
versions/1.20.4-fabric/build/libs/
├── Essential (fabric_1.20.4).jar          # Main JAR
└── pinned_Essential (fabric_1.20.4).jar   # Modrinth/CurseForge JAR

​
Testing Across Versions

Essential’s CI system verifies builds across all supported versions:
1

Internal CI

Builds all versions, runs integration tests, and uploads artifacts to Essential’s infrastructure.
2

Public GitHub CI

Rebuilds from public source on GitHub runners and verifies bit-for-bit identical output.
3

Checksum Verification

Publishes checksums for third-party verification without requiring a full rebuild.
You can verify the authenticity of Essential builds by comparing checksums from GitHub Actions runs. See the README for detailed instructions.

​
Challenges and Solutions

API Changes

Minecraft’s API changes dramatically between versions. Solution: Mapping files and preprocessor directives.

Performance

Older versions lack modern optimizations. Solution: Backport features like ImmediatelyFast and LWJGL3.

Mod Compatibility

Popular mods differ per version. Solution: Version-specific compatibility mixins.

Build Time

Building all versions takes significant time. Solution: Version aliases and incremental builds.

​
Next Steps

Loader Stages

Learn how Essential’s loader handles multi-version environments

Platform Support

Understand the four loader platforms Essential supports

Build Setup

Set up your environment to build Essential

Architecture

Return to the architecture overview

Build docs developers (and LLMs) love

Get started for freeTalk to us