Differences

This shows you the differences between two versions of the page.

--- tutorial:mixin_introduction [2025/09/23 18:19] – [Major Edit] Add a first version of a proper introduction to Mixins as a subsystem rather than relying purely on other internal and external pages to give an introduction to the concept. This introduction it WIP, and the title has been marked as such. Due gauntrecluse
+++ tutorial:mixin_introduction [2025/10/06 03:03] (current) – misc. rephrasings, replaced itemized list with table, add mention of MCDev gauntrecluse
@@ Line 4: / Line 4: @@
 ====== Introduction to Mixins (WIP) ======
 Mixins are a powerful and important tool used in the Fabric ecosystem and other modding frameworks for Minecraft. Their primary use case is modifying existing code in the base game,
-whether it be through injecting custom logic, removing mechanics, or modifying values. Note that **only Mixins written in Java are directly supported**, even if you use Kotlin or another language running on the Java Virtual Machine for the rest of your mod. It may technically be possible to use languages which compile to JVM Bytecode, but there are currently no plans to support it or document such a process.
+whether it be through injecting custom logic, removing mechanics, or modifying values. Note that **only Mixins written in Java are directly supported**, even if you use Kotlin or another language running on the Java Virtual Machine for the rest of your mod. Whilst it may be technically possible to use other JVM languages apart from Kotlin which is explicitly unsupported, there are currently no plans to support it or document such a process.
-Mixin is a complex subsystem which merges a mod's mixin "classes"
+Mixin is a complex subsystem which merges a mod's Mixin "classes"
 ((Mixin classes are not classes in the same way as "standard" Java classes. See [[https://github.com/SpongePowered/Mixin/wiki/Introduction-to-Mixins---Understanding-Mixin-Architecture/|the relevant Wiki page]] for a stronger base of understanding of Mixin's architecture, and how they do not fit in the practical Java definition of classes. TL;DR, Mixin Classes are only classes for the sake of being merged into another class at runtime. They shouldn't be instantiated.))
-into the targeted classes' compiled Bytecode at runtime by parsing the mixin classes' compiled bytecode. The specifics of how this is done is outside the scope of this introduction, refer to the relevant Mixin Wiki links on this page for details.\\
+into the targeted classes' compiled Bytecode at runtime by parsing the mixin classes' bytecode. It will merge both the annotated methods, and other members and interfaces added to the Mixin class. The specifics of how this is done is outside the scope of this introduction, refer to the relevant Mixin Wiki links on this page for details.
-It is not recommended to try and learn how Mixin works or how to use it without having some notion of what Bytecode is, as that may lead to unexpected behavior and misunderstandings. It is also recommended to know how to read Java Bytecode for your IDE of choice, as reading portions of the Bytecode may sometimes be necessary to use Mixin properly, notably when targeting anonymous classes, lambdas or code with a lot of ''if-else'' logic branching.\\
-Similarly, Mixin and this documentation expects the user to already be familiar with [[tutorial:reading_mc_code|Reading Minecraft and external source code]], and be able to set up an initial development environment, aswell as having a decent understanding of Java fundamentals.
-Mixin does its work very early in the overall Fabric launching process, and must be, in rough terms, fully applied before the code it targets is actually "in use". By the time a client sees the title menu or a server becomes joinable, Mixin has already attempted to complete all the work it could. This does not at all guarantee Mixin applied all patches as intended by the devs or that no patches were cancelled. It only means Mixin will not modify the game any further after that point.
+It is not recommended to try and learn how Mixin works or how to use it without having some notion of what Java bytecode is, as that may lead to unexpected behavior and misunderstandings. It is also recommended to know how to read bytecode for your IDE of choice, as reading portions of the Bytecode may sometimes be necessary to use Mixin properly, notably when targeting anonymous classes, lambdas or code with a lot of ''if-else'' logic branching.\\
+Similarly, Mixin and this documentation expects the user to already be familiar with [[tutorial:reading_mc_code|reading Minecraft and external source code]], and be able to set up an initial development environment, aswell as having a decent understanding of Java fundamentals. If, however, you specifically wish to skip to examples, be aware that it is expected for you to encounter difficulties and confusion in your learning process as you try to tackle more technical issues without learning some technical aspects, and you are likelier to need direct support.\\
+It is recommended to leverage the [[https://plugins.jetbrains.com/plugin/8327-minecraft-development|Minecraft Development plugin by demonwav on IntelliJ]] (AKA MCDev) for Mixin development to benefit from its autocompletion and utilities such as the MixinExtras Flow Diagram.
-There are different kinds of tools Mixin and MixinExtras
+Mixin can do its work throughout the game's lifecycle, however, a mixin must be applied before the targeted class has loaded. For the majority of mixins, this is very early in the overall Fabric launching process, but do mind that the game launching without Mixin crashing or logging warns doesn't mean all changes have applied as intended.
-((Since Fabric Loader 0.15, MixinExtras is bundled with Fabric. Since Loader version 0.17.0, MixinExtras major version 0.5.0 is included, and allows access to [[https://github.com/LlamaLad7/MixinExtras/wiki/Expressions|Expressions]] for extremely precise and flexible targeting. MixinExtras is a companion library to Mixin and is extremely useful for precise and compatible manipulation of Mixins.))
-provide for modifying source code. Those tools come in the form of Java annotations, those annotations decorate((AKA annotate, are attached to)) members of the Mixin class and are passed arguments which are used to associate the necessary information so that Mixin knows how to process your class and then transform and merge them into the target class. Here is a basic overview of Mixin's important annotations:\\
-FIXME //There ought to be dedicated pages going more in depth about the different tools annotations later on. This segment as it is edited should be kept to an introductory level to Mixin annotations and features.//
-  * The ''@Mixin'' annotation decorates every Mixin class. It mainly dictates the class to target and the priority of the decorated class relative to other mixin classes with the same target.
+There are different tools Mixin and MixinExtras
-  * Injector Mixin annotations decorate a handler method((In the context of Mixins, handler methods are the methods that are merged into the target class, and invoked at the relevant point the decorating annotation specifies as a target. For most cases, think of them are the methods decorated by injector or redirector annotations.)) and will inject it into the target class and then call it at the injection point. Injectors are distinguished by the fact they do not overwrite the targeted bytecode((As described on the [[https://github.com/SpongePowered/Mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors#1-code-out-of-the-aether---discovering-injectors|Mixin Wiki page]] introducing injectors)), injectors include all method decorations from MixinExtras and in base Mixin, mainly ''@Inject'', ''@ModifyVariable'' or ''@ModifyArg''.((As per message from Llamalad7 currently pinned in the #mod-dev-mixin Fabric Discord channel)) Injectors should be your primary way to modify external code as they are more compatible (more than one mod can inject the same target), and MixinExtras provides injector alternatives that fulfill nearly all roles of non-injector tools such as redirectors/redirect injectors and overwriting.
+((Since Fabric Loader 0.15, MixinExtras is bundled with Fabric. Since Loader version 0.17.0, MixinExtras major version 0.5.0 is included, and allows access to [[https://github.com/LlamaLad7/MixinExtras/wiki/Expressions|Expressions]] for extremely precise and flexible targeting. MixinExtras is a companion library to Mixin and is essential for precise and compatible manipulation of many Mixins.))
-  * Redirector Mixin annotations refers to annotations that merge the handler method and replace the targeted injection point with a call to your handler method. Think of it as overwriting what you targeted and replacing it with a call to the decorated handler method. Whilst a name for them is also Redirect Injectors, you should generally treat them differently as they do not merely inject but also overwrite information and cannot chain.((As per [[https://github.com/SpongePowered/Mixin/wiki/Advanced-Mixin-Usage---Redirect-Injectors|this stub in the Mixin Wiki]])) The main redirectors are ''@Redirect'' and ''@ModifyConstant''.
+provide for modifying source code. Those tools are usable by the users in the form of Java annotations, those annotations decorate(annotate, are attached to) members of the Mixin class, itself decorated and registered, and are passed metadata which is used by Mixin to process the Mixin class. The class's members, with some exceptions, are then merged into the target class.
-  * Overwriting, using the ''@Overwrite'' annotation simply replaces the targeted method with your own. There is practically never any reason to use this as a mod developer, and you should always prioritize other solutions like MixinExtras' ''@WrapMethod''.
-//For more complete and thorough information on Mixin functionality, usage, and mechanics, view the [[https://github.com/SpongePowered/Mixin/wiki|Mixin Official Wiki]]. Additional documentation can be found in the [[https://jenkins.liteloader.com/view/Other/job/Mixin/javadoc/index.html|Mixin Javadoc]]. MixinExtras features are documented on its [[https://github.com/LlamaLad7/MixinExtras/wiki|Official Wiki]]. JavaDoc documentation may be found in your local development environment with Mixin set up aswell.//
+Here is a cursory overview of some of Mixin's key features:\\
+FIXME //There ought to be dedicated pages going more in depth about the different tools annotations later on. This segment as it is edited should be kept to a cursory overview of Mixin(Extras) features.//
-The Fabric Wiki offers several articles that provide practical examples and explanations of some areas of the Mixin and MixinExtras tools:
+^ Feature ^ Overview ^ Notes ^
+| ''@Mixin'' annotation | Decorates every Mixin class, specifying the target class and the priority of the Mixin class relative to other classes with the same target. | All Mixin classes must also be registered in the relevant Mixin config file, see [[tutorial:mixin_registration|Mixin registration]] |
+| Merging | Mixin merges a Mixin class's members and interface implementations, with some exceptions, into the target class. Annotations on members may dictate special merging behavior or prevent merging. This is the fundamental tool which is used to modify the target class. | Understanding that Mixins //merge// with their target and do not exist at runtime (with the exception of accessors) is fundamental to understanding the rest of the subsystem's features. |
+| Injectors | Methods and a decorating annotation which creates a set of instructions that call back (called a "callback") to the injector's "handler" method at the specified injection point when merging the method. This does not overwrite or remove any of the target class's bytecode, as such more than one injector may target a singular injection point.((As described on the [[https://github.com/SpongePowered/Mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors#1-code-out-of-the-aether---discovering-injectors|Mixin Wiki page]] introducing injectors)) | Injectors include all of the method annotations from MixinExtras, and in "base" Mixin, mainly ''@Inject'', ''@ModifyVariable'' and ''@ModifyArg''. Injectors should be the primary way for a user to modify the target code. |
+| Redirectors/Redirect Injectors((Sometimes called that as per [[https://github.com/SpongePowered/Mixin/wiki/Advanced-Mixin-Usage---Redirect-Injectors|this stub in the Mixin Wiki]])) | Similar to injectors as described above, with the important difference that redirectors replace the target instructions with the callback, rather than only injecting new instructions. This makes it impossible to chain more than one redirector, making them a less practical options unless a hard incompatibility is specifically the intent. | Redirectors include mainly ''@Redirect'' and ''@ModifyConstant''. Both of which can be replaced by MixinExtras' ''@WrapOperation'' or ''@ModifyExpressionValue'' injectors which can chain unless a hard incompatibility is intended. |
+| Overwrites | Done via ''@Overwrite'', this is used to outright replace a target method with the annotated method. It is an impractical tool for nearly all situations compared to MixinExtras' ''@WrapMethod'' or more specific modifications of the method body. | There is practically almost never a situation where overwriting a method is the correct choice, as overwriting is an incredibly intrusive and incompatible tool. As such, one should always gather second opinions, or ask for help if the issue is the inability to figure out more precise tools, before committing to an overwrite; and only then, if it is absolutely necessary, create an overwrite. |
+//For more complete and thorough information on Mixin functionality, usage, and mechanics, view the [[https://github.com/SpongePowered/Mixin/wiki|Mixin Official Wiki]]. Documentation specific to individual Mixin features can be found in the [[https://jenkins.liteloader.com/view/Other/job/Mixin/javadoc/index.html|Mixin Javadoc]]. MixinExtras features are well-documented on its [[https://github.com/LlamaLad7/MixinExtras/wiki|Official Wiki]]. JavaDoc documentation of both may be found in your local development environment with Mixin set up aswell.//
+The Fabric Wiki offers several articles that provide practical examples and explanations of some areas of Mixin and MixinExtras:
   * [[tutorial:mixin_registration|Mixin registration]]
   * [[tutorial:mixin_injects|Injects]]