Fabric Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
:!: //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!//

====== Mixin Glossary (DRAFT) ======

===== 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.\\
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 -- mainly MixinExtras currently -- 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.\\
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//

----

//TODO: Probably add subsections depending on the terms?//\\
FIXME //This is under heavy construction and probably contains inaccuracies, likely redundancies, certainly inefficient definitions and most definitely is missing relatively important terms//
===== Definitions =====

==== General/Misc. Terms ====

== Mixin, Mixins ==
  - 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.


== 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]].


== To mix into, to Mixin to ==
  - Expressions referring to using Mixin to modify a target. For instance, "mixing into ServerLevel" would mean using a Mixin to modify the ''ServerLevel'' class.


== Bytecode 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.

----

==== 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 ==
  - Most commonly, references a "callback injector", which consists of an annotated "handler" method that will be merged by a Mixin Class, with a callback to the merged method (known as the handler method) at a specified injection point defined within the handler method's annotation. This most often does not include Redirectors, as redirectors cannot chain with one another and do not preserve the original target code.


== 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.


== 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.


== 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.
    - 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.

----