Differences

This shows you the differences between two versions of the page.

--- tutorial:mixin_registration [2020/06/08 21:26] – created lvanderzande
+++ tutorial:mixin_registration [2025/09/23 15:35] (current) – Rephrased naming convention section for mixin interfaces to no longer imply the I prefix for interfaces is standardized. Minor rephrasings. Fix internal link to accessor page containing "&" rather than "&" gauntrecluse
@@ Line 3: / Line 3: @@
 ==== Introduction ====
-In this example, you will learn how to register your Mixins through the ''%%resources/fabric.mod.json%%''.
+In this tutorial, you will learn how to register your Mixins through the ''%%resources/fabric.mod.json%%''.
 Inside your ''%%resources%%'' folder is where your ''%%fabric.mod.json%%'' should be.
@@ Line 19: / Line 19: @@
 {
   "mixins": [
-    "modid.mixins.json",
+    "modid.mixins.json"
-    {
-      "environment": "client",
-      "config": "modid.client.mixins.json"
-    }
   ]
 }
 </code>
-Providing a String ''%%"<modid>.mixins.json"%%'' inside the mixins array tells Fabric to load the mixins defined inside the file ''<modid>.mixins.json'' on **both client and server**.
+Providing a String ''%%"<modid>.mixins.json"%%'' inside the mixins array tells Fabric to load the mixins defined inside the file ''<modid>.mixins.json''.
-Providing an Object allows for deeper customization.
-Taking a closer look at the Object from lines 4 to 7:
-<code json>
-{
-  "environment": "client",
-  "config": "modid.client.mixins.json"
-}
-</code>
-The ''%%environment%%'' field is set to 'client'. Which lets Fabric know we want these mixins to only be loaded on the client.
-The ''%%config%%'' field should point to the file where all the mixins for that ''%%environment%%'' are defined.
 ==== Register Mixins ====
-In the previous section, you learned about registering your client/server ''<modid>.mixins.json'' and environment specific ''<modid>.<environment>.mixins.json'' files.
+In the previous section, you learned about registering your ''<modid>.mixins.json'' files.
 We still have to define which mixins to load and where these mixins are located.
-Inside your registered ''<modid>.<environment>.mixins.json'':
+A typical ''mixins.json'' file for 1.21.x development might look like this:
 <code json>
@@ Line 59: / Line 39: @@
   "minVersion": "0.8",
   "package": "net.fabricmc.example.mixin",
-  "compatibilityLevel": "JAVA_8",
+  "compatibilityLevel": "JAVA_21",
   "mixins": [],
   "client": [
     "TitleScreenMixin"
   ],
+  "server": [],
   "injectors": {
     "defaultRequire": 1
+  },
+  "overwrites": {
+    "requireAnnotations": true
   }
 }
 </code>
-The **2** main fields you should worry about when getting started with mixins are the ''package'' field and ''client'' array.
+The **4** main fields you should worry about when getting started with mixins are the ''package'' field, and the ''mixins'', ''client'', ''server'' arrays.
+  * The ''package'' field defines which folder (package) to find the Mixins in. That package and its subpackages should be dedicated to Mixins, and nothing else.
+  * The ''mixins'' array defines which classes should be loaded on both the **physical** client and **physical** server. Mixin Classes should be referenced by their file/class name when registered in your config. The naming convention is ''<TargetClass>Mixin'' for most Mixins and ''<TargetClass>Accessor'' for [[tutorial:mixin_accessors|Mixin Accessors & Invokers]]. Some may also prefer using the ''I'' prefix for interfaces, but it is not standardized.
+    * The ''client'' array defines which classes should be loaded only on the **physical** client. A physical, dedicated server will never interact with client-exclusive classes. So Mixins targeting client-sided classes should go in this field.
+    * The ''server'' array defines which classes should be loaded only on the **physical** server.
+Following that logic: ''net.fabricmc.example.mixin.TitleScreenMixin'' is the mixin class that will be loaded on the client.
+The other fields' rough function should also be kept in mind to understand when to change them from their defaults, and to understand what happens when another mod you're inspecting changes them:
-The ''package'' field defines which folder (package) to find the Mixins in.
+  * The ''required'' field holds a boolean value that corresponds to whether or not Mixin should crash if this config and its Mixins fail to apply or fail to find their targets. Injector Mixins have their own requirement value that precedes this.
+  * ''minVersion'' defines the minimum Mixin version that must be present and used to apply the config's Mixins.
+  * ''compatibilityLevel'' defines the minimum compatibility level that the Mixin sub system must be set to in order to apply the config's Mixins. It should generally be set to the Java level used by your MC version unless you specifically have a reason not to (e.g. ''JAVA_17'' for 1.20.1, ''JAVA_21'' for 1.21.x) Mixin will try to set itself to the highest version found in that field across the different configs it interacts with during launch.
+  * ''injectors'' holds a group of fields that define the settings for injector Mixins.
+    * The main one to keep in mind is ''defaultRequire'', which is by default 1. This setting controls the amount of targets injectors must match by default to not crash. By setting this to 0, you effectively make injectors not required by default. Injector annotations such as ''@Inject'' have an optional ''require'' parameter that overrides the config setting. Both the injector-specific setting and the config setting precede the ''required'' field in the config.
+  * ''overwrites'' holds a group of fields that define the settings for overwrite Mixins.
+    * The main one to keep in mind is ''requireAnnotations'' which holds a boolean value that, when set to true, makes Overwrite methods always require a corresponding annotation to overwrite the target class method. There is hardly ever a reason to set it to false.
-The ''client'' array defines which classes should be loaded.
+There are other fields that can optionally be added, most of which only serve specific purposes that are outside of the scope of a general explanation. There is, however, one that is relevant for MixinExtras:
+  * ''mixinExtras'', similarly to ''injectors'' holds a group of fields that serve as settings for MixinExtras specific behavior. Mainly, it allows to set up a separate ''minVersion'' value for MixinExtras. Doing this is required for setting up Expressions introduced in MixinExtras 0.5.0 (see the [[https://github.com/LlamaLad7/MixinExtras/wiki/Expressions-Setup|dedicated page on MixinExtras' wiki]]), but it also sets the version MixinExtras should behave as for your mod's purposes. It is //recommended// that you fill this field yourself even if you don't use Expressions to lessen the chances of issues arising from MixinExtras trying to behave as the wrong version when interacting with your mod.
-Following that logic: ''net.fabricmc.example.mixin.TitleScreenMixin'' is the mixin.
+:!: It is fine, especially if you are a beginner, to not necessarily understand the above fields fully. You should ask in the Fabric or SpongePowered Discord about clarifications on any of the concepts or fields you do not understand from this page. It may help improve your overall Mixin comprehension, and will help you have a more complete understanding of the Mixin subsystem.
+----
+For further reading, check out the [[https://jenkins.liteloader.com/view/Other/job/Mixin/javadoc/index.html|Mixin Javadoc]], given specifics here can vary based on version, it may be best to read the JavaDoc from your specific build. (On IntelliJ IDEa) you can middle click on a field in the settings to be taken to the corresponding class that handles that field. See [[tutorial:reading_mc_code|Reading the Minecraft source]] for general setup for reading external source code, including both MC and libraries, APIs or subsystems like Mixin.