Fabric Wiki

User Tools

Site Tools

Trace: • @Inject • Mixin Glossary (DRAFT)
tutorial:mixin_glossary

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
tutorial:mixin_glossary [2025/10/03 20:34] – Add bytecode entries to glossary for descriptors and signatures bawnortontutorial:mixin_glossary [2025/11/29 03:49] (current) – gauntrecluse
Line 1: Line 1:
-:!: //this page is a draft being written by GauntRecluse! Feedback is appreciated but the page is currently not ready to be read by users of the Wiki!//+:!: //this page is a draft! Feedback is appreciated but the page is currently not ready to be read by users of the Wiki!//
  
 ====== Mixin Glossary (DRAFT) ====== ====== Mixin Glossary (DRAFT) ======
Line 5: Line 5:
 ===== Preamble ===== ===== Preamble =====
  
-This page aims to address terms, acronyms, abbreviations, expressions, etc. and define them within as broad a scope as possible without describing technicalities or how to use them. It is complementary to actual documentation on how to use the tools and subsystem of Mixin and should only be used to get a quick, general idea of what a term means in the context of Mixin usage and learning. This glossary should also be taken with a grain of salt, as much as feedback will try to be used to make the definitions as accurate as possible, it can be as unreliable as any Wiki page.\\+This page aims to address terms, acronyms, abbreviations, expressions, etc. and define them within as broad a scope as possible without instructing how to use the associated tools. It is complementary to actual documentation on how to use the tools and subsystem of Mixin and should only be used to get a quick, general idea of what a term means in the context of Mixin usage and learning. This glossary should also be taken with a grain of salt, as much as feedback will try to be used to make the definitions as accurate as possible, it can be as unreliable as any Wiki page.\\
 It is advised to read the [[[[tutorial:mixin_introduction|Introduction to Mixins (WIP)]] page. It is advised to read the [[[[tutorial:mixin_introduction|Introduction to Mixins (WIP)]] page.
  
Line 12: Line 12:
 Seeing as this page is likely to change a lot with time as terms, both official and common usage ones, may vary over time and need many amendments as both Mixin and associated libraries evolve and get used in different contexts; it feels wise to add a section on best practices for contributing to this page in the long run. Seeing as this page is likely to change a lot with time as terms, both official and common usage ones, may vary over time and need many amendments as both Mixin and associated libraries evolve and get used in different contexts; it feels wise to add a section on best practices for contributing to this page in the long run.
  
-If you wish to contribute it is appreciated to use references to external sources whenever possible, preferably the [[https://github.com/spongepowered/mixin/wiki|official Mixin Wiki]], the [[https://jenkins.liteloader.com/job/Mixin/javadoc/|Mixin javadoc]] and the [[https://github.com/LlamaLad7/MixinExtras/wiki|official MixinExtras Wiki]]. If not, base your definitions on feedback from experienced devs and be willing to be scrutinized.\\+If you wish to contribute it is appreciated to use references to external sources when relevant, preferably the [[https://github.com/spongepowered/mixin/wiki|official Mixin Wiki]], the [[https://jenkins.liteloader.com/job/Mixin/javadoc/|Mixin javadoc]] and the [[https://github.com/LlamaLad7/MixinExtras/wiki|official MixinExtras Wiki]]. If not, base your definitions on feedback from experienced devs and be willing to be scrutinized.\\
 Due to the amount of potential areas that could be edited, it would also be appreciated to always specify which definitions you're adding or editing in your edit summary messages. If necessary, split your edit into different smaller edits to be able to more clearly indicate which definitions were modified. Due to the amount of potential areas that could be edited, it would also be appreciated to always specify which definitions you're adding or editing in your edit summary messages. If necessary, split your edit into different smaller edits to be able to more clearly indicate which definitions were modified.
  
Line 20: Line 20:
  
 TODO notes should always describe what should be added there and should ideally be in //italics// TODO notes should always describe what should be added there and should ideally be in //italics//
 +
 +Example definition:
 +
 +== Words! ==
 +  - First def
 +    - Sub-def
 +    * Note on First def
 +  - Second def
 +    * Note on Second def
 +
 +=== Referencing other definitions ===
 +
 +You can reference another definition on the page by referencing the definition's header: ''[[#header_name|text displayed for the link]]'', for example:\\
 +[[#bytecode|The bytecode segment]] - ''%%[[#bytecode|The bytecode segment]]%%''\\
 +[[#asm|The ASM definition]] - ''%%[[#asm|The ASM definition]]%%''
 +
  
 ---- ----
  
-FIXME //This is under heavy construction and probably contains inaccuracies, likely redundancies, certainly inefficient definitions and most definitely is missing relatively important terms//+:!: //This is under heavy construction and probably contains inaccuracies, likely redundancies, certainly inefficient definitions or may be missing important definitions.//
 ===== Definitions ===== ===== Definitions =====
  
-==== General/Misc. Terms ====+==== General and Misc. Terms ====
  
-== Mixin, Mixins ==+== Lambda Function, Lambda Method == 
 +  - Unnamed method that can be defined within a method body(see [[#enclosing_method|Enclosing Method]]), consisting of parameters followed by a method body or expression. Variables of a functional interface type, such as Java's ''Consumer<T>'', may also be used to hold a lambda function to be passed as an argument or stored as a variable later. Lambdas targeted separately from the rest of the encapsulating class's methods, as they are compiled into separate synthetic methods in [[#bytecode|Bytecode]]. 
 +  * For a more thorough technical definition, see [[https://docs.oracle.com/javase/tutorial/java/javaOO/lambdaexpressions.html|the official Oracle Documentation]]. 
 + 
 + 
 +== Anonymous Class == 
 +  - A nameless inner class declared and instantiated a single time. Anonymous classes may be declared within a method's body, such as to assign its instance to a local variable. As inner classes, anonymous classes must be targeted separately from the [[#encapsulating_class,_outer_class|outer class]] when mixing into it. 
 + 
 + 
 +== Enclosing Method == 
 +  - The method containing the relevant subject, such as an [[#anonymous_class|anonymous class]] or a [[#lambda_function,_lambda_method|lambda method]]. 
 + 
 +== Encapsulating Class, Outer Class == 
 +  - The class containing the relevant subject, often an inner class such as an [[#anonymous_class|anonymous class]]. 
 + 
 +== Mixin, Mixin Class ==
   - When used as a single term in the form of a proper noun, references the Mixin Subsystem as a whole. Mixin is a subsystem with the primary purpose of allowing a developer to describe modifications to be made at runtime using code. See [[tutorial:mixin_introduction|Introduction to Mixins (WIP)]]   - When used as a single term in the form of a proper noun, references the Mixin Subsystem as a whole. Mixin is a subsystem with the primary purpose of allowing a developer to describe modifications to be made at runtime using code. See [[tutorial:mixin_introduction|Introduction to Mixins (WIP)]]
-  - "a Mixin" or "a Mixin Class" references instances of classes or interfaces that are annotated with ''@Mixin'', and will be merged with a target class as a means to modify it.+  - "a Mixin" or "a Mixin Class" refers to classes or interfaces that are annotated with ''@Mixin'', and will be merged with a target class as a means to transform it. Non-accessor Mixins will not be available at runtime due to the merging process. 
 + 
 + 
 +== Target Class == 
 +  - A class with contents being targeted by the relevant Mixin Class's transformations. 
 + 
 + 
 +== Target Method == 
 +  - A method within a [[#target_class|target class]] being targeted by transformations from a Mixin class. 
  
 == Merging, to merge == == Merging, to merge ==
-  - In the context of a Mixin class being merged into a target class, it means adding new members and interfaces from the Mixin class into the target class's bytecode.+  - In the context of Mixin, merging most of members and new interface implementations from the Mixin class into the target class's bytecode. 
 + 
 + 
 +== Shadowing == 
 +  - Reference to usages of ''@Shadow'', an annotation used to simulate the presence of fields and methods from the target class to reference them. Shadowing avoids needing to cast a ''this'' to the target class for any and all fields. 
 + 
 +== Double-Casting == 
 +  - For Mixins, references the practice of casting a ''this'' instance of the Mixin class to ''Object'' and then to the target class. This is used mainly to pass the ''this'' instance of the target class as an argument. It is advised to use [[#shadowing|Shadows]] to reference the target's fields, and to extend the target's parents to access the parents' fields. 
 + 
 + 
 +== Accessor == 
 +  - Reference to an [[tutorial:mixin_accessors|Accessor Mixin]], or in other words an interface Mixin composed purely of ''@Accessor'' and ''@Invoker'' Mixins. 
 +  - Reference to the ''@Accessor'' annotation and its usages. An accessor is used to create public getter/setter fields for fields that would otherwise be immutable or inaccessible. 
 + 
 +== Invoker == 
 +  - Reference to the ''@Invoker'' annotation and its usages. An Invoker is used to call methods that would otherwise be inaccessible. It is mainly used in the context of [[tutorial:mixin_accessors|Accessor Mixins]]. 
 + 
  
 == MixinExtras == == MixinExtras ==
-  - A companion library for the Mixin subsystem primarily authored by Llamalad7. MixinExtras focuses on giving more versatile, precise and compatible injectors and general Mixin usage utility. MixinExtras is bundled with Fabric since Loader version 0.15; MixinExtras 0.5.0 has been bundled with Fabric since Loader version 0.17.0; See [[https://github.com/LlamaLad7/MixinExtras/wiki|the MixinExtras Wiki]].+  - A companion library for the Mixin subsystem. MixinExtras focuses on giving more versatile, precise and compatible injectors and general Mixin usage utility. MixinExtras is bundled with Fabric since Loader version 0.15; MixinExtras 0.5.0 has been bundled with Fabric since Loader version 0.17.0; See [[https://github.com/LlamaLad7/MixinExtras/wiki|the MixinExtras Wiki]].
  
  
Line 44: Line 101:
  
 == MCDev == == MCDev ==
-  - References the IntelliJ Minecraft Development Plugin. It is very frequently used for Mixin development due to the added convenience, autocompletion and error detection it provides. See [[https://plugins.jetbrains.com/plugin/8327-minecraft-development|the plugin's home page]].+  - References the IntelliJ Minecraft Development Plugin. It is very frequently used for Mixin development due to the added convenience, autocompletion and error detection it provides. See [[https://mcdev.io/|the plugin's home page]]. 
 + 
 + 
 +== ASM == 
 +  - Java framework used by Mixin and other tools to modify and manipulate JVM bytecode at runtime. 
 +  - In general programming contexts, may refer to Assembly. 
  
 ---- ----
Line 62: Line 125:
 == Field Descriptor == == Field Descriptor ==
   - A field descriptor represents the type of a field, parameter, local variable, or value.   - A field descriptor represents the type of a field, parameter, local variable, or value.
-  - See the below table for possible field descriptors.+    * See the below table for possible field descriptors.
  
 ^ FieldType term ^ Type ^ ^ FieldType term ^ Type ^
Line 79: Line 142:
   - A method descriptor contains zero or more parameter descriptors, representing the types of parameters that the method takes, and a return descriptor, representing the type of the value that the method returns. Note this does not include the name.   - A method descriptor contains zero or more parameter descriptors, representing the types of parameters that the method takes, and a return descriptor, representing the type of the value that the method returns. Note this does not include the name.
   - For example the descriptor of <code>Object method(int i, double d, Thread t) {...}</code> is <code>(IDLjava/lang/Thread;)Ljava/lang/Object;</code>   - For example the descriptor of <code>Object method(int i, double d, Thread t) {...}</code> is <code>(IDLjava/lang/Thread;)Ljava/lang/Object;</code>
 +
 +== Synthetic members/constructs ==
 +  - In Java, synthetic members and constructs refers to constructs added by the Java compiler into the compiled bytecode that do not have a source code equivalent. For instance, an anonymous class is given synthetic ''final'' fields which are used to be able to reference values of the enclosing method the anonymous class is declared in.
 +      * Synthetic members may be targeted by Mixin, such as with ''@Shadow'' or an Accessor but will require carefully reading the relevant bytecode.
  
 ---- ----
  
 ==== Injectors ==== ==== Injectors ====
- 
-== Relevant external articles for this section == 
-Technical article on callback injectors, Mixin Wiki: [[https://github.com/SpongePowered/Mixin/wiki/Advanced-Mixin-Usage---Callback-Injectors|Advanced Mixin Usage; Callback Injectors]]\\ 
-MixinExtras Wiki: [[https://github.com/LlamaLad7/MixinExtras/wiki|MixinExtras Wiki Home Page]] 
- 
----- 
  
 == Injector == == Injector ==
-  - Most commonly, references a "callback injector". This consists of a "handler method" or "handler", which is the annotated method to inject. The method will contain annotations for metadata to specify where and how to inject a "callback" to the handler. This callback is a set of instructions added to the target method's bytecode that will call back to the merged handler method.+  - Also known as "callback injectors". Used through the form of annotations such as ''@Inject'' decorating a "handler" method. Upon the handler being merged, Mixin will use information specified within the injector's annotation to inject a set of "callback" instructions that will call back to the handler at a specific point. 
 +    * Typically only refers to injectors that can chain and do not remove the targeted operations, which excludes redirectors such as ''@Redirect''.
  
  
 == Handler method / Handler == == Handler method / Handler ==
-  - In the context of Mixins, a decorated method that will be merged and then invoked/called by a "callback" that will be injected based on the annotation's information. How this is done is highly dependent on the given injector.+  - In Mixins, a method decorated by an injector annotation and then merged into the target class. It is then invoked/called within "callback" instructions that will be injected by Mixin based on the annotation's information.
  
  
 == Callback == == Callback ==
-  - A series of injected instructions that will invoke the related handler method based on that method's injection point definition. The simplest injected callback is ''@Inject'''s callback who is mostly a plain method call at the injection point.+  - A series of injected instructions invoking the associated handler method based on that method's injection point definition. This can include but is not limited to, adding a single method call, creating an early return instruction, wrapping a method call. 
 + 
 + 
 +== CallbackInfo == 
 +  - An argument passed to an injector allowing to interact with the callback instructions. Notably, it may be "cancelled" to create an early return by making the [[https://jenkins.liteloader.com/view/Other/job/Mixin/javadoc/org/spongepowered/asm/mixin/injection/Inject.html|Inject]] cancellable. 
 +    * If the target method returns a value, the injector will instead be passed a ''CallbackInfoReturnable<R>'' where ''R'' is the return type. 
 +    * See the JavaDocs for the [[https://jenkins.liteloader.com/view/Other/job/Mixin/javadoc/org/spongepowered/asm/mixin/injection/callback/CallbackInfo.html|CallbackInfo]] and [[https://jenkins.liteloader.com/view/Other/job/Mixin/javadoc/org/spongepowered/asm/mixin/injection/callback/CallbackInfoReturnable.html|CallbackInfoReturnable]] classes.
  
  
 == Injection Point == == Injection Point ==
-  - An injection point is the primary value used by Mixin to determine where to insert the callback instructions for a given injector. Injection points are most often defined in the ''@At'' annotation's ''value'' field. Certain injection points are self-sufficient, such as ''"HEAD"'' (injects at the head of the target method), whilst others may necessitate more discriminators to have a specific target like ''"INVOKE"'' (injects before a method call, or targets the method call itself depending on the injector). Injection points are used to search for specific Bytecode operations within the boundaries of the target method.+  - An injection point is the primary value used by Mixin to determine where to insert the callback instructions for a given injector. Injection points are typically passed in the ''@At'' annotation's ''value'' field. Certain injection points are self-sufficient, such as ''"HEAD"'' as it will simply try and target the earliest possible point in the target method, whilst others may necessitate more discriminators to have a specific target like ''"INVOKE"'' which will need to specify the method whose call should be targeted. Injection points are used to search for specific Bytecode operations within the boundaries of the target method.
     - The injection point "reference" refers to the documentation of Mixin's built-in injection points. See [[https://github.com/SpongePowered/Mixin/wiki/Injection-Point-Reference|the Mixin Wiki's injection point reference page]].     - The injection point "reference" refers to the documentation of Mixin's built-in injection points. See [[https://github.com/SpongePowered/Mixin/wiki/Injection-Point-Reference|the Mixin Wiki's injection point reference page]].
-  - In some cases of common speech, injection point may refer to the specific point an injector's callback will be inserted, resulting both from an injection point and other discriminators.+  - In some cases, injection point may refer to the specific point an injector's callback instructions will be inserted, resulting both from an injection point and other discriminators. 
 + 
 + 
 +== WrapOp, @WrapOperation == 
 +  - Injector from MixinExtras, used primarily to replace or modify operations such as method calls, field get/set operations, etc. 
 +    * See [[https://github.com/LlamaLad7/MixinExtras/wiki/WrapOperation|the official Wiki page]] 
 + 
 + 
 +== MEV, @ModifyExpressionValue == 
 +  - Injector from MixinExtras, used to modify the resultant value of a very wide range of expressions and operations. 
 +    * See [[https://github.com/LlamaLad7/MixinExtras/wiki/ModifyExpressionValue|the official Wiki page]] 
 + 
 + 
 +== MRV, @ModifyReturnValue == 
 +  - Injector from Mixinextras, used to modify the return value of a method in a compatible fashion. 
 +    * See [[https://github.com/LlamaLad7/MixinExtras/wiki/ModifyReturnValue|the official Wiki page]] 
 + 
 + 
 +== Inject == 
 +  - (Verb) To use a Mixin injector to add to or modify existing operations. 
 +  - Reference to the ''@Inject'' injector, used to insert a method call to the handler at a desired point. 
 + 
 + 
 +== Local == 
 +  - (General programming) Value confined to the relevant scope. 
 +    - When working with Mixins, the relevant scope will be the target method and its locals. 
 +  - Reference to the ''@Local'' annotation from MixinExtras, used to be able to capture the values of locals within a handler method's parameters. 
 +    * See the [[https://github.com/LlamaLad7/MixinExtras/wiki/Local|official Wiki article]] 
 + 
 +== Capturing Locals == 
 +  - The process of using [[#local|@Local]] to capture one or more local variables within an injector's parameters. 
 + 
 + 
 +== Cancel, Cancellable == 
 +  - (Verb) In the context of injectors, means to cancel the remaining operations of the target method. 
 +  - (Annotation) Reference to the ''@Cancellable'' annotation from MixinExtras or a usage of it. Used to be able to cancel a target method without needing to use ''@Inject'' 
 +    * See the [[https://github.com/LlamaLad7/MixinExtras/wiki/Cancellable|official Wiki article]] 
 + 
 + 
 +== Share, Sharing == 
 +  - ''@Share'' annotation from MixinExtras and its usages. Used to share values between handler methods injecting into the same target method. 
 +    * See the [[https://github.com/LlamaLad7/MixinExtras/wiki/Share|official Wiki article]] 
  
 ---- ----
 +
 +==== Targeting Tools ====
 +Outside of [[#injection_point|Injection Points]], the Mixin toolchain provides different features that may be used to more precisely target a specific element of a target method matching the injection point. This is essential for making an injector less "[[#brittle|brittle]]", and making more precise changes which are more compatible. Note that different discriminators may be combined, such as using both an [[#expressions|expression]] and a [[#slice,_slicing|slice]] for the same injector if needed.
 +
 +
 +== Brittle ==
 +  - A "brittle" injector or targeting refers to a way of targeting a given element in a method in a manner that is unreliable or particularly likely to break with an update affecting an unrelated function.
 +
 +
 +== Slice, Slicing ==
 +  - Reference to the ''@Slice'' annotation and its usages. Slicing consists of defining a range within the target method in which to look for valid injection points.
 +
 +
 +== Expressions ==
 +  - Added in MixinExtras ''0.5.0'', a feature consisting of injection point ''"MIXINEXTRAS:EXPRESSION"'' and associated tools, such as ''@Expression'' and ''@Definition''. Used to allow injectors to target a very wide range of instructions in a target method by using java-like expressions closer to a source code representation. MixinExtras ''0.5.0'' is bundled with Fabric Loader 0.17.0 and later.
 +    - To "use an expression" may refer to using MixinExtras Expressions to target a certain piece of target code.
 +    * See [[https://github.com/LlamaLad7/MixinExtras/wiki/Expressions|the official wiki articles and tutorial.]]
 +
 +== MixinExtras Flowchart ==
 +  - An IDE feature added by the [#mcdev|MCDev plugin]] for IntelliJ, used to generate and display a set of flowcharts representing a class's bytecode as expressions. Used to match, debug and write [[#expressions|Expressions]].
 +
 +== @Definition ==
 +  - In the context of [[#expressions|expressions]], a "definition" is used to refer to ''@Definition'' annotation usages. Definitions are used to declare what individual identifiers within an expression correspond to in code, such as types, methods, or variables.
 +
 +== Wildcard ==
 +  - In the context of Expressions, a wildcard -- represented by the ''?'' character -- can be used instead of a defined identifier or a series of identifiers. Wildcards are able to stand in for any identifier and will match mostly anything that would otherwise be matched by an identifier in that part of the expression, and are useful to deliberately leave a part of an expression ambiguous.
 +
 +
 +== Ordinal ==
 +  - A discriminator which, between all valid targets once other filters and discriminators are applied, uses a zero-indexed value to select one of the remaining targets for the injector to target.
 +    * Ordinals are generally a more [[#brittle|brittle]] and less recommended discriminator for targeting using injectors. Using [[#slice,_slicing|slices]] or [[#expressions|expressions]] is recommended instead in cases where an ordinal would be only used as a disambiguation tool between different targets for an injection point.
tutorial/mixin_glossary.1759523666.txt.gz · Last modified: 2025/10/03 20:34 by bawnorton