- ASM is a Java library for reading, changing, and writing JVM bytecode.
- It works on compiled .class files, so it can rewrite a class without recompiling.
- Mods use it to patch the already-compiled game at load time.
- Most modders use Mixin, which sits on top of ASM and hides the detail.
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.
Where Opal fits
Opal is a Fabric mod, and Fabric mods reach into game code through this bytecode layer. You do not touch it directly: the scripting engine gives you a clean way to extend Opal without writing bytecode.
What ASM actually does
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.
How it works
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 ways to do this.
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 it
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.
