|
1 | | -Soon... |
| 1 | +## Problem |
| 2 | + |
| 3 | +[Mixin](https://github.com/spongepowered/Mixin) is a powerful tool that enables on-the-fly code modification at runtime; |
| 4 | +however, it was designed for the broader Java ecosystem, **not just** Minecraft modding. As a result, it provides a |
| 5 | +fairly low-level interface that relies on imperative logic and implementation-heavy annotations. |
| 6 | + |
| 7 | +**Redundancy & Maintenance Hell**: Modding for years with standard Mixins reveals a pattern of constant duplication. A |
| 8 | +single logic change often requires updating method descriptors in multiple places: the injection point, the parameter |
| 9 | +list, Shadow methods, Accessors, and AW/AT configurations. This manual synchronization is fragile; missing a single |
| 10 | +descriptor during a version migration or mapping update leads to a broken mod. |
| 11 | + |
| 12 | +**The "Descriptor" Nightmare**: Relying on long, cryptic strings (like `Lnet/minecraft/class_...;()V`) makes code |
| 13 | +unreadable and error-prone. While IDE plugins help generate these, they only provide "coding-time" assistance. They |
| 14 | +don't prevent the project from building successfully even if a descriptor is wrong, leading to frustrating runtime |
| 15 | +crashes that only appear after the mod is deployed. |
| 16 | + |
| 17 | +**Decision Fatigue**: There is too much "freedom of choice" in how to achieve the same result. Whether it's choosing |
| 18 | +between an Accessor or an AW, or implementing a common pattern like Interface Injection to expose Mixin logic, |
| 19 | +developers often end up copy-pasting the same boilerplate or "reinventing the wheel". |
| 20 | + |
| 21 | +## Inspiration |
| 22 | + |
| 23 | +[MixinExtras](https://github.com/LlamaLad7/MixinExtras) revolutionized the ecosystem by bringing Minecraft-specific |
| 24 | +modding realities into the Mixin world. It introduced conflict-safe injections while maintaining strict compatibility |
| 25 | +with the original Mixin framework. |
| 26 | + |
| 27 | +Seeing the elegance of MixinExtras was my primary inspiration; it revealed the true potential of what modern injections |
| 28 | +could look like. Lapis wouldn't exist without it. To honor this foundation, I chose MixinExtras as the primary backend |
| 29 | +for my code generation, aiming to provide a high-level, intent-based layer on top of its robust architecture. |
| 30 | + |
| 31 | +## Solution |
| 32 | + |
| 33 | +Lapis is the result of moving the complexity from the developer's head to the compiler. It bridges the gap between |
| 34 | +low-level Mixins and expressive Kotlin. |
| 35 | + |
| 36 | +### Key Features |
| 37 | + |
| 38 | +- **Compile-time Safety**: No more runtime crashes due to typos in descriptors. If it builds, it works. |
| 39 | +- **Intent-Based DSL**: Write what you want to change, not how to find the bytecode instruction. |
| 40 | +- **Automatic Boilerplate**: Lapis handles Interface Injections, Extension properties, and AW/AT generation for you. |
| 41 | +- **Built-in Best Practices**: Optimized for conflict-free injections using MixinExtras by default. |
| 42 | + |
| 43 | +| Feature | Standard Mixin | Lapis | |
| 44 | +|:-----------------|:---------------------|:------------------------| |
| 45 | +| **Descriptors** | Strings | Type-safe references | |
| 46 | +| **Maintenance** | Update in 2-5 places | Update in one place | |
| 47 | +| **Safety** | Runtime crashes | Compile-time errors | |
| 48 | +| **Kotlin-first** | No | Native DSL & Extensions | |
| 49 | + |
| 50 | +--- |
| 51 | + |
| 52 | +## Quick Start |
| 53 | + |
| 54 | +> [!NOTE] |
| 55 | +> A brief guide on connecting the KSP plugin will be added here shortly. The full documentation and comprehensive Wiki |
| 56 | +> will be available with the **1.0.0** release. |
| 57 | +> |
| 58 | +> You can find the current documentation in our [Wiki →](https://github.com/recrafter/lapis/wiki). |
0 commit comments