Plugin Mixins

Mixins can be used to modify classes at runtime before they are loaded. You can use them in plugins if you want to optimize a part of the game specifically for your server - without having to fork Sponge. The modifications will be bundled directly with your plugin and are only active as long as the plugin is loaded.

See also

Mixin documentation

Mixin documentation including an introduction to Mixins.

Example plugin

Example plugin which uses Plugin Mixins to print a message when the server is starting.

Setup

1. Add the Mixin library as dependency to your plugin:

   dependencies {
       compile 'org.spongepowered:mixin:0.7.11-SNAPSHOT'
   }
   

2. Add a new Mixin configuration for your plugin, e.g. mixins.myplugin.json inside your resource folder:

   {
       "required": true,
       "minVersion": "0.7.10",
       "package": "com.example.myplugin.mixin",
       "refmap": "mixins.myplugin.refmap.json",
       "target": "@env(DEFAULT)",
       "compatibilityLevel": "JAVA_8",
       "mixins": [
           "MixinMinecraftServer"
       ]
   }
   

3. Add a Mixin class to the specified package:

   package com.example.myplugin.mixin;
   
   import net.minecraft.server.MinecraftServer;
   import org.spongepowered.asm.mixin.Mixin;
   
   @Mixin(MinecraftServer.class)
   public abstract class MixinMinecraftServer {
   
   }
   

Debugging

Normally, the Mixin configuration is registered inside JAR manifest of the plugin. Since the plugin is not packaged in a JAR while debugging inside the IDE you need specify the Mixins to apply as command line options:

1. Add a --mixin <mixin config file name> option for each Mixin configuration file to the program arguments of your run configuration:

   --mixin mixins.myplugin.json
   

Production

If your Mixin is working in your development environment you still need to make some changes to make it work in production:

1. Apply the MixinGradle plugin to your build script:

   buildscript {
       repositories {
           maven {
               name = 'sponge'
               url = 'https://repo.spongepowered.org/maven'
           }
       }
       dependencies {
           classpath 'org.spongepowered:mixingradle:0.6-SNAPSHOT'
       }
   }
   
   apply plugin: 'org.spongepowered.mixin'
   

2. Set the refmap from your Mixin configuration:

   sourceSets {
       main {
           ext.refMap = "mixins.myplugin.refmap.json"
       }
   }
   

3. Add your Mixin configuration to the JAR manifest. The FMLCorePluginContainsFMLMod manifest entry is necessary if you want to load your Mixin on SpongeForge:

   jar {
       manifest.attributes(
           'TweakClass': 'org.spongepowered.asm.launch.MixinTweaker',
           'MixinConfigs': 'mixins.myplugin.json',
           'FMLCorePluginContainsFMLMod': 'true',
       )
   }
   

4. Make sure to re-build the plugin using Gradle. The Mixin should then get applied by SpongeVanilla and SpongeForge.

   gradle clean build