lillero/README.md

Lillero

Lillero is a lightweight and simple Java ASM patching framework built on top of ObjectWeb's ASM library.

How

This library provides the core interface, IInjector, as well as a small set of utils to make your life easier. All patches should implement IInjector and be declared as services.

Some methods must be implemented, specifying which class and method will be patched:

• targetClass(): returns the fully qualified name of the class to patch (example: net.minecraft.client.Minecraft).
• methodName(): returns the name of the method to patch.
• methodDesc(): returns descriptor (arguments and return type) of method to patch.
• inject(ClassNode, MethodNode): will be invoked providing you the ClassNode and MethodNode you requested. This is where the actual patching will happen.

There's some more optional methods you don't have to implement, but really should because they will make your life considerably easier when it's time to debug:

• name() : returns patch name
• reason() : returns patch description

Finally, you should mark your classes as service providers, by creating a text file called ftbsc.lll.IInjector in src/main/resources/META-INF/services on your project. Inside, put the fully qualified names of your patches (example: ftbsc.bscv.asm.patches.TestPatch$TickPatch).

If you use Gradle (you do) don't forget to add this library as a dependency in your build.gradle:

repositories {
	maven { url = 'https://maven.fantabos.co' }
}
dependencies {
    implementation 'ftbsc:lll:<whatever the latest version is>'
}

You are going to need an appropriate loader to use Lillero patches: this is just a library and does nothing by itself. You need to make it work by loading services implementing the IInjector interface, and by calling their inject(ClassNode, MethodNode) methods with the appropriate parameters.

Tips specific to Minecraft patching

• Use Searge names in every place you are told to use a name.
  • Use MCP (AKA unobfuscated) names if you are running from ForgeGradle's runClient task.
• Use our loader that hooks into Forge's ModLauncher if you're writing a Forge mod.
• Spare yourself some trouble, and use this annotation processor to reduce boilerplate.
• Make sure to dunk on all the naysayers who tried to force you to use Mixin!

Example Minecraft patch

The following is an example patch, located at src/main/java/example/patches/SamplePatch.java:

  package example.patches;
  import ftbsc.lll.IInjector;
  public class SamplePatch implements IInjector {
    public String name()        { return "SamplePatch"; }
    public String targetClass() { return "net.minecraft.client.Minecraft"; }
    public String methodName()  { return "func_71407_l"; } // tick()
    public String methodDesc()  { return "()V"; }
    public void inject(ClassNode clazz, MethodNode main) {
      InsnList insnList = new InsnList();
      insnList.add(new InsnNode(POP));
      main.instructions.insert(insnList);
    }
  }

When loaded into Minecraft, this patch will crash the game with a NegativeArraySizeException as soon as it's done loading - so you know it's working.

The following is the service registration file, located at src/main/resources/META-INF/services/ftbsc.lll.IInjector:

  example.patches.SamplePatch

Happy patching! And remember...

"Don't do coremods!"