Minecraft Forums

Make sure you download the Javadoc and documentation for ASM from
http://asm.ow2.org/

And grab the ASM bytcode plugin for eclipse http://asm.ow2.org/eclipse/index.html

You must also be familiar with JVM Bytecode

To start we need to tell forge which class will handle the bytecode manipulation by registering the *NAME* of the transformer class.

public class EDFMLLoadingPlugin implements IFMLLoadingPlugin {

@Override
public String[] getASMTransformerClass() {
//This will return the name of the class "mod.culegooner.EDClassTransformer"
return new String[]{EDClassTransformer.class.getName()};
}
}

The class that will handle the actual transformations is the class that implements IClassTransformer

public class EDClassTransformer implements IClassTransformer {

@Override
public byte[] transform(String arg0, String arg1, byte[] arg2) {
//Bytecode manipulations goes here
}

This class implements the method transform that takes 3 parameters:

public byte[] transform(String arg0, String arg1, byte[] arg2) {

with arg0 being the name of the class forge is about to work with at the JVM level
arg1 is the new name of the class (not sure what this is tbh)
arg2 you can look at it as the chuck of bytecode that's about to be loaded into JVM.

From here we check the name of arg0 and trap the one that interest us.
In this example we are interested in the net.minecraft.world.Explosion
which once it's obfuscated it's called "abq".
Note: use the files in forge/mcp/conf to see what the names are!

@Override
public byte[] transform(String arg0, String arg1, byte[] arg2) {

if (arg0.equals("abq")) {
System.out.println("********* INSIDE OBFUSCATED EXPLOSION TRANSFORMER ABOUT TO PATCH: " + arg0);
return patchClassASM(arg0, arg2, true);
}

if (arg0.equals("net.minecraft.world.Explosion")) {
System.out.println("********* INSIDE EXPLOSION TRANSFORMER ABOUT TO PATCH: " + arg0);
return patchClassASM(arg0, arg2, false);
}

return arg2;
}

Once we get to the traget class we call our own little method that does the modifications:

What we want to modfy in net.minecraft.world.Explosion is the method

public void doExplosionB(boolean par1)

buried inside this method a call to drop blocks after an explosion happens is issued.

var25.dropBlockAsItemWithChance(this.worldObj, var4, var5, var6, this.worldObj.getBlockMetadata(var4, var5, var6), 1.0F / this.explosionSize, 0);

by default the number of items dropped is dependent on the explosionSize variable.

We want to alter this to make it look like this instead:

var25.dropBlockAsItemWithChance(this.worldObj, var4, var5, var6, this.worldObj.getBlockMetadata(var4, var5, var6), 1.0F, 0);

If you install the ASM bytcode plugin for eclipse, you can see how it looks like in bytecode ASM instruction. at least the 1.0F / this.explosionSize, 0); part.

Read this as a stack:

mv.visitInsn(FCONST_1);
mv.visitVarInsn(ALOAD, 0);
mv.visitFieldInsn(GETFIELD, "net/minecraft/src/Explosion", "explosionSize", "F");
mv.visitInsn(FDIV);
mv.visitInsn(ICONST_0);
mv.visitMethodInsn(INVOKEVIRTUAL, "net/minecraft/src/Block", "dropBlockAsItemWithChance", "(Lnet/minecraft/src/World;IIIIFI)V");

So let's set it up in our patchClassASM method:
(Note: once Explosion.class is obfuscated, the name of the method doExplosionB becomes "a"

This is done in multiple steps.
First we loop over the method names until we come across our target method.

Then we loop over the instructions inside that method until we come across an instruction that interests us.

public byte[] patchClassASM(String name, byte[] bytes, boolean obfuscated) {

String targetMethodName = "";

//Our target method
if(obfuscated == true)
targetMethodName ="a";
else
targetMethodName ="doExplosionB";


//set up ASM class manipulation stuff. Consult the ASM docs for details
ClassNode classNode = new ClassNode();
ClassReader classReader = new ClassReader(bytes);
classReader.accept(classNode, 0);

//Now we loop over all of the methods declared inside the Explosion class until we get to the targetMethodName "doExplosionB"

Iterator<MethodNode> methods = classNode.methods.iterator();
while(methods.hasNext())
{
MethodNode m = methods.next();
int fdiv_index = -1;

//Check if this is doExplosionB and it's method signature is (Z)V which means that it accepts a boolean (Z) and returns a void (V)
if ((m.name.equals(targetMethodName) && m.desc.equals("(Z)V")))
{
System.out.println("********* Inside target method!");

AbstractInsnNode currentNode = null;
AbstractInsnNode targetNode = null;

@SuppressWarnings("unchecked")
Iterator<AbstractInsnNode> iter = m.instructions.iterator();

int index = -1;

//Loop over the instruction set and find the instruction FDIV which does the division of 1/explosionSize
while (iter.hasNext())
{
index++;
currentNode = iter.next();

//Found it! save the index location of instruction FDIV and the node for this instruction
if (currentNode.getOpcode() == FDIV)
{
targetNode = currentNode;
fdiv_index = index;
}
}

//now we want the save nods that load the variable explosionSize and the division instruction:

/*
mv.visitInsn(FCONST_1);
mv.visitVarInsn(ALOAD, 0);
mv.visitFieldInsn(GETFIELD, "net/minecraft/src/Explosion", "explosionSize", "F");
mv.visitInsn(FDIV);
mv.visitInsn(ICONST_0);
mv.visitMethodInsn(INVOKEVIRTUAL, "net/minecraft/src/Block", "dropBlockAsItemWithChance", "(Lnet/minecraft/src/World;IIIIFI)V");
*/

AbstractInsnNode remNode1 = m.instructions.get(fdiv_index-2); // mv.visitVarInsn(ALOAD, 0);
AbstractInsnNode remNode2 = m.instructions.get(fdiv_index-1); // mv.visitFieldInsn(GETFIELD, "net/minecraft/src/Explosion", "explosionSize", "F");
AbstractInsnNode remNode3 = m.instructions.get(fdiv_index); // mv.visitInsn(FDIV);


//just remove these nodes from the instruction set, this will prevent the instruction FCONST_1 to be divided.

m.instructions.remove(remNode1);
m.instructions.remove(remNode2);
m.instructions.remove(remNode3);


//in this section, i'll just illustrate how to inject a call to a static method if your instruction is a little more advanced than just removing a couple of instruction:

/*
To add new instructions, such as calling a static method can be done like so:

// make new instruction list
InsnList toInject = new InsnList();

//add your own instruction lists: *USE THE ASM JAVADOC AS REFERENCE*
toInject.add(new VarInsnNode(ALOAD, 0));
toInject.add(new MethodInsnNode(INVOKESTATIC, "mod/culegooner/MyStaticClass", "myStaticMethod", "()V"));

// add the added code to the nstruction list
// You can also choose if you want to add the code before or after the target node, check the ASM Javadoc (insertBefore)
m.instructions.insert(targetNode, toInject);
*/

System.out.println("Patching Complete!");
break;
}
}

//ASM specific for cleaning up and returning the final bytes for JVM processing.
ClassWriter writer = new ClassWriter(ClassWriter.COMPUTE_MAXS | ClassWriter.COMPUTE_FRAMES);
classNode.accept(writer);
return writer.toByteArray();
}

Example:

The full code for this example can be found here:
ExplosionDropsCore

In this example we will replace the *WHOLE* EntityCreeper.class with one that has the following modifications:

diff -ruN forge/mcp/src/minecraft/net/minecraft/entity/monster/EntityCreeper.java baseEdits_777/mcp/src/minecraft/net/minecraft/entity/monster/EntityCreeper.java
--- forge/mcp/src/minecraft/net/minecraft/entity/monster/EntityCreeper.java 2013-07-09 03:42:53.130368000 +0300
+++ baseEdits_777/mcp/src/minecraft/net/minecraft/entity/monster/EntityCreeper.java 2013-07-09 04:30:41.259006500 +0300
@@ -19,6 +19,7 @@
import net.minecraft.item.Item;
import net.minecraft.nbt.NBTTagCompound;
import net.minecraft.util.DamageSource;
+import net.minecraft.util.MathHelper;
import net.minecraft.world.World;

public class EntityCreeper extends EntityMob
@@ -259,4 +260,25 @@
super.onStruckByLightning(par1EntityLightningBolt);
this.dataWatcher.updateObject(17, Byte.valueOf((byte)1));
}
+
+
+ /**
+ * Called frequently so the entity can update its state every tick as required. For example, zombies and skeletons
+ * use this to react to sunlight and start to burn.
+ */
+ public void onLivingUpdate()
+ {
+ if (this.worldObj.isDaytime() && !this.worldObj.isRemote)
+ {
+ float f = this.getBrightness(1.0F);
+
+ if (f > 0.5F && this.rand.nextFloat() * 30.0F < (f - 0.4F) * 2.0F && this.worldObj.canBlockSeeTheSky(MathHelper.floor_double(this.posX), MathHelper.floor_double(this.posY), MathHelper.floor_double(this.posZ)))
+ {
+ this.setFire(8);
+ }
+ }
+
+ super.onLivingUpdate();
+ }
+
}

After we modify the base class run forge/mcp commands to compile and obfuscate:
recompile.bat
reobfuscate.bat --> gives the obfuscated class
reobfuscate_srg.bat --> gives the unobfuscated class

This will give us the class files:
net.minecraft.entity.monster.EntityCreeper.class
and
te.class


open the file CreeperBurnCore_dummy.jar with winzip or 7zip and put those classes inside the jar.

the structure should end up looking like so

CreeperBurnCore_dummy.jar
+->META-INF
..|
..+-> MANIFEST.MF

+->net
..|
..+->minecraft
....|
....+->entity
......|
......+->monster
........|
........+->EntityCreeper.class

+->te.class

Once again we need to implement the IFMLLoadingPlugin and IClassTransformer interfaces

public class CBFMLLoadingPlugin implements IFMLLoadingPlugin {

//declare a placeholder for the name and location of the CreeperBurnCore_dummy.jar
public static File location;

@Override
public String[] getASMTransformerClass() {
////This will return the name of the class "mod.culegooner.CBClassTransformer"
return new String[]{CBClassTransformer.class.getName()};
}


@Override
public void injectData(Map<String, Object> data) {
//This will return the jar file of this mod CreeperBurnCore_dummy.jar"
location = (File) data.get("coremodLocation");
}

}

For this example, we don't want the transformer to modify a specific base method, instead we want to replace the entire class.

public class CBClassTransformer implements IClassTransformer {

@Override
public byte[] transform(String arg0, String arg1, byte[] arg2) {

//Check if the JVM is about to process the te.class or the EntityCreeper.class
if (arg0.equals("te") || arg0.equals("net.minecraft.entity.monster.EntityCreeper")) {
System.out.println("********* INSIDE CREEPER TRANSFORMER ABOUT TO PATCH: " + arg0);
arg2 = patchClassInJar(arg0, arg2, arg0, CBFMLLoadingPlugin.location);
}
return arg2;
}

//a small helper method that takes the class name we want to replace and our jar file.
//It then uses the java zip library to open up the jar file and extract the classes.
//Afterwards it serializes the class in bytes and pushes it on to the JVM.
//with the original bytes that JVM was about to process ignored completly

public byte[] patchClassInJar(String name, byte[] bytes, String ObfName, File location) {
try {
//open the jar as zip
ZipFile zip = new ZipFile(location);
//find the file inside the zip that is called te.class or net.minecraft.entity.monster.EntityCreeper.class
//replacing the . to / so it would look for net/minecraft/entity/monster/EntityCreeper.class
ZipEntry entry = zip.getEntry(name.replace('.', '/') + ".class");


if (entry == null) {
System.out.println(name + " not found in " + location.getName());
} else {

//serialize the class file into the bytes array
InputStream zin = zip.getInputStream(entry);
bytes = new byte[(int) entry.getSize()];
zin.read(bytes);
zin.close();
System.out.println("[" + "CreeperBurnCore" + "]: " + "Class " + name + " patched!");
}
zip.close();
} catch (Exception e) {
throw new RuntimeException("Error overriding " + name + " from " + location.getName(), e);
}

//return the new bytes
return bytes;
}
}

The full code for this example can be found here:
CreeperBurnCore

This section is just how to make the core mod appear in the lists of mods when you click on "Mods" on the main page

Going back to the class that implements IFMLLoadingPlugin add the following:

@Override
public String getModContainerClass() {
//This is the name of our dummy container "mod.culegooner.CreeperBurnCore.CBDummyContainer"
return CBDummyContainer.class.getName();
}

Then create a class that extends cpw.mods.fml.common.DummyModContainer

package mod.culegooner.CreeperBurnCore;

import java.util.Arrays;

import com.google.common.eventbus.EventBus;
import com.google.common.eventbus.Subscribe;

import cpw.mods.fml.common.DummyModContainer;
import cpw.mods.fml.common.LoadController;
import cpw.mods.fml.common.ModMetadata;
import cpw.mods.fml.common.event.FMLConstructionEvent;
import cpw.mods.fml.common.event.FMLInitializationEvent;
import cpw.mods.fml.common.event.FMLPostInitializationEvent;
import cpw.mods.fml.common.event.FMLPreInitializationEvent;

public class CBDummyContainer extends DummyModContainer {

public CBDummyContainer() {

super(new ModMetadata());
ModMetadata meta = getMetadata();
meta.modId = "CreeperBurnCore";
meta.name = "CreeperBurnCore";
meta.version = "@VERSION@";
meta.credits = "Roll Credits ...";
meta.authorList = Arrays.asList("culegooner");
meta.description = "";
meta.url = "https://github.com/culegooner/CreeperBurnCore";
meta.updateUrl = "";
meta.screenshots = new String[0];
meta.logoFile = "";

}

@Override
public boolean registerBus(EventBus bus, LoadController controller) {
bus.register(this);
return true;
}

@Subscribe
public void modConstruction(FMLConstructionEvent evt){

}

@Subscribe
public void preInit(FMLPreInitializationEvent evt) {

}

@Subscribe
public void init(FMLInitializationEvent evt) {

}


@Subscribe
public void postInit(FMLPostInitializationEvent evt) {

}

}

This is how I run coremods in my development enviroment. There is another way using the argument fml.coreMods.load, but I never tried that. I use the approach I'm explaining here since I could also include the class patches to it as in the example of CreeperBurnCore discussed earlier.

If you still want to use the fml.coreMods.load argument, then just type the following in your VM arguments of your run configuration. If you have multiple coremods you seperate them with a comma.

-Dfml.coreMods.load=mod.culegooner.ExplosionDropsCore.EDFMLLoadingPlugin

Here's how to create the dummy jar:

First create a directory called META-INF.
Inside the META-INF folder create a file called MANIFEST.MF

Edit the file and for the line FMLCorePlugin write the fully qualified name of the class that implements the IFMLLoadingPlugin interface.
Make sure to include the other 2 lines as well.

Manifest-Version: 1.0
FMLCorePlugin: mod.culegooner.ExplosionDropsCore.EDFMLLoadingPlugin
Created-By: 1.7.0 (Oracle Corporation)

Compress the directory into a zip using winrar or 7zip and rename the file to have the extension .jar instead of .zip (Don't compress into a .rar format!)

In the end the final jar should look like this:

ExplosionDropsCore_dummy.jar
+->META-INF
..|
..+-> MANIFEST.MF

Now copy the new jar file to the directory /forge/mcp/jars/mods

A very quick guide to access transformers. I wasn't planning on writing one this early since I don't have a practical example to show.
Instead we'll just look at Forge itself and how it uses it.
This section as with this whole tutorial might not be 100% accurate.


Prerequisite:
-------------
You must be familliar with java reflection and that this also exists as an alternative that you can exploit.



What are they?
To describe it in the most simple terms, they are just a way of changing the access levels of vanilla classes/methods/fields

so if in vanilla you find:

private int var;

and you want to be able to access that var and modify it, then run AccessTransformer on it so it becomes:

public int var;

How it's done?

As with all the other coremods we need to implement the IFMLLoadingPlugin and IClassTransformer interfaces.

But in the case of AccessTransformers, cpw already implemented the IClassTransformer and it's called cpw.mods.fml.common.asm.transformers.AccessTransformer
So instead of implementing your own version, you can just extend AccessTransformer!

Let's get back to the IFMLLoadingPlugin implementation in forge:

public class FMLForgePlugin implements IFMLLoadingPlugin
{
@Override
public String[] getASMTransformerClass()
{
return new String[]{"net.minecraftforge.transformers.ForgeAccessTransformer"}; }
}

And the implementation of ForgeAccessTransformer is very straight forward:

public class ForgeAccessTransformer extends AccessTransformer
{
public ForgeAccessTransformer() throws IOException
{
super("forge_at.cfg");
}
}

So it's letting AccessTransformer worry about the full implementation and it's just passing the _at.cfg file.

How is the _at.cfg written?

You can use the files in mcp/conf to find the mapping of the variables and fields that you need.

just add the access level and the field or method you want to change. To change if the field is final add the flag -f +f depending on the situation.
Look at the forge_at.cfg for examples.

But let's say you want to change the visibility of a class and it's constructor.

in the fml_cfg there's this example:

# CallableMinecraftVersion - sanity check the MC version
public c #CL:CallableMinecraftVersion
public c.<init>(Lb;)V #MD:CallableMinecraftVersion/<init>(Lnet/minecraft/src/CrashReport;) #constructor

You can find from the joined.srg the following about CallableMinecraftVersion and CrashReport:
CL: c net/minecraft/src/CallableMinecraftVersion
CL: b net/minecraft/src/CrashReport

But what about this <init>?

c.<init> is another way of saying the constructor of c

You can look at the joined.exc and see
net/minecraft/src/CallableMinecraftVersion.<init>(Lnet/minecraft/src/CrashReport;)V=|p_i1338_1_

so our target is:
net/minecraft/src/CallableMinecraftVersion.<init>(Lnet/minecraft/src/CrashReport;)V

and replacing CallableMinecraftVersion and CrashReport with the obfuscated counterparts we end up with this:
c.<init>(Lb;)V

Just to make sure that what we are doing is correct, grab the mincraft server jar minecraft_server.1.6.2.jar
and extract it to some folder.

inside where all the classes are run this command from the command line:

javap -s c.class

The output should be like so:

Compiled from "SourceFile"
class c implements java.util.concurrent.Callable {
final b a;
Signature: Lb;
c(B);
Signature: (Lb;)V

public java.lang.String a();
Signature: ()Ljava/lang/String;

public java.lang.Object call();
Signature: ()Ljava/lang/Object;
}

So that shows us that the constructor which takes a parameter c( b ) has the signature (Lb;)V

These launch scripts allow you to run javap and ASMifier on your source code inside of eclipse. The results are displayed in the Console tab in eclipse.

just copy the *.launch files to

forge/mcp/eclipse/.metadata/.plugins/org.eclipse.debug.core/.launches/

the launch configuration can be downloaded from here:
EclipseLaunchers