Stage 0 API

​

Overview

​

Core Components

​

EssentialLoader (Common)

​

loadStage1File()

public Path loadStage1File(Path gameDir) throws Exception

• Checks for stage1.update.jar and applies updates if present
• Scans classpath for all gg/essential/loader/stage0/stage1.jar resources
• Compares versions using manifest Implementation-Version attribute
• Extracts the latest version to essential/loader/stage0/{variant}/stage1.jar
• Returns the extracted file path

{gameDir}/essential/loader/stage0/{variant}/
  ├── stage1.jar          # Current Stage 1 JAR
  └── stage1.update.jar   # Pending update (if present)

​

Platform Implementations

​

LaunchWrapper Platform

​

EssentialSetupTweaker

public class EssentialSetupTweaker implements ITweaker {
    public EssentialSetupTweaker() throws Exception
}

1. Extract Stage 1: Calls loadStage1File() using Launch.minecraftHome
2. Add to ClassLoader: Adds Stage 1 JAR to LaunchClassLoader and its parent
3. Exclusion: Registers gg.essential.loader.stage1. package exclusion
4. Instantiate: Loads Stage 1’s EssentialSetupTweaker via reflection
5. Delegate: Forwards all ITweaker calls to Stage 1 instance

// Automatic initialization when specified as tweaker
// In launcher configuration:
--tweakClass gg.essential.loader.stage0.EssentialSetupTweaker

System ClassLoader
└── LaunchWrapper ClassLoader (with stage1 exclusion)
    └── Stage 1 Classes (gg.essential.loader.stage1.*)

​

Fabric Platform

​

EssentialSetupPreLaunch

public class EssentialSetupPreLaunch implements PreLaunchEntrypoint {
    @Override
    public void onPreLaunch()
}

1. Extract Stage 1: Calls loadStage1File() using Fabric’s game directory
2. Create ClassLoader: Creates isolated URLClassLoader with Stage 1 JAR
3. Instantiate: Loads Stage 1’s EssentialSetupPreLaunch class
4. Delegate: Forwards onPreLaunch() call to Stage 1 instance

// In fabric.mod.json
{
  "entrypoints": {
    "preLaunch": [
      "gg.essential.loader.stage0.EssentialSetupPreLaunch"
    ]
  }
}

Fabric Loader ClassLoader
└── URLClassLoader (isolated)
    └── Stage 1 Classes (gg.essential.loader.stage1.*)

​

ModLauncher Platform

​

EssentialTransformationService

public class EssentialTransformationService 
    extends EssentialTransformationServiceBase

1. Get Game Directory: Queries ModLauncher environment for GAMEDIR
2. Extract Stage 1: Calls loadStage1File() with discovered game directory
3. Create ClassLoader: Creates isolated URLClassLoader with Stage 1 JAR
4. Instantiate: Loads Stage 1’s EssentialTransformationService class
5. Delegate: Forwards all ITransformationService calls to Stage 1 instance

META-INF/services/cpw.mods.modlauncher.api.ITransformationService
  → gg.essential.loader.stage0.EssentialTransformationService

• modlauncher8: Forge 1.15-1.16 (ModLauncher 8.x)
• modlauncher9: Forge 1.17-1.20.1 (ModLauncher 9.x/10.x)
• modlauncher11: NeoForge 1.20.2+ (ModLauncher 11.x)

​

Relocation Requirements

​

Required Relocations

// In build.gradle with Shadow plugin
shadowJar {
    relocate 'gg.essential.loader.stage0', 'your.mod.loader.stage0'
}

1. Class Uniqueness: Each mod needs its own Stage 0 instance in the platform class loader
2. Conflict Avoidance: Multiple mods may bundle different Stage 0 versions
3. Isolation: Stage 0 must bootstrap independently per mod
4. Version Management: Each mod controls its own Stage 1 discovery

​

Relocation Verification

# Check that stage0 classes are relocated
jar -tf your-mod.jar | grep stage0

# Should show YOUR relocated package, not gg.essential.loader.stage0
com/example/yourmod/loader/stage0/EssentialSetupTweaker.class

​

Stage 1 Discovery Algorithm

​

Version Comparison

private static int getVersion(URL file) {
    try (JarInputStream in = new JarInputStream(file.openStream())) {
        Manifest manifest = in.getManifest();
        Attributes attributes = manifest.getMainAttributes();
        
        // Verify package name
        if (!"gg/essential/loader/stage1/".equals(
            attributes.getValue("Name"))) {
            return -1;
        }
        
        // Parse version number
        return Integer.parseInt(
            attributes.getValue("Implementation-Version"));
    }
}

​

Discovery Order

1. Check for existing stage1.jar in data directory
2. Check for pending stage1.update.jar
3. Scan classpath for embedded gg/essential/loader/stage0/stage1.jar resources
4. Compare all versions and select highest
5. Extract selected version if newer than current

​

Error Handling

​

Common Errors

​

Development & Testing

​

Embedding Stage 1

// In build.gradle
configurations {
    stage1
}

dependencies {
    stage1 'gg.essential:loader-stage1:+'
}

processResources {
    from(configurations.stage1) {
        into 'gg/essential/loader/stage0'
        rename { 'stage1.jar' }
    }
}

​

Local Testing

# Test Stage 0 discovery in development environment
./gradlew runClient \
    -Pessential.loader.stage0.debug=true

​

See Also

• Stage 1 API - Configuration and update management
• Stage 2 API - Chain-loading and mod installation
• Integration Guides - Platform-specific setup