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/16 11:46] – Add targeting tools section; Add misc. definitions; minor tweaks gauntreclusetutorial:mixin_glossary [2025/11/29 03:49] (current) – gauntrecluse
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]]%%''
 +
  
 ---- ----
  
-:!: //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 ====
  
-FIXME //The defs for lambda funs and anon classes are really barebone so far and should be improved.// +== Lambda Function, Lambda Method == 
-== Lambda Functions == +  - 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]]. 
-  - (Java) Unnamed function that can be defined within a method body, 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. Lambdas must be mixed into separately from the rest of the encapsulating class's methods.+  * For a more thorough technical definition, see [[https://docs.oracle.com/javase/tutorial/java/javaOO/lambdaexpressions.html|the official Oracle Documentation]].
  
  
-== Anonymous Classes == +== Anonymous Class == 
-  - A nameless inner class declared and instantiated a single time. As with any inner class, anonymous classes must be mixed into specifically rather than outer classes.+  - 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 == == Enclosing Method ==
-  - The method containing the relevant subject. For instance, an anonymous class or lambda's 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 == == Mixin, Mixin Class ==
Line 52: Line 69:
  
 == Target Method == == Target Method ==
-  - A method within a target class being targeted by transformations from a Mixin class.+  - 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 Mixin, merging most of members and new interface implementations 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]].
 +
  
  
Line 124: Line 157:
  
 == Handler method / Handler == == Handler method / Handler ==
-  - (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.+  - 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 invoking the associated handler method based on that method's injection point definition.+  - 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.
  
  
Line 145: Line 184:
   - Injector from MixinExtras, used to modify the resultant value of a very wide range of expressions and operations.   - 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]]     * 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]]
  
  
Line 157: Line 201:
   - Reference to the ''@Local'' annotation from MixinExtras, used to be able to capture the values of locals within a handler method's parameters.   - 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]]     * 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.
  
  
Line 173: Line 220:
  
 ==== Targeting Tools ==== ==== 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 == == Slice, Slicing ==
-  - Reference to the ''@Slice'' annotation and its usages, used to narrow the scope of the injector to be between two points within the target method.+  - 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 == == Expressions ==
-  - Added in MixinExtras 0.5.0; a tool consisting of injection point ''"MIXINEXTRAS:EXPRESSION"'' and associated tools. Used to allow injectors to target a very wide range of expressions in a target method. MixinExtras 0.5.0 is bundled with Fabric Loader 0.17.0 and later. +  - 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 with an injector. +    - To "use an expression" may refer to using MixinExtras Expressions to target a certain piece of target code. 
-    * See the [[https://github.com/LlamaLad7/MixinExtras/wiki/Expressions|official wiki articles]]+    * 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 == == Ordinal ==
-  - Zero-indexed integer value used to select a single target within the list of potential targets based on other discriminators and targeting tools. An ordinal of 0 would target the first of the potential targets by order of appearance in bytecode, for instance. +  - 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 and less recommended discriminator for targeting using injectors.+    * 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.1760615207.txt.gz · Last modified: 2025/10/16 11:46 by gauntrecluse