Mixins

Mixins are a feature which allow for the modification of existing Java classes with altered functionality or access, allowing for unique and customized behavior, even though the target class is already compiled. This tutorial will walk you through the process of making a Mixin with PickHaxe.

In Minecraft modding, mixins allow for the modification or extension of vanilla classes without modifying the physical JAR file. In many cases, certain mixins can be made compatible with each other, which would be impossible with the original method of making coremods.

You can find the full documentation for Mixins on the SpongePowered wiki. This documentation is essential to understanding how to develop mixins.

Mixins in PickHaxe

PickHaxe is notable in its implementation of mixins, in that it provides additional utilities via compile-time macros to make things easier for you when developing them.

Getting Started

Start by adding the following to your project.xml file.

  <mod-mixin
    package="com.example.mymodid.mixin">
    <class environment="CLIENT" value="PistonStructureResolverMixin" />
        <class environment="*" value="PistonStructureResolverMixin" />
  </mod-mixin>

You can use multiple <class> tags to define multiple mixin class files, and multiple <mod-mixin> tags to define multiple mixins.

Then, you can create the corresponding file:

// src/com/example/mymodid/mixin/PlayerRendererMixin.hx
package com.example.mymodid.mixin;

import net.pickhaxe.core.Mixin;

@:mixin({
	target: net.minecraft.client.renderer.entity.player.PlayerRenderer,
})
abstract class PlayerRendererMixin implements Mixin {}

Note that the Mixin target must be an abstract class, and it must implement net.pickhaxe.core.Mixin, otherwise the annotations will not function.

In standard Mixin development, the next step would be to dig into documentation to determine the appropriate superclass type. However, PickHaxe provides functionality to automatically calcuate the appropriate superclass when a Mixin class is missing it, and display it at build time:

./src/com/example/mymodid/mixin/PlayerRendererMixin.hx:14: character 1 : Warning : Mixin PlayerRendererMixin should have a superclass:
./src/com/example/mymodid/mixin/PlayerRendererMixin.hx:14: character 1 : net.minecraft.client.renderer.entity.LivingEntityRenderer<net.minecraft.client.player.AbstractClientPlayer, net.minecraft.client.model.PlayerModel<net.minecraft.client.player.AbstractClientPlayer>>

You can then copy-paste the second line into your mixin class:

// src/com/example/mymodid/mixin/PlayerRendererMixin.hx
package com.example.mymodid.mixin;

import net.pickhaxe.core.Mixin;

@:mixin({
	target: net.minecraft.client.renderer.entity.player.PlayerRenderer,
})
abstract class PlayerRendererMixin implements Mixin extends net.minecraft.client.renderer.entity.LivingEntityRenderer<net.minecraft.client.player.AbstractClientPlayer, net.minecraft.client.model.PlayerModel<net.minecraft.client.player.AbstractClientPlayer>> {}

The next step would be to determine the superconstructor to call, but PickHaxe has you covered there too. PickHaxe will inject the generated constructor into the mixin class automatically; tyou can turn this off by providing a constructor yourself or adding the parameter autoConstructor: false to the mixin metadata.

./src/com/example/mymodid/mixin/PlayerRendererMixin.hx:14: character 1 : Mixin PlayerRendererMixin should have a constructor, automatically adding one...