Learn · concepts
What Is ASM (Java Bytecode)? Library Explained
ASM is a Java library for reading and writing JVM bytecode at runtime. Here is what it does, how it works, and why Minecraft mods rely on it.
What is ASM in Minecraft modding?
ASM is a Java library for reading, changing, and writing JVM bytecode. It works on compiled .class files instead of source code, so it can inspect or rewrite a class without recompiling. Minecraft mods lean on it because it lets them patch the game at load time, after the game is already compiled.
Why bytecode patching exists
The Minecraft game ships as compiled bytecode, not source. That means a mod author can't change the source and recompile the whole game: the source doesn't exist. The only way to patch code you don't own is to reach in at the bytecode level, the instruction set the Java Virtual Machine actually runs. ASM is the practical tool for that job.
How ASM works
ASM turns a compiled class into something a program can edit. A .class file is just bytecode, the instructions the Java Virtual Machine runs. ASM parses that bytecode, hands you the methods and fields, and lets you add, remove, or change instructions. Then it writes a new valid class back out.
Plain Java cannot do this on its own. The compiler turns your source into bytecode once, and after that the bytecode is fixed. ASM reaches in at the bytecode level, which is the layer below the source you normally write.
The visitor pattern and tree API
ASM reads a class with a ClassReader and writes one with a ClassWriter. Between the two, your code visits the parts of the class and decides what to change. There are two approaches:
The visitor approach streams through the class one element at a time. It is fast and uses little memory because it never holds the whole class at once. The tree approach loads the class into objects you can walk and edit freely, which is easier to reason about for bigger changes but uses more memory.
| Approach | How it works | Best for |
|---|---|---|
| Visitor API | Streams class events as they are read | Small, fast edits with low memory |
| Tree API | Builds an editable object model of the class | Larger or more complex rewrites |
Why Minecraft mods use ASM
Mods need to change game code they did not write and cannot recompile. The game ships as compiled classes, so the only way in is at the bytecode level, and that is what ASM provides. A mod can inject a hook into a game method, redirect a call, or add a field, all at launch.
Most modders do not call ASM by hand. They use Mixin, a higher-level framework that sits on top of ASM and turns simple annotations into the bytecode edits underneath. You write a small Java class describing the change, and the framework does the low-level work with ASM for you. Fabric mods in particular rely on this chain.
When you would touch ASM directly
You rarely write raw ASM as a mod author. It shows up when a tool needs more control than an annotation can express, such as a loader, an obfuscator, or a patcher that rewrites classes wholesale. For everyday mods, the annotation layer on top is enough, and it is far less error-prone.
FAQ
No. A decompiler turns bytecode back into readable source. ASM works on the bytecode itself and is built to change it, not to recover source code.
Usually not. Most Fabric mods use Mixin, which hides the ASM details behind annotations. You only reach for raw ASM when you need fine control.
No. ASM is a general Java library used across many tools that work with bytecode. Minecraft modding is one common use, not its only one.
You cannot. The game ships compiled, not as source you can change and rebuild. Editing bytecode is the practical way to patch code you do not own.