From 227da6ad1ff4a92d51b4346c1d7a5b5a870a859e Mon Sep 17 00:00:00 2001 From: zaaarf Date: Fri, 8 Sep 2023 19:00:05 +0200 Subject: [PATCH] feat: began work on chapter 2 --- README.md | 2 +- src/1_introduction/why_lillero.md | 2 +- src/2_patching/nodes.md | 6 ++++++ src/2_patching/patching.md | 6 ++++++ src/SUMMARY.md | 2 ++ 5 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 src/2_patching/nodes.md create mode 100644 src/2_patching/patching.md diff --git a/README.md b/README.md index c64b010..26e3e2f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 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. -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. diff --git a/src/1_introduction/why_lillero.md b/src/1_introduction/why_lillero.md index d677543..5e46c29 100644 --- a/src/1_introduction/why_lillero.md +++ b/src/1_introduction/why_lillero.md @@ -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. -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. \ No newline at end of file diff --git a/src/2_patching/nodes.md b/src/2_patching/nodes.md new file mode 100644 index 0000000..b644388 --- /dev/null +++ b/src/2_patching/nodes.md @@ -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. \ No newline at end of file diff --git a/src/2_patching/patching.md b/src/2_patching/patching.md new file mode 100644 index 0000000..731f073 --- /dev/null +++ b/src/2_patching/patching.md @@ -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, `` for instance fields and loose blocks, and `` for static fields and `static` blocks. \ No newline at end of file diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7cfe081..2a34e90 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,3 +4,5 @@ - [An introduction to ASM Patching](./1_introduction/asm_patching.md) - [Why (not) Mixin?](./1_introduction/why_mixin.md) - [Why Lillero?](./1_introduction/why_lillero.md) +- [Patching Methods](./2_patching/patching.md) + - [Nodes](./2_patching/nodes.md) \ No newline at end of file