Fabric Wiki

User Tools

Site Tools

Trace:
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/11/29 03:42] – gauntreclusetutorial:mixin_glossary [2026/02/26 08:59] (current) – Added MixinSquared entry gauntrecluse
Line 1: Line 1:
-:!: //this page is a draft! Feedback is appreciated but the page is currently not ready to be read by users of the Wiki!//+:!: This page was recently pushed out of drafting, it may still contain errors or inaccuracies. Direct [[#contributing|contributions]] and feedback in the ''#wiki'' channel of the Fabric Discord are both welcome.
  
-====== Mixin Glossary (DRAFT) ======+====== Mixin Glossary ======
  
-===== Preamble ===== +===== About This 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. +
- +
-==== Contributing ==== +
- +
-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 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. +
- +
-=== Formatting and TODOs === +
- +
-When you are doubtful on a term's definition, add a %%FIXME%% above the relevant text with text in //italics// until a more confident definition can be found. Definitions should generally take the form of itemized lists with the term above the list's first items. Synonyms should be grouped together. Footnotes references describing the same resource and so on should use the **exact** same text so that they both redirect to the same footnote. +
- +
-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 page aims to address terms, acronyms, abbreviations, expressions, etc. and define them 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.\\
 +It is advised to read the [[tutorial:mixin_introduction|Introduction to Mixins]] page for an introduction to the concept, and frequently ask for advice.
  
 ---- ----
  
-:!: //This is under heavy construction and probably contains inaccuracies, likely redundancies, certainly inefficient definitions or may be missing important definitions.// 
 ===== Definitions ===== ===== Definitions =====
  
Line 50: Line 20:
  
 == Anonymous Class == == 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.+  - A nameless local class declared and instantiated at the same time. Anonymous classes may be declared within a method's body, such as to assign its instance to a local variable, or assigned to fields in an outer class. 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, such as an [[#anonymous_class|anonymous class]] or a [[#lambda_function,_lambda_method|lambda 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 == == Encapsulating Class, Outer Class ==
   - The class containing the relevant subject, often an inner class such as an [[#anonymous_class|anonymous class]].   - The class containing the relevant subject, often an inner class such as an [[#anonymous_class|anonymous class]].
 +
 +
 +== Composition ==
 +  - The action of wrapping an object, most often a lambda, into a bigger one of the same type. With mixins, this is often done instead of injecting at the head and/or tail of a lambda method. This avoids needing to inject into a lambda's synthetic method in bytecode directly, and is considered less brittle.
 +
  
 == Mixin, Mixin 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" 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.+  - "a Mixin" or "a Mixin Class" refers to classes or interfaces that are annotated with ''@Mixin'', and will be merged with a [[#target_class|target class]] as a means to transform it. Non-accessor Mixins will not be available at runtime due to the merging process.
  
  
 == Target Class == == Target Class ==
-  - A class with contents being targeted by the relevant Mixin Class's transformations.+  - A class which a [[#mixin,_mixin_class|Mixin Class]] targets via the ''@Mixin'' annotation in order to transform and modify its methods.
  
  
 == Target Method == == Target Method ==
-  - A method within a [[#target_class|target class]] being targeted by transformations from a Mixin class.+  - A method within a [[#target_class|target class]]. Target methods are modified by using [[#injectors|injectors]] to modify individual elements and operations within them or add new elements.
  
  
 == 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, means to merge most of the members and new interface implementations from a given Mixin class into its target class's bytecode. The merging process is usually accompanied by modifications to existing members in the target class.
  
  
Line 80: Line 56:
  
 == Double-Casting == == 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.+  - 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 == == 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 an [[tutorial:mixin_accessors|Accessor Mixin]], or in other words a Mixin which is always an interface, composed purely of ''@Accessor'' and ''@Invoker'' Mixins, with the goal of accessing or mutating otherwise inaccessible fields or methods in a target class. Accessor Mixin interfaces are accessible by the rest of a mod's codebase, unlike most other Mixin classes, which are merged into the target class and thus become inaccessible.
   - 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.   - 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 == == 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]].   - 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 95: Line 70:
   - 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]].   - 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]].
  
 +
 +== MixinSquared ==
 +  - A specialized library for Mixin. MixinSquared focuses on providing ways to modify other mods' mixin classes and potentially cancel them. It must be included by individual mods, as it is not bundled in Fabric Loader. MixinSquared should only be used when it is not reasonable or feasible to integrate the changes into a target mod directly, such as with a pull request or raising an issue.
 +    * See the [[https://github.com/Bawnorton/MixinSquared/wiki|official MixinSquared Wiki]] for how to include it into your mod and use it.
  
 == To mix into, to Mixin to == == To mix into, to Mixin to ==
Line 112: Line 91:
  
 ==== Bytecode ===== ==== Bytecode =====
 +
 +For a more thorough look at JVM Bytecode, see [[https://docs.fabricmc.net/develop/mixins/bytecode|the Docs Page]].
  
 == As opposed to Source code == == As opposed to Source code ==
   - Bytecode is a set of less readable, computer-oriented instructions, which code running on the Java Virtual Machine will be compiled into. Mixin works with bytecode as opposed to "Source" code, both for the Mixins to be applied and the code to target, "source" code being the decompiled/pre-compilation code, and as such, whilst source code can be used to infer bytecode, one should always prioritize bytecode for precise targeting or for certain targets which may not be reliably in the same position or order in the bytecode compared to a decompilation. See [[tutorial:reading_mc_code|Reading the Minecraft source]]'s relevant section on bytecode.   - Bytecode is a set of less readable, computer-oriented instructions, which code running on the Java Virtual Machine will be compiled into. Mixin works with bytecode as opposed to "Source" code, both for the Mixins to be applied and the code to target, "source" code being the decompiled/pre-compilation code, and as such, whilst source code can be used to infer bytecode, one should always prioritize bytecode for precise targeting or for certain targets which may not be reliably in the same position or order in the bytecode compared to a decompilation. See [[tutorial:reading_mc_code|Reading the Minecraft source]]'s relevant section on bytecode.
- 
----- 
  
 == Signatures == == Signatures ==
Line 134: Line 113:
 | I | int | | I | int |
 | J | long | | J | long |
-| L ClassName ; | Named class or interface type |+| L ClassName ;  | Named class or interface type |
 | S | short | | S | short |
 | Z | boolean | | Z | boolean |
Line 145: Line 124:
 == Synthetic members/constructs == == 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.   - 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.+      * Synthetic members may be targeted by mixins, but often require reading the bytecode.
  
 ---- ----
Line 161: Line 140:
  
 == Callback == == Callback ==
-  - 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.+  - 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 or expression, etc.
  
  
Line 215: Line 194:
   - ''@Share'' annotation from MixinExtras and its usages. Used to share values between handler methods injecting into the same target method.   - ''@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]]     * See the [[https://github.com/LlamaLad7/MixinExtras/wiki/Share|official Wiki article]]
- 
  
 ---- ----
  
 ==== 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 useful for making an injector less "[[#brittle|brittle]]", and making it +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 == == 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.+  - 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 modifying something functionally unrelated to the mixin.
  
  
Line 232: Line 210:
  
 == Expressions == == 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. +  - Added in MixinExtras ''0.5.0'', a feature consisting of the ''"MIXINEXTRAS:EXPRESSION"''  injection point 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.]] 
-    * See [[https://github.com/LlamaLad7/MixinExtras/wiki/Expressions|the official wiki articles]]+
  
 == MixinExtras Flowchart == == 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]].+  - 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 == == @Definition ==
-  - In the context of 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.+  - 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 == == Wildcard ==
Line 247: Line 227:
  
 == 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. 
 + 
 + 
 + 
 +===== Contributing ===== 
 + 
 +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 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. 
 + 
 +=== Formatting and TODOs === 
 + 
 +When you are doubtful on a term's definition, add a %%FIXME%% above the relevant text with text in //italics// until a more confident definition can be found. Definitions should generally take the form of itemized lists with the term above the list's first items. Synonyms should be grouped together. Footnotes references describing the same resource and so on should use the **exact** same text so that they both redirect to the same footnote. 
 + 
 +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]]%%''
tutorial/mixin_glossary.1764387765.txt.gz · Last modified: 2025/11/29 03:42 by gauntrecluse