MixinBooter Mod (1.12.2) – Library for Rongmario’s Mods

Overview#

MixinBooter is a foundational library mod designed to facilitate the use of Mixins—a powerful trait-based bytecode manipulation framework—within the Minecraft ecosystem. Originally developed to support Rongmario's suite of modifications, it has evolved into a standard utility for the legacy modding community.

The mod's primary purpose is to solve the "early loading" problem. In standard Forge environments, many classes are loaded before traditional mods can intervene. MixinBooter provides a standardized way to inject code into these early-game classes (such as those in Vanilla Minecraft, Forge, or other libraries) without requiring every mod to implement its own complex coremod logic. By providing a unified Mixin environment, it prevents version mismatches and crashes that occur when multiple mods attempt to bundle different versions of the Mixin library.

Technical Specifications#

MixinBooter is built upon a specialized fork of the Mixin library to ensure maximum stability in older Minecraft versions.

Core Components

UniMix: The mod utilizes UniMix (currently version 0.15.3), a fork maintained by CleanroomMC. This version is derived from the Mixin 0.8.7 branch, providing modern features to legacy versions of the game.
Cross-Version Support: A unique feature of MixinBooter is its single-build architecture. The same JAR file is compatible across all versions from Minecraft, simplifying installation for users and dependency management for developers.

Mechanics and Loading Paths#

MixinBooter categorizes code injections into two distinct paths based on when the target classes are loaded by the game. Understanding these paths is essential for proper mod functionality.

Loading Path	Target Classes	Implementation Interface
Early Loading	Vanilla Minecraft, Forge, Guava, and other core libraries.	`IEarlyMixinLoader`
Late Loading	Standard mod classes and late-initialized game components.	`ILateMixinLoader`

Early Mixin Loading

This path is used for modifications that must occur before the game fully initializes. Developers implementing this must create a coremod using IFMLLoadingPlugin and implement the IEarlyMixinLoader interface. This ensures that the Mixins are applied as soon as the classloader encounters the target classes.

Late Mixin Loading

This is the standard path for most mod-to-mod interactions. It allows a mod to inject code into another mod's classes. By implementing ILateMixinLoader, a mod can register its Mixin configurations to be applied after all mods have been identified but before they are fully initialized.

Configuration and Properties#

MixinBooter utilizes a JSON-based configuration system to define how Mixins are applied. These configurations are typically found in a mod's resources as a .json file.

Mixin Configuration Properties

Property	Type	Description
`package`	String	Required. The root package where the Mixin classes reside.
`refmap`	String	Required. The filename of the refmap used for obfuscation mapping.
`parent`	String	Optional. Defines a parent configuration to inherit settings from.
`required`	Boolean	If true, the game will hard crash if the Mixins fail to apply.
`plugin`	String	Path to an `IMixinConfigPlugin` for logic-based application.
`target`	String	Defines the target environment (e.g., `@env(DEFAULT)`).
`conformVisibility`	Boolean	Whether overwrites should conform to the original method's visibility.
`requireAnnotations`	Boolean	If true, requires the `@Overwrite` annotation for all method replacements.

Injector Options

Within the configuration, developers can fine-tune the behavior of code injections:

defaultRequire: The number of times an injection must succeed before it is considered successful (default is 0).
maxShiftBy: The maximum number of opcodes an injection point can shift to find a valid target (default is 0, max is 5).

Developer Integration#

For mod developers, MixinBooter is integrated via Maven. It supports both standard ForgeGradle and the modern RetroFuturaGradle toolchains.

Dependency Setup

Developers must add the CleanroomMC repository and include the following dependencies in their build.gradle file:

repositories {
 maven { url 'https://maven.cleanroommc.com' }
}

dependencies {
 // Common Annotation Processors
 annotationProcessor 'org.ow2.asm:asm-debug-all:5.2'
 annotationProcessor 'com.google.guava:guava:32.1.2-jre'
 annotationProcessor 'com.google.code.gson:gson:2.8.9'

 // MixinBooter Implementation
 implementation ('zone.rong:mixinbooter:10.7') { transitive = false }
 annotationProcessor ('zone.rong:mixinbooter:10.7') { transitive = false }
}

Implementation Example

To register Mixin configurations, a developer must return a list of config paths through the getMixinConfigs method in their loader class:

public class MyModMixinLoader implements ILateMixinLoader {
 @Override
 public List<String> getMixinConfigs {
 return Arrays.asList("mixins.mymod.json");
 }
}

Compatibility and Optimization#

MixinBooter includes several built-in compatibility fixes to ensure a stable gameplay experience when using multiple high-profile mods.

Log Readability: MixinBooter includes enhancements to the game's logging system, making it easier for users and developers to identify which specific Mixin caused a crash by providing more detailed bytecode traces.