Skip to main content

​
Prerequisites

Before building Essential from source, ensure you have the required tools and dependencies installed.

​
Required Java versions

You must have multiple Java Development Kits (JDKs) installed, even if you only want to build for a specific Minecraft version.
Install the following JDK versions from Adoptium:
  • Java 21 (or newer) - Must be the default Java version
  • Java 17
  • Java 16
  • Java 8
1

Install multiple JDK versions

Download and install all four required Java versions from Adoptium. The build system needs access to all of them.
2

Set Java 21 as default

Configure your system to use Java 21 as the default Java version:
# Check current Java version
java -version

# Set JAVA_HOME (adjust path to your Java 21 installation)
export JAVA_HOME=/path/to/java-21
export PATH=$JAVA_HOME/bin:$PATH
3

Verify installation

Confirm Java 21 is active:
java -version
# Should output: openjdk version "21.x.x" or similar

​
Additional tools

No additional tools like Gradle need to be installed manually. The Gradle wrapper included in the repository will automatically download the correct Gradle version.
Required:
  • Git (for cloning the repository and managing submodules)
Recommended:
  • 16GB+ RAM (configured in gradle.properties as -Xmx16G)
  • Fast internet connection (first build downloads many dependencies)

​
Cloning the repository

Essential uses git submodules. You must initialize them after cloning.
1

Clone with submodules

Option A: Clone with recursive flag (recommended)
git clone --recursive https://github.com/EssentialGG/Essential.git
cd Essential
Option B: Clone then initialize submodules
git clone https://github.com/EssentialGG/Essential.git
cd Essential
git submodule update --init --recursive
2

Update submodules after pulling

Every time you pull new changes, update the submodules:
git pull
git submodule update --init --recursive

​
Building Essential

​
Build all versions

To build Essential for all Minecraft versions: 
./gradlew build
Depending on your system and internet connection, the first build may take 10 minutes to an hour. Subsequent builds will be much faster thanks to Gradle’s caching.

​
Build for specific version

To build for a specific Minecraft version and mod loader: 
# Format: ./gradlew :<version>-<loader>:build

# Examples:
./gradlew :1.12.2-forge:build
./gradlew :1.20.4-fabric:build
./gradlew :1.21.1-neoforge:build
Building any version other than the main version (currently 1.12.2) will require all versions between it and the main version to be set up regardless. The time saved over building all versions may vary.

​
Output files

Once the build completes, find the compiled jars in: 
versions/<MC-Version>/build/libs/
You’ll find two types of jar files:
  1. pinned_*.jar - Mod file for Modrinth/CurseForge
    • Contains a specific version of Essential
    • Larger file size
    • Suitable for modpacks
  2. Essential *.jar - Main mod file
    • Downloaded by in-game updater
    • Used by third-party mods embedding Essential Loader
    • Used by container mods and the Essential Installer

​
Building Essential Loader

The Essential Loader is automatically built when building the main mod (included in pinned_ jars). The loader is split into three stages, each with platform-specific variants: Platforms:
  • fabric - All Fabric versions
  • launchwrapper - Forge on Minecraft 1.8.9 and 1.12.2
  • modlauncher8 - Forge on Minecraft 1.16.5
  • modlauncher9 - Forge on Minecraft 1.17+
Output location: 
loader/<stage>/<platform>/build/libs/
For technical details about loader stages, see loader/docs/stages.md in the repository. For platform details, see loader/docs/platforms.md.

​
Building Essential Container

The Essential Container is a thin mod that downloads Essential on first launch.
1

Choose your platform

Select the appropriate platform for your target:
  • fabric - All Fabric versions
  • launchwrapper - Forge 1.8.9 and 1.12.2
  • modlauncher8 - Forge 1.16.5
  • modlauncher9 - Forge 1.17+, NeoForge
2

Build the container

# Format: ./gradlew :loader:container:<platform>:build

# Examples:
./gradlew :loader:container:fabric:build
./gradlew :loader:container:launchwrapper:build
./gradlew :loader:container:modlauncher9:build
3

Locate the output

Find the container jar in:
loader/container/<platform>/build/libs/
Container mods are small (< 1 MB) and download the latest Essential version at runtime, while pinned mods include a specific Essential version.

​
Build configuration

The build is configured in several key files:

​
gradle.properties

Key build properties: 
version=1.3.10.6
minecraftVersion=11202
org.gradle.jvmargs=-Xmx16G
org.gradle.parallel=true
org.gradle.caching=true

​
build.gradle.kts

Main build script with:
  • Dependency management
  • Kotlin version constraints
  • Platform-specific configurations
  • Relocation rules for bundled libraries

​
settings.gradle.kts

Defines all Minecraft version projects: 
listOf(
    "1.8.9-forge",
    "1.12.2-forge",
    "1.16.2-forge",
    "1.16.2-fabric",
    // ... and many more
    "1.21.11-fabric",
)

​
Gradle wrapper

Essential includes the Gradle wrapper for reproducible builds:
  • Linux/macOS: ./gradlew
  • Windows: gradlew.bat
Always use the wrapper scripts instead of a local Gradle installation. This ensures you use the exact same Gradle version as the official builds and guarantees bit-for-bit identical output.

​
Continuous Integration (CI)

Every Essential release is built by CI twice:
1

Internal CI build

Built on ModCore’s internal, self-hosted CI system:
  • Faster build times
  • Runs integration tests
  • Uploads jars to infrastructure
  • Publishes source code to GitHub
2

Public GitHub Actions build

Built directly from public source on GitHub-provided runners:
  • Ensures published source matches released jars
  • Builds from scratch in clean environment
  • Verifies bit-for-bit identical output
  • Publishes checksums for verification

​
Verifying checksums

You can verify the authenticity of Essential files:
1

Build locally or get checksums

Option A: Build Essential yourself following the steps aboveOption B: Find the GitHub Actions run and download the checksums artifact or view the Generate checksums log
2

Identify file type

Determine which file you’re verifying:
  • .minecraft/mods/: Container (< 1 MB) or pinned mod (larger)
  • .minecraft/essential/: Main Essential jar
  • .minecraft/essential/loader/: Loader stage files
  • .minecraft/essential/libraries/: Extracted dependencies
3

Compare checksums

Use a SHA-256 checksum tool:
sha256sum Essential\ \(Fabric_1.20.4\).jar
Compare the output to the checksum from your build or the GitHub Actions log.
Some Essential versions are compatible with multiple Minecraft versions. See versions/aliases.txt for the exact mapping.

​
Common build issues

Error: Build fails with Java version errorsSolution: Ensure Java 21 is your default version:
java -version  # Should show Java 21
Also verify all required JDK versions (8, 16, 17, 21) are installed.
Error: java.lang.OutOfMemoryError: Java heap spaceSolution: The build is configured for 16GB RAM in gradle.properties. If you have less RAM, reduce the value:
org.gradle.jvmargs=-Xmx8G
Error: Missing files or build failures related to the loaderSolution: Update git submodules:
git submodule update --init --recursive
Error: Build hangs or fails mysteriouslySolution: Stop all Gradle daemons and retry:
./gradlew --stop
./gradlew build
This is expected. The first build:
  • Downloads all Minecraft versions
  • Downloads all dependencies
  • Sets up development environments
  • Compiles for all platforms
Subsequent builds use Gradle’s cache and complete much faster.

​
Development environment

To set up Essential for development in your IDE:
1

Import the project

Import the Essential directory as a Gradle project in your IDE (IntelliJ IDEA or Eclipse).
2

Wait for Gradle sync

Let your IDE sync the Gradle project. This may take several minutes on first import.
3

Run configurations

Essential includes pre-configured run configurations. Look for “Minecraft Client” run configurations for each version.Note: Essential is client-side only, so server run configs are disabled.

​
License restrictions

Essential is source-available but NOT open source. You can build and verify the code, but you cannot:
  • Use any code or assets (even for personal use)
  • Incorporate the source code in other projects
  • Use the code as a reference for new projects
  • Modify or alter the source code
  • Distribute compiled or modified versions
See the full LICENSE for details.

​
Getting help

For build issues or development questions:
  • Join the Essential Discord and use the dedicated support channels
  • Check existing GitHub issues for similar problems
  • Review the loader documentation in loader/docs/

​
Additional resources

Loader stages

See loader/docs/stages.md for technical details about the three-stage loader architecture

Loader platforms

See loader/docs/platforms.md for details about different mod loader platforms

Container vs Pinned

See loader/docs/container-mods.md for technical details about container and pinned mod variants

Build logic

See build-logic/src/main/kotlin/essential/pinned-jar.gradle.kts for how pinned jars are generated

Build docs developers (and LLMs) love

Get started for freeTalk to us