mirror of
https://github.com/zaaarf/lillero-book.git
synced 2024-11-22 06:24:48 +01:00
feat: began work on chapter 2
This commit is contained in:
parent
6325f4e791
commit
227da6ad1f
5 changed files with 16 additions and 2 deletions
|
@ -1,6 +1,6 @@
|
||||||
# The Lillero Book
|
# The Lillero Book
|
||||||
This is meant as an in-depth guide to ASM manipulation with the [Lillero](https://github.com/zaaarf/lillero) framework. While that's the main focus, it's written to also be useful to anyone wanting to learn ASM patching in general. Some parts (which will be flagged appropriately) may be applicable to Minecraft alone, but most of the book is meant to be generic.
|
This is meant as an in-depth guide to ASM manipulation with the [Lillero](https://github.com/zaaarf/lillero) framework. While that's the main focus, it's written to also be useful to anyone wanting to learn ASM patching in general. Some parts (which will be flagged appropriately) may be applicable to Minecraft alone, but most of the book is meant to be generic.
|
||||||
|
|
||||||
The [ASM](https://asm.ow2.io/) library that Lillero is built with is capable of so much more than what is described in this book. In fact, the [official ASM guide](https://asm.ow2.io/asm4-guide.pdf) is a must-read for anyone wishing to understand its inner workings more in depth. While very well written, the ASM guide reads more like a scientific paper than a user manual, and this is part of my reasons for creating the Lillero Book. Much like Lillero is an intermediary layer meant to simplify working with ASM, this book is an intermediary step meant to give you a passable understanding of patching before plunging deep into the obscure inner workings of Java bytecode.
|
The [ASM](https://asm.ow2.io/) library that Lillero is built with is capable of so much more than what is described in this book. In fact, the [official ASM guide](https://asm.ow2.io/asm4-guide.pdf) is a must-read for anyone wishing to understand its inner workings more in depth. While very well written, the official ASM guide reads more like a scientific paper than a practical manual, and this is part of my reasons for creating the Lillero Book. Much like Lillero is an intermediary layer meant to simplify working with ASM, this book is an intermediary step meant to give you a passable understanding of patching before plunging deep into the obscure inner workings of Java bytecode.
|
||||||
|
|
||||||
In short, this is no replacement for the ASM manual: think of the Lillero Book as a (relatively) simple introduction to its topics.
|
In short, this is no replacement for the ASM manual: think of the Lillero Book as a (relatively) simple introduction to its topics.
|
||||||
|
|
|
@ -5,6 +5,6 @@ Why do people fail at making patches? The answer is lack of checks mixed with ge
|
||||||
|
|
||||||
[Lillero](https://github.com/zaaarf/lillero) was my alternative answer to those problems. I wrote Lillero with a clear goal in mind: it should allow you to do everything, while keeping it as comfortable as it can get this close to bare metal. When used to its full potential, Lillero is lightweight and flexible, but also easy to write. Coupled with this book, it should empower anyone to write good patches following the best possible practices.
|
[Lillero](https://github.com/zaaarf/lillero) was my alternative answer to those problems. I wrote Lillero with a clear goal in mind: it should allow you to do everything, while keeping it as comfortable as it can get this close to bare metal. When used to its full potential, Lillero is lightweight and flexible, but also easy to write. Coupled with this book, it should empower anyone to write good patches following the best possible practices.
|
||||||
|
|
||||||
At the heart of Lillero lies a Java interface, which any patch should implement: it will contain various methods, and any metadata that may be needed by the loader. As we'll see, you won't have to write most of this boilerplate by hand: the [Lillero-processor](https://github.com/zaaarf/lillero-processor/) will take care of generating it.
|
At the heart of Lillero lies a Java interface, which any aspiring patch should implement: it will contain various methods, providing any metadata that may be needed by the loader as well as the one where the patching will happen. As we'll see, you won't have to write most of this boilerplate by hand: the [Lillero-processor](https://github.com/zaaarf/lillero-processor/) will take care of generating it.
|
||||||
|
|
||||||
*Generating* is the keyword here: repetitive tasks aren't abstracted out, they are just made to write by the machine. One can open the generated files and easily see what each annotation does. By design, Lillero's inner workings should be clear and easy to follow for anyone wishing to learn. Should one want to dig deeper, they'll find that all code in the Lillero project is heavily documented, with a Javadoc for every last method and field, so that everything is perfectly clear to anyone wishing to learn from it.
|
*Generating* is the keyword here: repetitive tasks aren't abstracted out, they are just made to write by the machine. One can open the generated files and easily see what each annotation does. By design, Lillero's inner workings should be clear and easy to follow for anyone wishing to learn. Should one want to dig deeper, they'll find that all code in the Lillero project is heavily documented, with a Javadoc for every last method and field, so that everything is perfectly clear to anyone wishing to learn from it.
|
6
src/2_patching/nodes.md
Normal file
6
src/2_patching/nodes.md
Normal file
|
@ -0,0 +1,6 @@
|
||||||
|
# Nodes
|
||||||
|
The [ASM](https://asm.ow2.io/) library represents sequences of bytecode as [doubly linked lists](https://en.wikipedia.org/wiki/Doubly_linked_list), with the [`InsnList`](https://asm.ow2.io/javadoc/org/objectweb/asm/tree/InsnList.html) type. Lillero provides an extended functionality
|
||||||
|
|
||||||
|
Each instruction is a node, represented by [various subclasses](https://asm.ow2.io/javadoc/org/objectweb/asm/tree/package-summary.html) of [`AbstractInsnNode`](https://asm.ow2.io/javadoc/org/objectweb/asm/tree/AbstractInsnNode.html); each node contains an opcode, a number of parameters depending on the opcode type, and references to the preceding and following nodes.
|
||||||
|
|
||||||
|
You can access the nodes within the the [`MethodNode`](https://asm.ow2.io/javadoc/org/objectweb/asm/tree/MethodNode.html) by accessing the `instructions` field.
|
6
src/2_patching/patching.md
Normal file
6
src/2_patching/patching.md
Normal file
|
@ -0,0 +1,6 @@
|
||||||
|
# Patching
|
||||||
|
Since you are applying changes to the bytecode of a class, this must necessarily happen before said class is loaded in memory. The component that applies said changes is called a *loader*; don't concern yourself on the inner workings of loaders for now, just know that they are in charge of the initial step: we'll cover them in detail in their own chapter.
|
||||||
|
|
||||||
|
Suppose that you already have a working loader in place. This loader calls your *injector method*, and passes it a `ClassNode` and a `MethodNode` as arguments, representing respectively the container class and the target method. This is the most common type of ASM patching, and it's probably why you're here; more advanced subjects may be covered in additional chapters later on.
|
||||||
|
|
||||||
|
At a glance, this might seem restrictive. However, do keep in mind that even code outside of methods - in field declarations, in loose blocks, or in `static` blocks - is actually considered to be part of a method by the compiler. Specifically, `<init>` for instance fields and loose blocks, and `<clinit>` for static fields and `static` blocks.
|
|
@ -4,3 +4,5 @@
|
||||||
- [An introduction to ASM Patching](./1_introduction/asm_patching.md)
|
- [An introduction to ASM Patching](./1_introduction/asm_patching.md)
|
||||||
- [Why (not) Mixin?](./1_introduction/why_mixin.md)
|
- [Why (not) Mixin?](./1_introduction/why_mixin.md)
|
||||||
- [Why Lillero?](./1_introduction/why_lillero.md)
|
- [Why Lillero?](./1_introduction/why_lillero.md)
|
||||||
|
- [Patching Methods](./2_patching/patching.md)
|
||||||
|
- [Nodes](./2_patching/nodes.md)
|
Loading…
Reference in a new issue