Differences

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

--- tutorial:introduction [2019/11/03 14:03] – created layl
+++ tutorial:introduction [2023/09/13 21:20] (current) – ↷ Links adapted because of a move operation 2001:8a0:f4d2:c700:98c:bb27:6ad8:1dab
@@ Line 1: / Line 1: @@
-====== Introduction to Modding with Fabric (DRAFT) ======
+====== Introduction to Modding with Fabric ======
 This is a quick introduction to some common techniques you can use while making Fabric mods.
@@ Line 11: / Line 11: @@
 Mixins can be fragile, and at times can cause conflicts.
 Therefore, some common functionality has already been implemented by the Fabric API for you.
-If it doesn't exist in the core Fabric API, often it will exist in a third party library.
+If it doesn't exist in the core Fabric API, often it will exist in a third-party library.
-In almost every situation it's preferable to use either the Fabric API, or a third party library over implementing a mixin yourself.
+In almost every situation it's preferable to use either the Fabric API or a third party library over implementing a mixin yourself.
 Sometimes though, you don't need any of that.
@@ Line 23: / Line 23: @@
 If Minecraft already lets you do something, don't re-invent the wheel.
-A good example of this is the "Registry" class, which lets you add blocks and items without any modifications to Minecraft's code.
+A good example of this is the "<yarn class_2378>" class, which lets you add blocks and items without any modifications to Minecraft's code.
-Minecraft will also load in the JSON data files from your mod.
+Minecraft also uses JSON data files for various data-driven features.
-These files are used for anything data-driven, where code isn't necessary in the first place.
+You can add JSON files to your mod, which are then injected by the Fabric API.
 For example, block models and loot tables are implemented through JSON files.
@@ Line 40: / Line 40: @@
 You can find out what's included in the Fabric API by looking over [[https://github.com/FabricMC/fabric|its source code on GitHub]].
-The Fabric API contains a lot of common event hooks, and general utilities for things like networking and rendering.
+The Fabric API contains a lot of common event hooks and general utilities for things like networking and rendering.
@@ Line 46: / Line 46: @@
 Because the Fabric API is intentionally kept small and focused, third party APIs exist to fill in the gaps.
-Mixins allow any third party library to affect Minecraft's code just as much as the core Fabric API can.
+Mixins allow any third party library to affect Minecraft's code in the same way as the core Fabric API can.
-You should use these instead of writing your own mixins where possible to minimize the possibility for conflicts.
+You should use these instead of writing your own mixins where possible to minimize the possibility of conflicts.
-A good example of this is [[https://github.com/cottonmc|Cotton]], which provides a variety of common utilities, as well as common resource ores, items and blocks.
+You can find an incomplete list of [[community:library_mods|third party libraries]] on this wiki.
+===== Mixins =====
+Finally, you can use mixins.
+Mixins are a powerful feature that lets you change any of Minecraft's own code.
+Some mixins can cause conflict but used responsibly these are key to adding unique behavior to your mod.
-===== Mixins =====
+Mixins come in a variety of flavors, in rough order of preference:
+  * Adding Interfaces
+  * Callback Injectors
+  * Redirect Injectors
+  * Overwrites
+This is not a complete list, but rather a quick overview.
+Some mixin types are omitted here.
+==== Adding Interfaces ====
+This is probably one of the safest ways to use mixins.
+New interface implementations can be added to any Minecraft class.
+You can then access the interface by casting the class to it.
+This doesn't change anything about the class, it only adds new things, and is therefore very unlikely to conflict.
+One caveat is that the function signature (name + parameter types) you inject must be unique. So if you use common parameter types, be sure to give it a very unique name.
+==== Callback Injectors ====
+Callback injectors let you add callback hooks to existing methods, as well as on specific method calls within that method.
+They also let you intercept and change the return value of a method, and return early.
+Callback injects can stack, and are therefore unlikely to cause conflicts between mods.
+==== Redirect Injectors ====
-Finally, if all other methods have failed, you can use mixins.
+Redirects let you wrap method calls or variable access within a target method with your own code.
-These are not to be taken lightly, they can make debugging a lot harder.
+Use these very sparingly, a target call or access can only be redirected once between all mods.
-But, if you need to affect Minecraft's core functionality in a way no other previously mentioned method lets you, this is the way to do it.
+If two mods redirect the same value, that will cause a conflict.
+Consider callback injects first.
-Mixins allow you to add any code you want to existing Minecraft classes and methods.
-The example project already comes with an example mixin that injects itself into the "MinecraftClient#init" method.
-If you can, prefer adding interfaces to classes over injecting into existing methods.
+==== Overwrite ====
-This will let you access the class in ways not previously allowed by casting an instance of it to your interface.
-By preferring adding interfaces, you minimize the risk of conflicts by purely adding something to the class rather than changing it.
-If you do have to use injections, **strongly** prefer additions over overwrites.
+Be very careful with how you use Overwrites.
-Overwrites are the most likely to conflict with other mods and in most situations you do not need them.
+They replace a method entirely, removing all existing code and conflicting with any other types of mixins on the method.
-You can inject code into any part of a method, including wrapping inner method calls and canceling them.
+They are extremely likely to conflict not just with other mods, but also with changes to Minecraft itself.
+You most likely do not need an overwrite to do what you want to do.