Differences

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

--- tutorial:introduction [2019/11/03 14:20] – [Mixins] layl
+++ tutorial:introduction [2019/11/03 23:07] – [Third Party APIs] layl
@@ Line 47: / Line 47: @@
 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.
-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 lists of [[documentation:libraries|third party libraries]] on this wiki.
+===== Mixins =====
+Finally, you can use mixins.
+Mixins are a powerful feature that let 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, you should never use these
+This is not a complete list, but rather a quick overview.
+Some mixin types are omitted here.
+==== Adding Interfaces ====
+This is probably the safest way 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.
+==== 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 and increase the risk of conflicts.
+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 method injections, **strongly** prefer additions over "@Overwrite"-ing methods entirely.
+Avoid overwrites completely.
-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, please use something else.