Skip to main content

​
Project Structure

Essential Mod is built as a multi-module Gradle project with a sophisticated architecture designed to support multiple Minecraft versions and mod loaders simultaneously.

​
Directory Layout

Essential/
├── api/                    # Public API for third-party mods
├── build-logic/            # Custom Gradle plugins and build logic
├── elementa/               # UI framework (statev2, layoutdsl)
├── gui/                    # GUI components (elementa, essential, vigilance)
├── loader/                 # Essential Loader (submodule)
├── src/                    # Core mod implementation
├── subprojects/            # Modular feature implementations
└── versions/               # Version-specific implementations

​
Core Components

Essential is organized into several key layers that work together to provide a seamless cross-version experience.

​
Main Module

The src/main directory contains the core Essential Mod implementation: 
src/main/
├── java/
│   ├── gg/essential/
│   │   ├── Essential.java           # Main mod entry point
│   │   ├── api/tweaker/             # Tweaker integration
│   │   ├── asm/                     # Bytecode transformers
│   │   ├── commands/                # Command implementations
│   │   ├── cosmetics/               # Cosmetics system
│   │   └── ...
The core module is shared across all Minecraft versions. Version-specific code is isolated in the versions/ directory.

​
Subprojects

Essential uses a modular architecture with specialized subprojects:
SubprojectPurpose
classloadersCustom class loading utilities
clipboardCross-platform clipboard support
cosmeticsCosmetics rendering and management
feature-flagsFeature flag system for gradual rollouts
iceICE (Interactive Connectivity Establishment) for P2P
immediatelyfastPerformance optimizations (1.18+)
infraInfrastructure and networking
kdiscordipcDiscord Rich Presence integration
libsBundled third-party libraries
lwjgl3LWJGL3 support for older versions
minecraft-authAuthentication system
plasmoVoice chat integration
pseudotcpPseudo-TCP over UDP
quic-connectorQUIC protocol support
slf4j-to-log4jSLF4J adapter for MC < 1.19.3
utilsUtility classes and helpers
vigilance2Settings UI framework
Each subproject is self-contained and can be built independently, promoting code reusability and maintainability.

​
API Layer

The api/ directory provides a stable public API for third-party mods:
Example: Using Essential API
import gg.essential.api.EssentialAPI;

public class MyMod {
    public void init() {
        // Check if Essential is loaded
        if (EssentialAPI.getMinecraftUtil().isRunningEssential()) {
            // Use Essential features
        }
    }
}
The API is versioned per Minecraft version to ensure compatibility. See versions/api/ for version-specific implementations.

​
GUI Framework

Essential includes a sophisticated GUI system:

Elementa

A declarative UI framework with layout DSL for building modern interfaces.

Vigilance

Settings and configuration UI framework with automatic serialization.

​
Build System

The build-logic/ directory contains custom Gradle plugins:
Embeds Essential Loader into the mod JAR. This plugin handles bundling the appropriate loader stage files for each platform.
Creates “pinned” JAR files for Modrinth/CurseForge distribution. These JARs contain a specific version of Essential, unlike container mods which download the latest version.
Manages multi-version support and mappings transformation. Handles the complex process of maintaining a single codebase across multiple Minecraft versions.

​
Version-Specific Code

The versions/ directory contains code specific to each Minecraft version and loader combination:
Version structure
versions/
├── 1.8.9-forge/
│   └── src/main/java/gg/essential/mixins/
├── 1.12.2-forge/
├── 1.16.2-fabric/
├── 1.16.2-forge/
├── ...
├── 1.21.11-fabric/
└── aliases.txt          # Version aliases mapping
Most version directories only contain mixins and compatibility patches. The bulk of the code is shared in the main module.

​
Version Aliases

Some Essential versions are compatible with multiple Minecraft versions. The aliases.txt file maps compatible versions:
versions/aliases.txt
1.21.10-fabric → 1.21.9-fabric
1.16.5-forge → 1.16.2-forge
This allows Essential to support more Minecraft versions without duplicating code.

​
Build Outputs

Essential produces different types of artifacts for different use cases:
1

Main JAR

The standard Essential JAR found in versions/<MC-Version>/build/libs/Essential (<Loader>_<MC-Version>).jar. This is downloaded by the Essential Loader and used for in-game updates.
2

Pinned JAR

Prefixed with pinned_, this JAR includes a specific version of Essential Loader and is distributed via Modrinth/CurseForge. Users install this directly in their mods folder.
3

Container JAR

A minimal JAR (< 1MB) that downloads the latest Essential on first launch. Found in loader/container/<platform>/build/libs/.

​
Architecture Benefits

This architecture provides several key advantages:

Code Reuse

Shared core implementation across all versions minimizes duplication and maintenance burden.

Modularity

Subprojects can be developed, tested, and updated independently.

Flexibility

Version-specific directories allow targeted fixes without affecting other versions.

Scalability

Easy to add support for new Minecraft versions and mod loaders.

​
Next Steps

Multi-Version Support

Learn how Essential supports Minecraft 1.8.9 through 1.21.x

Loader Stages

Understand the three-stage loader architecture

Platform Support

Explore support for Forge, Fabric, and NeoForge

Building Essential

Get started building Essential from source

Build docs developers (and LLMs) love

Get started for freeTalk to us