Differences

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

--- tutorial:mixin_introduction [2025/10/20 00:15] – Clarify wording for redirectors "notes" section in table gauntrecluse
+++ tutorial:mixin_introduction [2025/11/21 00:24] (current) – Rephrase and abbreviate some parts gauntrecluse
@@ Line 1: / Line 1: @@
-FIXME //The Mixin related pages of the Fabric Wiki are undergoing a more thorough review, and are subject to change, rewrites or being replaced. Many pages may be outdated, inaccurate, inactive or incomplete. It is strongly recommended to use the Fabric wiki and linked resources to get a rudimentary Mixin understanding, and then frequently ask questions in dedicated Mixin Support channels on the Fabric or SpongePowered Discord servers for any specific knowledge or specific issue-solving. Any help or feedback in amending pages on this topic is greatly appreciated.//\\
+FIXME //The Mixin related pages of the Fabric Wiki are undergoing a more thorough review, and are subject to change, rewrites or being replaced. Many pages may be outdated, inaccurate, inactive or incomplete. It is strongly recommended to use the Fabric wiki and linked resources to get a rudimentary Mixin understanding, and then frequently ask questions in dedicated Mixin Support channels on the Fabric or SpongePowered Discord servers for any specific knowledge or specific issue-solving. Any help or feedback in amending pages on this topic is greatly appreciated.//
-//This page specifically is under heavy revisions, and may change in large ways almost overnight as a result. Always prioritize learning from the dedicated external Wikis and asking questions in support channels when in doubt//
 ====== 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. 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.
+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, there are currently no plans to support it or document such a process. Note that Kotlin in particular is directly incompatible with Mixin without providing additional compatibility layers.
-Mixin is a complex subsystem which merges a mod's Mixin "classes"
+Mixin is a complex subsystem which uses 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 Mixin Wiki page]] for a stronger base of understanding of Mixin's architecture, and how Mixin classes 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.))
+((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 Mixin Wiki page]]. Mixin classes should not be instantiated as they no longer exist at runtime.))
-into the targeted classes' compiled Bytecode at runtime by parsing the Mixin classes' Bytecode. This is done by merging the Mixin class's members, with some exceptions, and new interface implementations into the target 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.
+to transform the targeted classes' compiled Bytecode as the game runs("runtime"), but before the target class is loaded.
-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.\\
+It is not recommended to try and learn how Mixin works or how to use it without prior knowledge of what Java bytecode is, as Mixin applies to bytecode rather than "source" code. 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, such as 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.\\
+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 an 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 or create Mixins that will be needlessly incompatible with other mods.\\
-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.
+It is recommended to leverage the [[https://mcdev.io/|Minecraft Development plugin by demonwav on IntelliJ]] (AKA MCDev) for Mixin development to benefit from its autocompletion, error highlighting, and utilities such as the MixinExtras Flow Diagram.
-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.
+Mixin can do its work throughout the game's lifecycle, however, a Mixin's transformations 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 certain targets may only be loaded as the game loads a world.
 There are different tools Mixin and MixinExtras
 ((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.))
-provide for modifying source code. Most of these tools are provided to the users in the form of Java annotations, those annotations decorate(annotate, are attached to) members of the Mixin class, itself decorated and registered. These annotations serve as a way to make Mixin merge the annotated members in a specific way.
+provide for modifying source code. Most of these tools are provided to the users in the form of Java annotations, those annotations are associated to members of the Mixin class, itself annotated with ''@Mixin'' and [[tutorial:mixin_registration|registered]]. These annotations are used to communicate to Mixin how to treat different elements of the Mixin class during the target's modification process.
-Here is a cursory overview of some of Mixin's key features:\\
+As to make reading more precise documentation easier, here is a basic overview of some of Mixin's most important 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.//
 ^ 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]] |
+| ''@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 [[tutorial:mixin_registration|registered in the relevant Mixin config file]]. |
-| 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.  | 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. |
+| Merging | Mixin merges a Mixin class's members and interface implementations, apart from some outliers, into the target class. Annotations on members may dictate special merging behavior or prevent merging altogether.  | Understanding that Mixin classes are transformed into the target class which they are subsequently merged with, and that as a result the Mixin classes do not exist at runtime (with the exception of accessors) is fundamental to understanding many of Mixin'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. | 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. |
+| Injectors | An injector typically refers to an annotation and an associated "handler" method. When an injector's "handler" is merged, it will add new instructions at the specified point in the target method(s), without removing or overwriting any existing bytecode there. | Injectors include all of the modification tools from MixinExtras, along with mainly ''@Inject'', ''@ModifyVariable'' and ''@ModifyArg'' in "stock" Mixin. Injectors should be the primary way for a user to modify the target code, as multiple injectors may target the same element and chain with one another for compatibility. |
-| Redirectors(rarely called Redirect Injectors) | 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 due to their ability to chain with other mods. Redirectors should only be used when a good reason necessitates them, such as an intended incompatibility. |
+| Redirectors(rarely called Redirect Injectors) | 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 for more than on Redirector to apply to the same target, making them impractical unless a hard incompatibility is intended. | Redirectors include mainly ''@Redirect'' and ''@ModifyConstant''. Both of which can be replaced by MixinExtras' ''@WrapOperation'' or ''@ModifyExpressionValue'' injectors for use-cases not leveraging redirectors' incompatibility from the lack of chaining. |
-| 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. |
+| Overwriting | Done explicitly via ''@Overwrite'', describes the process of a Mixin member replacing, overwriting, an existing member in the target class. | Overwriting is inherently incompatible, and unless the intent is to use that incompatibility, it should never be done. |
-//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.//
+//For more complete information on Mixin functionality and usage 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 also be found in the source code of both, viewable in your IDE.//
 The Fabric Wiki offers several articles that provide practical examples and explanations of some areas of Mixin and MixinExtras:
@@ Line 40: / Line 39: @@
     * [[tutorial:mixin_redirectors_methods|Method redirectors]]
   * [[tutorial:mixin_tips|Tips]] (WIP)
-  * [[tutorial:mixin_examples|Examples]] (Rewrite WIP -GauntRecluse)
+  * [[tutorial:mixin_examples|Examples]]
   * [[tutorial:mixin_hotswaps|Hotswapping Mixins]]
   * [[tutorial:mixin_export|Exporting Mixin Classes]]
-  * [[tutorial:accesswideners |Access Wideners]]
+  * [[tutorial:accesswideners|Access Widening]]
   * [[tutorial:reflection|Reflection]]
   * [[tutorial:interface_injection|Interface Injection]]
   * [[tutorial:modding_tips|Modding Tips]]