| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| drafts:mixin_glossary [2025/12/12 01:47] – [Targeting Tools] Fix Mixin Flowcharts link to MCDev definition - pointed out by skycatminepokie gauntrecluse | drafts:mixin_glossary [2026/01/01 13:14] (current) – Add link to Java Bytecode Docs page under Bytecode segment gauntrecluse |
|---|
| ====== Mixin Glossary (DRAFT) ====== | ====== Mixin Glossary (DRAFT) ====== |
| |
| ===== 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 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 it will be attempted to use feedback 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]] page for an introduction to the concept. |
| |
| ---- | ---- |
| |
| == 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. |
| |
| |
| == 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 method 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. |
| |
| |
| |
| == 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. |
| |
| |
| ==== 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 == |
| - 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. | - 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. | * 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]]%%'' |
