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.
====== Mixins and Obfuscation (DRAFT) ======

===== What is Obfuscation? =====

Obfuscation refers to a process used by Mojang up until 26.1, in which the names in the game's code were made obfuscated, in other words were scrambled to be meaningless. In order to get around this and be able to mod with meaningful names, the MC modding community has been using mappings, including mainly Yarn mappings, a libre-licensed set of mappings developed by and mainly for Fabric until obfuscation was dropped, and Mojang/"official" mappings, provided by Mojang directly. Remapping is the process of converting a set of named references and declarations of classes, methods and fields, and changing them to match a certain set of mappings.

This matters as it pertains to Mixins, as on obfuscated versions the mappings will likely not match between the development environment and runtime, and we still want to be able to reference method names, among other things, by the names as they appear in source code. For Fabric's case, the runtime mappings will be intermediary mappings, which follow a pattern of ''field_XXXX'', ''method_XXXX'' or ''class_XXXX''.

Note this is an oversimplified overview of obfuscation and the remapping process for the sake of explaining how it relates to Mixins.


==== Which MC versions are not obfuscated? ====

Minecraft is obfuscated up to and including 1.21.11, meaning that the first unobfuscated versions will be 26.1 and its snapshots. An easy way to remember it is that MC versions are obfuscated up until the change to the new versioning scheme.

Unobfuscated versions will no longer require any obfuscation mappings or remapping, meaning that MC code will be targetable in roughly the same ways as any other Java library present at runtime and not loaded before Mixin.

==== Are mods Obfuscated? ====

The short answer is no, mods are not obfuscated. //However// an important thing to note is that obfuscated methods will still need remapping even if targeting an override within a non-obfuscated class. This is typically seen with MC method overrides in another mod.


===== Writing Mixins and Obfuscation =====

==== The Mixin Refmap and the Annotation Processor ====

The refmap is used by Mixins to map meaningful names in Mixin classes to runtime mappings.

In current versions of Loom, the annotation processor is disabled entirely and no refmap is needed as Loom remaps Mixins in-place to match runtime targets. However, if you encounter issues with Loom's remapping, the following can be added to your ''build.gradle'' file to re-enable the Mixin AP:
<code groovy>
loom {
    mixin {
        useLegacyMixinAp = true
    }
}
</code>

Even with the Mixin AP enabled, the refmap and remapping of Mixins is handled for you, and there is no need to do additional setups for a refmap or the AP.


==== Toggling Mixin Remapping ====

By default on obfuscated versions, Mixin classes have remapping enabled for every injector, if you are targeting unobfuscated targets, there are two scopes to turn remapping on or off:  
  * The entire Mixin class via ''@Mixin(value = TargetClass.class, remap = false)''
  * Per-injector, via the ''remap = true/false'' attribute on the injector's annotation. If not specified per injector, the Mixin class's setting will be used.

Remapping should be set to false when targeting unobfuscated targets, which includes most mods' methods, but excludes overrides of obfuscated code, such as an override of an MC method in a mod's class.

==== Local Capture ====

The standard method of capturing local variables in a target method is via MixinExtras' [[https://github.com/LlamaLad7/MixinExtras/wiki/Local|@Local]], and whilst it does provide a way to capture variables by name via ''@Local(name = "...")'', that does not work on obfuscated versions. Instead, it requires using an ordinal, which refers to which local to capture within the set of locals with matching discriminators like type, or the Local Variable Table index if ordinals fail.

The reason this is an issue is because of ordinals and especially indices being "brittle", meaning they are likely to be unreliable or break between updates. For example if there are five variables of the type you wish to capture in the target method, your ordinal will suddenly target a different variable if a variable of the same type was added before it or the order of the variables before it was changed in any way. Even worse, this can cause silent failures and bugs that do not throw an error.

This means that when targeting obfuscated methods, one should avoid directly capturing locals when possible. Certain injectors such as ''@WrapOperation'' may be used to capture the value of a local at a given point, allowing to get a value without having to sometimes resort to very brittle local capture. Whether this is advisable will vary on the situation.

Unobfuscated targets such as post-1.21.11 MC or mods allow targeting local variables by name, which gives a much more expressive option for targeting locals that is not nearly as brittle.