Skip to main content

​
Update Modes

Essential Loader supports three distinct update modes, configurable via the autoUpdate property:
Automatic updates enabled
  • Checks for updates on every game boot
  • Automatically downloads and installs the latest version
  • Ignores any pinned versions in the container mod
  • Updates to the latest version on the configured branch
autoUpdate=true
This is the default mode for thin container mods (without pinned jars).

​
How Version Checking Works

The loader implements sophisticated version checking logic to ensure smooth updates:

​
Initial Load

  1. Check for cached version: Look for already-downloaded jar in .minecraft/essential/loader/stage1/$variant/
  2. Verify checksum: Ensure cached version hasn’t been corrupted
  3. Use pinned version: If no cached version exists, extract from container mod
  4. Download latest: If neither exists, fetch latest from configured branch

​
Full Auto-Update Mode

if (autoUpdate == Full && !RELAUNCHING) {
    FileMeta latestOnlineMeta = fetchLatestMetadata(branch);
    if (latestOnlineMeta != null && !latestOnlineMeta.checksum.equals(localMd5)) {
        // Download and use latest version
    }
}
The loader:
  • Fetches metadata for the latest version on the configured branch
  • Compares checksums (not just version numbers)
  • Downloads if any difference is detected
  • Skips check if relaunching (to avoid infinite loops)

​
Manual Update Mode (with-prompt)

The click-to-update flow involves multiple configuration properties:
​
pendingUpdateVersion
string
Set by the loader when a new update is available.Must not be modified by the mod. Instead, set pendingUpdateResolution to respond.Example: 1.2.0.13
​
pendingUpdateResolution
boolean
Set by the mod (or fallback UI) to accept or reject the pending update.
  • true: Accept and download the update
  • false: Ignore this specific update version
  • null/unset: Decision pending
If the mod fails to write this property, the loader shows its own update prompt as a fallback.
​
overridePinnedVersion
string
Internal use only. Stores the last version the user accepted.Used to prevent downgrades when container mod version changes. See Pinning documentation for details.

​
Update Resolution Flow

If the mod fails to handle the update prompt, the loader displays a fallback UI. This ensures users can update even if the current mod version is broken.

​
Branch Selection

Control which release channel to follow using the branch property:
​
branch
string
default:"stable"
The update branch to follow.Common values:
  • stable: Production releases (default)
  • beta: Beta testing releases
  • staging: Development/staging releases
Can be set in container mod configuration or overridden in user configuration.

​
Configuration Hierarchy

Branch selection follows this priority order:
  1. User configuration file: .minecraft/essential/mods/$pub_$mod/essential-loader.properties
  2. System property: -Dessential.stage2.branch=beta
  3. Environment variable: ESSENTIAL_STAGE2_BRANCH=beta
  4. Container mod: essential-loader.properties in the jar
  5. Default: stable
# In container jar's essential-loader.properties
publisherSlug=essential
modSlug=mymod
branch=beta
All users default to beta branch.

​
Programmatic Update Control

Mods can programmatically enable or disable updates by writing to the user configuration file: 
Path configFile = gameDir
    .resolve("essential/mods")
    .resolve(publisherSlug + "_" + modSlug)
    .resolve("essential-loader.properties");

Properties config = new Properties();
if (Files.exists(configFile)) {
    try (InputStream in = Files.newInputStream(configFile)) {
        config.load(in);
    }
}

// Enable auto-updates
config.setProperty("autoUpdate", "true");

// Or enable click-to-update
config.setProperty("autoUpdate", "with-prompt");

// Change branch
config.setProperty("branch", "beta");

try (OutputStream out = Files.newOutputStream(configFile)) {
    config.store(out, "Updated by MyMod settings");
}

​
User Configuration Location

The configuration file path follows this pattern: 
.minecraft/essential/mods/$pub_$mod/essential-loader.properties
Where:
  • $pub = publisherSlug
  • $mod = modSlug
If publisherSlug and modSlug are identical, the folder name is shortened to just $mod.Special case: Essential itself uses .minecraft/essential/essential-loader.properties for legacy reasons.

​
Disabling Updates

To completely disable update checks:
Create or edit .minecraft/essential/mods/$pub_$mod/essential-loader.properties:
autoUpdate=false
With updates disabled:
  • No network requests are made (after initial download if needed)
  • Cached version is used if available
  • Pinned version is used if no cache exists
  • Perfect for offline gameplay or controlled environments

​
Update Prompts

When autoUpdate=with-prompt, the loader manages update prompts:

​
Mod-Implemented Prompts

Your mod should:
  1. Check for pendingUpdateVersion in the config file
  2. Display an in-game UI with update details
  3. Write pendingUpdateResolution=true or false based on user choice

​
Fallback Prompt

If the mod doesn’t handle the prompt, the loader shows a standalone UI:
  • Displays update version and changelog summary
  • Allows user to accept or decline
  • Ensures updates are possible even with broken mod versions
The fallback prompt is a safety mechanism. Mods should implement their own prompts for better integration with their UI.

​
Version API

The loader exposes version information via system properties: 
String version = System.getProperty("essential.stage2.version");
String branch = System.getProperty("essential.stage2.branch");
String autoUpdate = System.getProperty("essential.stage2.autoUpdate");
These properties are set after the stage2 jar is selected but before it’s loaded, allowing stage2 code to access version metadata.

Build docs developers (and LLMs) love

Get started for freeTalk to us