Introduction to Mixin Configuration Management

If you have already used Mixin on legacy versions of Minecraft through classical shading techniques, you are probably accustomed to creating your own coremod and using Mixins#addConfiguration as a way to register your mixin configuration. In such case, it's about time to ditch that habit once and for all - for our framework provides more reliable, flexible and aesthetical solution for dealing with all your mixin configurations!

The Fast and Easy

Should you just want to get things done with least effort and learning, the simplest path would be to add forceLoadAtStage entry to your mixin configuration, specifying which stage you want that configuration to be loaded. Suppose you start with normal average .json configuration such as the one below:

{
  "required": true,
  "verbose": true,
  "package": "com.randomdude.supermod.mixins",
  "mixins": [
    "MixinEntityPlayer",
    "MixinWorld"
  ],
  "server": [],
  "client": [],
  "compatibilityLevel": "JAVA_8",
  "minVersion": "0.7.11",
  "refmap": "supermod.refmap.json"
}

All you do is just add a new entry to this .json:

{
  "required": true,
  "verbose": true,
  "package": "com.randomdude.supermod.mixins",
  "mixins": [
    "MixinEntityPlayer",
    "MixinWorld"
  ],
  "server": [],
  "client": [],
  "compatibilityLevel": "JAVA_8",
  "minVersion": "0.7.11",
  "refmap": "supermod.refmap.json",
  "forceLoadAtStage": "CORELOAD"
}

And that's it! With this little change, the Grimoire will automatically recognize and register your mixin configuration at startup, without you needing to make a dedicated coremod for that purpose and shade full Mixin implementation into your mod's jar. Regarding what you can specify as value for this forceLoadAtStage entry, there basically are two options:

• CORELOAD - will make sure mixins in your configurations are loaded at appropriate time to target Minecraft/Forge classes, or classes from mods which ship their own coremod;
• MODLOAD - will allow mixins in your configuration to target classes from other mods, but not Minecraft/Forge.

If you have the need to target both types of classes, you would simply create two different mixin configurations - one with mixins targetting Minecraft/Forge, another with mixins aimed at other mods.

The Less Fast, But Cooler

While the path above is indeed fast and easy, suppose you're not satisfied with how little flexibility it does provide. Suppose you want to load your mixin configuration only if certain conditions check out, which you verify at runtime; or you have some business to do at coremod loading stage anyways, even though it's not a normal coremod business. I such case worry not, we got you covered! With Grimmix Controller™️ you can manage loading of your configurations at runtime, build them at runtime instead of creating a regular .json, communicate with other controllers, and execute arbitrary code at predefined points in time during game startup.

Creating your own controller is really not that complicated. You simply reserve a dedicated class to serve as one, make it extend GrimmixController from Grimoire's API package, and annotate it with @Grimmix annotation. What you will end up with in the end will look something like this:

@Grimmix(id = "supermodgrimmix", name = "Supermod Grimmix", version = "1.0.0")
public class SupermodGrimmix extends GrimmixController {
	// Nothing here yet...
}

See? I told ya, it's not that complicated! Now Grimoire will automatically find and instantiate this controller during the startup, wherever it is. Of all values in the @Grimmix annotation the only mandatory one is id, which uniquely identifies your controller among others. Other ones are optional and serve only for the purposes of logging or helping other controllers establish the identity of your one, should they want to do that for some reason.

Of course, we're not done yet, as insofar all our newborn controller does is stand there not getting any work done. Suppose we want to make it load one of our mixin configurations. In such case we once again have to decide at which stage that configuration should be loaded - core loading or mod loading, as there are two methods in the GrimmixController class that we can override for that purpose - GrimmixController#coreLoad and GrimmixController#modLoad respectively. They both receive their own subclass of IConfigRegistryEvent, which we will use to register our configuration by invoking the IConfigRegistryEvent#registerConfiguration method.

What we will end up having in the end will look something like this:

@Grimmix(id = "supemodgrimmix", name = "Supermod Grimmix", version = "1.0.0")
public class SupermodGrimmix extends GrimmixController {

	@Override
	public void coreLoad(ICoreLoadEvent event) {
		event.registerConfiguration("supermod.mixins.json");
	}
	
}

Still nothing complicated, right? But just you wait, we can make things even simpler for you! During it's initialization phase, not only Grimoire looks out for GrimmixControllers in your jar, but it will also keep track of everything that convincingly looks like mixin .json configuration. It will not load those configurations unless they have forceLoadAtStage entry we talked about earlier, but it will keep track of them and allow you to load those configurations through your grimmix yourself. To do that we will invoke IConfigRegistryEvent#registerConfigurationCandidates method, like this:

@Override
public void coreLoad(ICoreLoadEvent event) {
	event.registerConfigurationCandidates();
}

Alternatively, you can use a version of that method which accepts Predicate<String> as argument, if you need to determine which configurations get loaded on case-by-case basis.

Epilogue

This more or less concludes our brief introduction into how to load mixin configurations with the help of Grimoire. The possibilities are of course much more numerous, and what is presented above are just the simplest examples - more advanced matters will be covered in more advanced article (which is yet to be written).

A question might have been brewing in your head for a while by now - "But... can I, like, just do things the old way? Mixins#addConfiguration, that sorta stuff?..". The answer is: no, no you can't. If you want to use our API and toolstack, you really shouldn't try to do that, as it completely ignores nice and soft API layer Grimoire so conveniently places between you and Mixin, stripping you and other users of our framework of crucial part of it's functionality. The reasoning behind why an API is structured in such a way ultimately deserves it's own more advanced article, which when written will be linked here.