Mixin

https://github.com/spongepowered/mixin
Admin
Mixin is a trait/mixin framework for Java using ASM and hooking into the runtime classloading...
Tokens:62,232
Snippets:336
Trust Score:9.8
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Method signature notation

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Shows the signature of the example method in a compact notation.

```text
(double,int,int,int,boolean)com.mypackage.ThingType
```

--------------------------------

### Complete Gradle mixin closure example

Source: https://github.com/spongepowered/mixin/wiki/Mixins-on-Minecraft-Forge

Complete example of a Gradle 'mixin' closure configuring refmaps, configs, debug options, and annotation processor settings. Includes 'add' for refmaps, 'config' for mixin configs, debug flags, and 'quiet'.

```groovy
mixin {
    // Refmaps for each SourceSet
    add sourceSets.main, 'mixins.mymod.refmap.json'

    // Configs to add to runs and jars
    config 'mixins.mymod.json'

    // Specify options for dev run configs
    debug.verbose = true
    debug.export = true
    dumpTargetOnFailure = true

    // Options for the Annotation Processor
    quiet
}
```

--------------------------------

### Bytecode descriptor for method signature

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Shows the bytecode descriptor equivalent of the example method signature.

```text
(DIIIZ)Lcom/mypackage/ThingType;
```

--------------------------------

### Java method signature example

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Shows a Java method declaration used to illustrate a method signature.

```java
public ThingType getThingAtLocation(double scale, int x, int y, int z, boolean squash) {
```

--------------------------------

### Target method setPos with arguments

Source: https://github.com/spongepowered/mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors

Example target method that sets a position. It takes two integer arguments and is used to demonstrate how to pass arguments to a handler method.

```java
/**
 * A target method, setPos
 */
public void setPos(int x, int y) {
    Point p = new Point(x, y);
    this.position = p;
    this.update();
}
```

--------------------------------

### Basic mixin extension closure

Source: https://github.com/spongepowered/mixin/wiki/Mixins-on-Minecraft-Forge

Starts the MixinGradle configuration by declaring the 'mixin' extension with an empty closure. This is typically placed after sourceSets or dependencies blocks.

```groovy
mixin {
    // MixinGradle Settings
}
```

--------------------------------

### Soft implementation of accessor with @Shadow and @Implements

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Overwriting-Methods

Converts an accessor to a soft implementation using @Implements with prefix 'id$'. The method id$getID() calls the shadowed original getID(). This setup causes a conflict after merging and self-referential recursion if called.

```java
@Mixin(Foo.class)
@Implements(@Interface(iface = Indentifyable.class, prefix = "id$"))
public abstract class MixinFoo {

    @Shadow
    public abstract int getID();

    /**
     * This method will become our intrinsic proxy method, it
     * calls the original (shadowed) version of the accessor.
     */
    public int id$getID() {
        // Call original accessor
        return this.getID();
    }
}
```

--------------------------------

### Enable debug.verbose and debug.export

Source: https://github.com/spongepowered/mixin/wiki/Mixins-on-Minecraft-Forge

Recommended development settings that set the 'mixin.debug.verbose' and 'mixin.debug.export' system properties. Remember to regenerate runs after changing these settings.

```groovy
mixin {
    // MixinGradle Settings
    add sourceSets.main, 'mixins.mymod.refmap.json'
    config 'mixins.mymod.json'

    debug.verbose = true
    debug.export = true
}
```

--------------------------------

### Configure refmaps and configs for additional SourceSets

Source: https://github.com/spongepowered/mixin/wiki/Mixins-on-Minecraft-Forge

Adds separate refmap names and config entries for 'main', 'client', and 'api' SourceSets. Each SourceSet requires its own refmap because the AP runs separately for each compile task.

```groovy
mixin {
    add sourceSets.main, 'mixins.mymod.refmap.json'
    add sourceSets.client, 'mixins.mymod.client.refmap.json'
    add sourceSets.api, 'mixins.mymod.api.refmap.json'

    config 'mixins.mymod.json'
    config 'mixins.mymod.client.json'
    config 'mixins.mymod.api.json'
}
```

--------------------------------

### Use the default shadow$ prefix for a shadow method

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Resolving-Method-Signature-Conflicts

Mixin provides a default prefix 'shadow$' that can be used without explicitly defining the prefix. However, it is recommended to always define the prefix explicitly for readability.

```java
@Shadow
public abstract int shadow$getID();
```

--------------------------------

### Handler method onSetPos with arguments and CallbackInfo

Source: https://github.com/spongepowered/mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors

Handler method for setPos that consumes the target's arguments (x, y) before the CallbackInfo parameter. It checks if the position is the origin and calls a helper method. The CallbackInfo argument is still required.

```java
/**
 * Handler method, onSetPos. Note the two int variables x and y
 * which appear before the callbackinfo
 */
@Inject(method = "setPos", at = @At("HEAD"))
protected void onSetPos(int x, int y, CallbackInfo ci) {
    System.out.printf("Position is being set to (%d, %d)\n", x, y);
}
```

--------------------------------

### MyTokenProvider implements ITokenProvider

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Overwriting-Methods

A token provider that returns the application build number for the token 'BUILD' and null for other tokens. Register an instance during Mixin bootstrapping.

```java
public class MyTokenProvider implements ITokenProvider {
    public Integer getToken(String token) {
        if ("BUILD".equals(token)) {
            return TargetApplication.getInstance().getBuildNumber();
        }
        return null;
    }
}
```

--------------------------------

### @Overwrite with constraints = "BUILD(1234)"

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Overwriting-Methods

Defines an overwrite with a constraint that the BUILD token must be defined and equal to 1234. If not met, the mixin processor raises an error and crashes the application.

```java
@Overwrite(constraints = "BUILD(1234)")
public void someHackyOverwrite(int x, int y) {
    // do hacky things
}
```

--------------------------------

### Add MixinGradle plugin to build.gradle

Source: https://github.com/spongepowered/mixin/wiki/Mixins-on-Minecraft-Forge

Add the MixinGradle plugin to the plugins block in build.gradle. The first line is the plugin to add, and the second shows the complete plugins block after adding it.

```groovy
id 'org.spongepowered.mixin' version '0.7.+'
```

```groovy
plugins {
    id 'eclipse'
    id 'maven-publish'
    id 'net.minecraftforge.gradle' version '5.1.+'
    id 'org.spongepowered.mixin' version '0.7.+'
}
```

--------------------------------

### Copy a method with ASM in 8 lines

Source: https://github.com/spongepowered/mixin/wiki/Flippin'-Mixins,-how-do-they-work?

Shows the minimal ASM code to copy a method named "foo" from one class to another. This is the core principle of Mixin: merging bytecode. It is intentionally simplistic and does not check for conflicts or validity, which is why Mixin adds complexity.

```java
ClassNode source = new ClassNode();
ClassNode dest = new ClassNode();
new ClassReader(sourceBytes).accept(source);
new ClassReader(destBytes).accept(dest);
source.methods.stream().filter(m -> m.name.equals("foo")).forEach(dest.methods::add);
ClassWriter cw = new ClassWriter(0);
dest.accept(cw);
return cw.toByteArray();
```

--------------------------------

### Basic @Inject handler method with CallbackInfo

Source: https://github.com/spongepowered/mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors

A minimal handler method for the update() method, injected at HEAD. The handler receives a CallbackInfo parameter and calls a custom method. This is the simplified version; real handlers must accept CallbackInfo.

```java
@Inject(method = "update", at = @At("HEAD"))
protected void onUpdate(CallbackInfo ci) {
    Observer.instance.foo(this);
}
```

--------------------------------

### Inject at first RETURN opcode using ordinal

Source: https://github.com/spongepowered/mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors

Use this injector to place a callback only before the first RETURN opcode in the target method. The ordinal value of 0 in the @At annotation selects the first match. This is useful when a method has multiple return points and you need to target the initial one.

```java
@Inject(method = "setPos", at = @At(value = "RETURN", ordinal = 0))
protected void onResetPos(int x, int y, CallbackInfo ci) {
    // handler logic
}
```

--------------------------------

### Add refmap and config to mixin closure

Source: https://github.com/spongepowered/mixin/wiki/Mixins-on-Minecraft-Forge

Adds the refmap filename for the 'main' SourceSet with 'add sourceSets.main' and registers the mixin config with 'config'. The refmap name must match the refmap specified in the config JSON.

```groovy
mixin {
    // MixinGradle Settings
    add sourceSets.main, 'mixins.mymod.refmap.json'
    config 'mixins.mymod.json'
}
```

--------------------------------

### @Overwrite with offset constraint BUILD(1230+10)

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Overwriting-Methods

Allows any value between 1230 and 1240 (inclusive) for the BUILD token, equivalent to the range form.

```java
@Overwrite(constraints = "BUILD(1230+10)")
```

--------------------------------

### Wildcard Constructor Injection with @Inject

Source: https://github.com/spongepowered/mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors

Injects a callback into all constructors of a class by using a wildcard in the method name. The injection point is RETURN, and the handler takes a CallbackInfo parameter. This is useful for observer-type injections across overloaded constructors.

```java
@Inject(method = "<init>*", at = @At("RETURN"))
private void onConstructed(CallbackInfo ci) {
    // do initialisation stuff
}
```

--------------------------------

### Provide method implementation in mixin

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Adds an implementation of setLevel() to the mixin to avoid AbstractMethodError at runtime. The method is patched into the target class when the mixin is applied.

```java
@Mixin(EntityPlayer.class)
public abstract class MixinEntityPlayer
    extends Entity
    implements LivingThing, Leveller {

    @Override
    public void setLevel(int newLevel) {
        // TODO implement this method
    }
}
```

--------------------------------

### Define a shadow method with a custom prefix to avoid signature conflict

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Resolving-Method-Signature-Conflicts

Use @Shadow(prefix = "conflict$") to rename the shadow method and avoid a signature conflict with an interface method. The prefix is defined directly in the annotation.

```java
public abstract class MixinFoo implements Identifyable {

    @Shadow(prefix = "conflict$")
    public abstract int conflict$getID();

    public UUID getID() {
        // return the unique ID
    }
}
```

--------------------------------

### @Overwrite with range constraint BUILD(1230-1240)

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Overwriting-Methods

Allows any value between 1230 and 1240 (inclusive) for the BUILD token.

```java
@Overwrite(constraints = "BUILD(1230-1240)")
```

--------------------------------

### Soft Implementing an Interface with @Implements and @Interface

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Resolving-Method-Signature-Conflicts

Declares a soft implementation by annotating a mixin with `@Implements` and specifying an interface and prefix. The prefixed method `ident$getID` is used to implement `Indentifyable.getId`. Prefixes should end with `$` for readability and evoke the interface name for clarity.

```java
@Mixin(Bar.class)
@Implements(@Interface(iface = Indentifyable.class, prefix = "ident$"))
public abstract class MixinBar extends Foo {

    private final UUID id = UUID.randomUUID();

    public UUID ident$getID() {
        return this.id;
    }
}
```

--------------------------------

### Inject at RETURN with CallbackInfoReturnable

Source: https://github.com/spongepowered/mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors

Use this injector to intercept a method's return value and provide a fallback when it is null. The handler receives a CallbackInfoReturnable<Point> and calls setReturnValue to override the result. This works with any injection point, but is especially useful at RETURN to capture the actual return value.

```java
@Inject(method = "getPos", at = @At("RETURN"), cancellable = true)
protected void onGetPos(CallbackInfoReturnable<Point> cir) {
    // Check the captured return value
    if (cir.getReturnValue() == null) {
        // if it's null, set our fallback value as the return
        cir.setReturnValue(Point.ORIGIN);
    }
}
```

--------------------------------

### Add Mixin AP to additional SourceSets

Source: https://github.com/spongepowered/mixin/wiki/Mixins-on-Minecraft-Forge

Add the Mixin AP dependency to additional SourceSets (client and api) using their corresponding configuration names (clientAnnotationProcessor and apiAnnotationProcessor). Each SourceSet containing mixins requires its own Reference Map and the AP dependency.

```groovy
dependencies {
    // Specify the version of Minecraft to use. If this is any group other than 'net.minecraft', it is assumed
    // that the dep is a ForgeGradle 'patcher' dependency, and its patches will be applied.
    // The userdev artifact is a special name and will get all sorts of transformations applied to it.
    minecraft 'net.minecraftforge:forge:1.17.1-37.0.70'

    annotationProcessor 'org.spongepowered:mixin:0.8.5:processor'
    clientAnnotationProcessor 'org.spongepowered:mixin:0.8.5:processor'
    apiAnnotationProcessor 'org.spongepowered:mixin:0.8.5:processor'
}
```

--------------------------------

### ITokenProvider.getToken

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Overwriting-Methods

Interface method for a token provider that returns an integer value for a given token string, or null if the token is not supported.

```APIDOC
## ITokenProvider.getToken

### Description
Returns the integer value associated with the given token string, or null if the token is not supported by this provider.

### Method
`Integer getToken(String token)`

### Parameters
- **token** (String) - Required - The token string to look up.

### Returns
- **Integer** - The value for the token, or null if not supported.

### Example
java
public class MyTokenProvider implements ITokenProvider {
    public Integer getToken(String token) {
        if ("BUILD".equals(token)) {
            return TargetApplication.getInstance().getBuildNumber();
        }
        return null;
    }
}

```

--------------------------------

### Cancellable injection with @Inject cancellable flag

Source: https://github.com/spongepowered/mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors

Use this snippet to create a cancellable injection that can prematurely return from the target method. Set the 'cancellable' flag to true in the @Inject annotation and call ci.cancel() to trigger an immediate return after the injection. Calling cancel() on a non-cancellable CallbackInfo raises an exception.

```java
/**
 * Cancellable injection, note that we set the "cancellable"
 * flag to "true" in the injector annotation
 */
@Inject(method = "setPos", at = @At("HEAD"), cancellable = true)
protected void onSetPos(int x, int y, CallbackInfo ci) {
    // Check whether setting position to origin and do some custom logic
    if (x == 0 && y == 0) {
        // Some custom logic
        this.position = Point.ORIGIN;
        this.handleOriginPosition();
        
        // Call update() just like the original method would have
        this.update();
        
        // Mark the callback as cancelled
        ci.cancel();
    }
    
    // Execution proceeds as normal at this point, no custom handling
}
```

--------------------------------

### Apply interface to target class with @Mixin

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Declares a mixin class that targets EntityPlayer and implements the LivingThing interface. When applied, the target class will implement LivingThing, enabling duck typing.

```java
@Mixin(EntityPlayer.class)
public abstract class MixinEntityPlayer
    extends Entity
    implements LivingThing {
}
```

--------------------------------

### Use duck typing after mixin application

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Shows how the applied mixin enables casting an EntityPlayer to LivingThing and calling interface methods like getHealth(). The cast succeeds only after the mixin is applied.

```java
public void method() {
    EntityPlayer player = new EntityPlayer();

    // With the mixin applied, this cast succeeds
    LivingThing living = (LivingThing)player;

    // And because the cast succeeded, we can pass our object
    // to other things that require a reference to LivingThing
    // such as the method below
    if (this.isAlive(living)) {
        // hooray
    }
}

public boolean isAlive(LivingThing living) {
    // We can call getHealth() just fine, because the method
    // exists and is accessible via the LivingThing interface
    int health = living.getHealth();
    return health > 0;
} 
```

--------------------------------

### @Overwrite constraints

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Overwriting-Methods

Defines constraints on an @Overwrite method using a constraint string that specifies required token values.

```APIDOC
## @Overwrite constraints

### Description
Specifies constraints on an @Overwrite method. The constraint string defines required token values that must be present in the environment for the overwrite to be applied.

### Usage
Add a `constraints` attribute to the `@Overwrite` annotation.

### Parameters
- **constraints** (String) - Required - A constraint string following the syntax described below.

### Constraint Syntax
- `()` - Token must be present, any value.
- `(1234)` - Token must be exactly 1234.
- `(1234+)`, `(1234-)`, `(1234>)` - Token must be 1234 or greater.
- `(<1234)` - Token must be less than 1234.
- `(<=1234)` - Token must be less than or equal to 1234.
- `(>1234)` - Token must be greater than 1234.
- `(>=1234)` - Token must be greater than or equal to 1234.
- `(1234-1300)` - Token must be between 1234 and 1300 inclusive.
- `(1234+10)` - Token must be between 1234 and 1244 inclusive.

### Example
java
@Overwrite(constraints = "BUILD(1234)")
public void someHackyOverwrite(int x, int y) {
    // do hacky things
}

```

--------------------------------

### Mixin config JSON: injectors block with defaultRequire

Source: https://github.com/spongepowered/mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors

Configuration snippet for a mixin config file that sets a global default for `require` across all mixins in the config. The `injectors` block contains `defaultRequire` set to 1.

```json
{
   "injectors": {
        "defaultRequire": 1
    }
}
```

--------------------------------

### Declare a mixin class with @Mixin(EntityPlayer.class)

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Declares a mixin class targeting EntityPlayer using the @Mixin annotation. The class is abstract and extends Entity, and the annotation specifies the target class to apply the mixin to.

```java
@Mixin(EntityPlayer.class)
public abstract class MixinEntityPlayer
    extends Entity {
}
```

--------------------------------

### Configure Mixin AP options in Gradle mixin closure

Source: https://github.com/spongepowered/mixin/wiki/Mixins-on-Minecraft-Forge

Configures Mixin annotation processor options in a Gradle build. Disables the target validator, sets the overwrite error level to 'error', suppresses AP output with 'quiet', and feeds an additional custom TSRG mapping file.

```groovy
mixin {
    // AP Settings
    disableTargetValidator = true
    overwriteErrorLevel = 'error'
    quiet
    extraMappings file("my_custom_srgs.tsrg")
}    
```

--------------------------------

### Intrinsic proxy with @Intrinsic(displace = true)

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Overwriting-Methods

Adds the @Intrinsic(displace = true) annotation to the proxy method to avoid re-entrance. If the intrinsic counterpart exists, it is renamed and references updated; otherwise the proxy is added normally.

```java
    /**
     * This method will become our intrinsic proxy method, it
     * calls the original (shadowed) version of the accessor.
     * It uses the displace parameter to avoid re-entrance when
     * the method would otherwise be overwritten.
     */
    @Intrinsic(displace = true)
    public int id$getID() {
        // Call original accessor
        return this.getID();
    }
```

--------------------------------

### Add Mixin AP dependency to main dependencies block

Source: https://github.com/spongepowered/mixin/wiki/Mixins-on-Minecraft-Forge

Add the Mixin annotation processor dependency to the main dependencies block. The AP dependency uses the classifier 'processor' and should be the same version or newer than the Mixin version used in the project.

```groovy
dependencies {
    // Specify the version of Minecraft to use. If this is any group other than 'net.minecraft', it is assumed
    // that the dep is a ForgeGradle 'patcher' dependency, and its patches will be applied.
    // The userdev artifact is a special name and will get all sorts of transformations applied to it.
    minecraft 'net.minecraftforge:forge:1.17.1-37.0.70'

    // Apply Mixin AP
    annotationProcessor 'org.spongepowered:mixin:0.8.5:processor'
}
```

--------------------------------

### Define the Identifyable interface with getID()

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Resolving-Method-Signature-Conflicts

Defines the Identifyable interface with a getID() method returning a UUID. This interface is intended to be mixed into target classes to tag objects, but conflicts when the target's superclass already has getID() with a different return type.

```java
public interface Identifyable {

    /**
     * Get the ID for this object
     */
    public abstract UUID getID();
}
```

--------------------------------

### Using @Shadow to access a private method in a mixin

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Adds a @Shadow method 'update()' to the mixin, allowing invocation of the target class's private method. The method is declared with an empty body because it cannot be both private and abstract.

```java
@Mixin(EntityPlayer.class)
public abstract class MixinEntityPlayer
    extends Entity
    implements LivingThing, Leveller {
    
    @Shadow
    private int level;
    
    @Shadow
    private void update() {}
    
    @Override
    public void setLevel(int newLevel) {
        // Set the level value
        this.level = newLevel;
        
        // Invoke the shadowed method to update the object state
        this.update();
    }
}
```

--------------------------------

### Call unimplemented interface method (setLevel) throws AbstractMethodError

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Illustrates that even if the interface cast succeeds, calling a method not implemented by the target class throws AbstractMethodError. The comment explains that setLevel(I) is not defined in EntityPlayer or its superclasses.

```java
public void method() {
    EntityPlayer player = new EntityPlayer();

    // Assume that we can runtime-patch the interface
    // declaration onto the EntityPlayer class, allowing
    // this assignment to succeed
    Leveller lev = (Leveller)player;

    // This statement will throw an AbstractMethodError at
    // runtime because setLevel(I) is not defined in the
    // EntityPlayer class or any of its superclasses.
    lev.setLevel(10);
} 
```

--------------------------------

### Using @Overwrite annotation on a method

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Overwriting-Methods

Decorates a method with @Overwrite to connect it with its target method for obfuscation. The annotation processor looks up the target at compile time and generates an error if no mapping is found. Use for obfuscated methods; for non-obfuscated methods, simply declare the method without the annotation.

```java
    /**
     * Adding the annotation to our overwrite connects it with
     * its will-be-obfuscated target method.
     */
    @Overwrite
    public int getLevel() {
        return Math.max(this.level, 0);
    }
```

--------------------------------

### Overwrite getLevel() in MixinEntityPlayer

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Overwriting-Methods

Declares a mixin class that overwrites the getLevel() method in EntityPlayer to ensure it returns a non-negative value. The mixin extends Entity and implements LivingThing and Leveller, and uses @Shadow to access the private level field. When applied, the mixin method replaces the original getLevel() method.

```java
@Mixin(EntityPlayer.class)
public abstract class MixinEntityPlayer
    extends Entity
    implements LivingThing, Leveller {

    @Shadow
    private int level;

    /**
     * This method overwrites getLevel in the target class and
     * ensures that it returns a non-negative value.
     */
    public int getLevel() {
        return Math.max(this.level, 0);
    }

    @Override
    public void setLevel(int newLevel) {
    
        ... etc.
```

--------------------------------

### Using @Shadow to access a private field in a mixin

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Declares a @Shadow field 'level' in the mixin to access the private field of the target class EntityPlayer. The field is used in the setLevel method to assign a new value.

```java
@Mixin(EntityPlayer.class)
public abstract class MixinEntityPlayer
    extends Entity
    implements LivingThing, Leveller {
    
    @Shadow
    private int level;
    
    @Override
    public void setLevel(int newLevel) {
        // Refers to the shadow field above, but will refer
        // to the REAL field when the mixin is applied
        this.level = newLevel;
    }
}
```

--------------------------------

### Specify alias for Shadow annotation

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Obfuscation-and-Mixins

Use the aliases value on a @Shadow annotation to provide a fallback name for the target field. This is necessary when the synthetic field is stripped and recreated by the compiler, so the shadow can resolve at development time. Aliases can only be used on private fields and methods.

```java
@Shadow(aliases = {"this$0"})
private MyOuterClassType myOuter;
```

--------------------------------

### Cast to non-implemented interface (Leveller) causes ClassCastException

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Shows that casting an object to an interface it does not implement compiles but throws ClassCastException at runtime. The comment notes that the cast to Leveller will fail even though the method getLevel() could be implemented by EntityPlayer.

```java
public void method() {
    // Make a new EntityPlayer
    EntityPlayer player = new EntityPlayer();

    // This will compile, even though EntityPlayer doesn't
    // actually implement the interface, but it will throw
    // a ClassCastException at runtime
    Leveller lev = (Leveller)player;

    // We will never reach this code, but again it will
    // compile just fine.
    int level = lev.getLevel();
} 
```

--------------------------------

### Implement additional interface in mixin

Source: https://github.com/spongepowered/mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture

Extends the previous mixin to also implement the Leveller interface, which declares a method not present in the target class. The abstract modifier allows compilation without implementing the interface method.

```java
@Mixin(EntityPlayer.class)
public abstract class MixinEntityPlayer
    extends Entity
    implements LivingThing, Leveller {
}
```
Tokens:
Raw