feat: introduction

.gitignore

@@ -0,0 +1 @@
+book

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 zaaarf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,2 @@
+# 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.

book.toml

@@ -0,0 +1,5 @@
+[book]
+authors = ["zaaarf"]
+language = "en"
+multilingual = false
+src = "src"

src/1_introduction/asm_patching.md

@@ -0,0 +1,4 @@
+# An introduction to ASM patching
+ASM patching means, in short, to modify the "ASM" - that is, "assembly" - of an application at runtime. Within Java, this refers to the bytecode, which is the lower-level language your Java code gets compiled to. Due to the radical nature of modifying the game, before writing a patch one should always wonder whether patching is the correct approach. That is not to say that there is never a need for patching: you should just know that many problems can be solved by other means.
+
+Though reviled by many, ASM patching remains one of the most powerful tools at your disposal when modding a game. Like every tool, ASM patching is not evil in itself, rather it depends on how one uses it; when used correctly, it can solve just about any problem elegantly and with the lowest possible footprint; when done incorrectly, it can wreak havoc on the entire environment, causing inexplicable crashes and odd incompatibilities.

src/1_introduction/why_lillero.md

@@ -0,0 +1,12 @@
+# Why Lillero?
+As you may have gleamed from the previous chapter, I am not a fan of Mixin.
+I respect its engineering, which is admittedly clever, and acknowledge the problems it attempts to solve, but I reject their solutions.
+
+[Lillero](https://github.com/zaaarf/lillero) was my alternative answer, which I wrote with a clear goal in mind: it should allow to do everything, while keeping it as comfortable as it can get this close to bare metal. Lillero is lightweight and flexible, but also easy to write when used to its full potential.
+
+The idea was to provide a simple interface, with methods to provide the metadata and one method where the implementer would get to perform his modifications.
+As we'll see, this resulted in quite a bit of boilerplate, which prompted the creation of the [Lillero-processor](https://github.com/zaaarf/lillero-processor/) to generate all of it.
+
+*Generate* is the keyword here: repetitive tasks aren't removed or 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 working with it. Should one want to dig deeper, they'll find that all of Lillero's code is fully documented, with a Javadoc for every last method and field.
+
+The Minecraft Forge Forums and many others would agree that this knowledge should be left buried in the sands of time where it is. I disagree: it's in the same spirit that I wrote this book. This should serve as a guide not to Lillero alone, but to the whole world of ASM patching.

src/1_introduction/why_mixin.md

@@ -0,0 +1,14 @@
+# Why (not) Mixin?
+[Mixin](https://github.com/SpongePowered/Mixin/) is a bytecode manipulation framework that has become very popular in recent years. 
+Though it also relies on the [ASM library](https://asm.ow2.io/), Mixin is not an "ASM patching" framework in the true meaning of the word, though it has similar goals. 
+Self-described as a "bytecode-weaving" framework, it allows the user wishing to modify Java code to work at a considerably higher level.
+
+The user of Mixin will be writing familiar Java, rather than mysterious bytecode instructions, and you'll use a system of annotations to determine where to write.
+You will have a far easier life working with Mixin, but you won't have the surgical precision that is the main strength of ASM patching.
+Another advatage of working at a lower level is that you can do just about anything: Mixin is quite big, and the reason is that by hiding everything behind a simplified façade they now have to re-invent just about any operation that normal ASM patching allows you to do.
+
+An unfortunately widespread myth is that Mixin "allows for greater compatibility" with other mods that work to modify the same part of the code. This is not true.
+Poorly written Mixins can break compatibility as much as any badly ASM patch; conversely, properly made Mixins will work just as well as properly written ASM patches.
+The one true upside Mixin has is that it's stricter: it performs a number of checks to ensure the validity of what you wrote, a safety net that simply does not exist in raw ASM. This, however, has nothing to do with compatibility.
+
+Mixin is also unfortunately huge; while most Minecraft mod loaders now bundle it (which is a questionable design choice, but whatever), this issue still exists when patching outside of those. In many cases, I've seen more than a program bundle a Mixin binary that was a dozen times bigger than itself.

src/SUMMARY.md

@@ -0,0 +1,5 @@
+# Summary
+[What is Lillero?](./what_is_lillero.md)
+- [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)

src/what_is_lillero.md

@@ -0,0 +1,16 @@
+# What is Lillero?
+Lillero is a lightweight and simple Java ASM patching framework built on top of [ObjectWeb's ASM library](https://asm.ow2.io/).
+It can be used in conjunction with any loader that supports the ASM library's `ClassVisitor` system. 
+
+Lillero is made up of multiple components:
+
+- [Lillero](https://github.com/zaaarf/lillero), the core library.
+- [Lillero-processor](https://github.com/zaaarf/Lillero-processor), the annotation processor.
+- [Lillero-mapper](https://github.com/zaaarf/lillero-mapper), a library which provides the ability to read multiple obfuscation mapping formats.
+- [Lillero-mapping-writer](https://github.com/zaaarf/Lillero-mapping-writer), a CLI tool for converting and inverting mapping formats.
+
+On top of these, there's [Lillero-loader](https://github.com/zaaarf/lillero-loader), a sample loader, in form of a plugin for Minecraft Forge's [ModLauncher](https://github.com/McModLauncher/modlauncher).
+Lillero-loader is the only Minecraft-specific part of the Lillero system.
+To reiterate: while Lillero was initially developed for use with Minecraft, it really works with anything, as long as you have a loader that supports the ASM library.
+
+This book will introduce you to ASM patching and provide an in-depth guide on how to use Lillero to do it in a way that is flexible and yet comfortable.