Skip to main content

​
Overview

A pinned container mod embeds a specific version of your mod directly into the container jar. This enables:
  • Fully offline usage without requiring initial download
  • Controlled, user-approved updates via click-to-update prompts
  • Modpack distribution with known mod versions
  • Gradual rollout strategies for new versions
Pinned container mods can still receive updates through two modes:
  1. Full auto-updates: Behaves like a thin container, ignoring the pinned version
  2. Click-to-update (default): Users are notified in-game and can choose to update

​
Embedding a Pinned Jar

​
Container Mod Configuration

To create a pinned container mod, add the following properties to your essential-loader.properties file at the root of your container jar: 
# Standard container mod properties
publisherSlug=essential
modSlug=examplemod
displayName=ExampleMod
branch=stable

# Pinning properties
pinnedFile=/path-to-embedded.jar
pinnedFileMd5=d41d8cd98f00b204e9800998ecf8427e
pinnedFileVersion=1.2.0

​
Pinning Properties

​
pinnedFile
string
required
Path to the embedded mod jar inside the container jar.Must include the leading slash (e.g., /bundled-mod-1.2.0.jar), otherwise it will be read as a regular URL.
The path should be unique to this mod+version to avoid clashes with other mods or versions of the same mod.
​
pinnedFileMd5
string
required
MD5 checksum of the pinned jar file.Used to verify the integrity of the embedded file and detect version changes.
md5sum path-to-embedded.jar
​
pinnedFileVersion
string
The version name as shown in the Essential Mods Panel.Required for:
  • Click-to-update functionality
  • Diff-updates (otherwise full jar is downloaded on first update)
  • Mods that need to know their own version
Example: 1.2.0
​
pinnedFileVersionId
string
The version ID from the Essential Mods Panel.Optional identifier that may be used instead of human-readable version in certain contexts. Currently unused but reserved for future functionality.Example: 6b26c76a26d49e5b60ecf53d

​
Pinning Stage2

Stage2 pinning is currently in development for third-party usage. Since stage2 is shared between all mods, the system needs to handle cases where different mods have different pinning preferences.
Stage2 can be pinned on Fabric and ModLauncher platforms. (On LaunchWrapper, stage2 is already included in the stage1 jar and cannot be updated independently.)

​
Configuration

Instead of the root essential-loader.properties file, place a properties file at: 
gg/essential/loader/stage1/stage2.properties
With the following required properties: 
pinnedFile=/bundled-stage2-1.0.0.jar
pinnedFileMd5=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
pinnedFileVersion=1.0.0
All three properties (pinnedFile, pinnedFileMd5, and pinnedFileVersion) are required for stage2 pinning.
The external configuration file for stage2 is located at: 
.minecraft/essential/loader/stage1/$variant/config.properties
It supports the same update properties as per-mod configuration: autoUpdate, branch, pendingUpdateVersion, and pendingUpdateResolution.

​
Use Cases

​
Offline Environments

Pinned container mods work perfectly in environments without internet access: 
publisherSlug=mycompany
modSlug=internal-tool
displayName=Internal Tool
pinnedFile=/internal-tool-2.1.0.jar
pinnedFileMd5=9f8e7d6c5b4a3210fedcba09
pinnedFileVersion=2.1.0
With autoUpdate=false in the user configuration, the mod runs entirely offline.

​
Modpack Distribution

Modpack creators can distribute specific tested versions: 
publisherSlug=essential
modSlug=skyblock-enhanced
displayName=Skyblock Enhanced
branch=stable
pinnedFile=/skyblock-enhanced-3.0.0.jar
pinnedFileMd5=1a2b3c4d5e6f7890abcdef12
pinnedFileVersion=3.0.0
Users receive the known-good version immediately, with optional click-to-update for newer releases.

​
Controlled Rollouts

Gradually roll out new versions by updating the pinned jar in new modpack releases: 
pinnedFile=/mymod-1.0.0.jar
pinnedFileMd5=abc123...
pinnedFileVersion=1.0.0
Existing users on older modpack versions see update prompts, while new users get the latest version immediately.

​
Version Override Behavior

The loader tracks accepted updates to prevent unintended downgrades:
  1. User accepts update to version 1.3.0
  2. overridePinnedVersion=1.3.0 is written to user config
  3. If container mod is downgraded (e.g., older modpack version with 1.2.0 pinned):
    • Pinned version 1.2.0 is ignored (older than override)
    • User continues using 1.3.0
  4. If container mod is upgraded (e.g., newer modpack with 1.4.0 pinned):
    • Pinned version 1.4.0 is used (newer than or equal to override)
    • overridePinnedVersion is cleared
    • User can now downgrade by downgrading the container mod
This behavior ensures users don’t lose functionality when modpack versions change, while still allowing intentional downgrades through container mod updates.

Build docs developers (and LLMs) love

Get started for freeTalk to us