Mixin: choosing the right tool (DRAFT)

This page should be read after having already read the Mixin Introduction page.

Mixins are a tool that is, by virtue of modifying potentially vastly different targets, a tool that changes its usage on a case-by-case basis. As such, which tool is right for the job, if Mixin is fitting in the first place, will change for every single case. This page will attempt to document the process of choosing which tool to use based on common situations encountered relating to Mixins.

Sometimes, the goal to be fulfilled is simply not something Mixin is fit for. A good rule of thumb to avoid creating unnecessary Mixins is to only use them when other options such as existing events and other tools integrated into the modding framework are insufficient or greatly impractical. In other words, Mixin is not a first resort tool.

A very frequent use case for Mixins is to “listen” for a specific operation in code, and react to it. Modloaders, however, typically already have a large amount of events built into them. As such, when trying to “listen” to a given action in Vanilla code, a dev should first search through the relevant events of their modding framework.

This is however not the only case where events are the better option. For instance, say you wanted to add functionality upon interacting (most often via right clicking) a block that is registered as a Block. One may want to use a Mixin to register it as a custom class to give it all sorts of functionality. However, if the only desirable trait is to do something when right clicking on it, it may be relevant to instead consider using the modding framework's event for interacting with blocks, and checking if the block interacted with is the one we wish to add a functionality to.
It may be unintuitive at first, however the reason this may be an approach to consider is that changing the class it is registered as can cause a lot of issues for other mods who may want to do a similar action, or for mods that may rely on that block being the class it is registered as. Changing the registration class via Mixin would have ripple effects and likely cause issues. At that point, it may not be worth using Mixin anymore.

Do not use Mixins when there are ways for events or other non-Mixin tools to substitute them in a way that is less intrusive and/or incompatible. This fits into the broader principle that Mixins need to, when they must be used, be used in the most precise way as to cause the least potential issues.

As Mixin's set of tools evolved with updates and the additions of MixinExtras, some features have becomes significantly less useful as time went on. This section will cover tools that are almost never recommended for modern Mixin work.

A method overwrite, done via @Overwrite is practically never the right solution. There are ways to target nearly any element of a given method, and method overwrites are extremely intrusive and incompatible. If you believe an overwrite is the right tool for your situation, it is heavily recommended to first ask for second opinions as it is likely you have made a mistake in your thought process.

Redirectors, or “redirect injectors”, are able to redirect operations and constants in a target method to a custom value or operation to replace the target with. Redirectors consist primarily of @Redirect and @ModifyConstant. This has the major downside that redirecting cannot chain, meaning that only one mod may redirect a given target. This makes it inherently less compatible than alternatives able to apply similar modifications with chaining abilities, notably @WrapOperation and @ModifyExpressionValue, which can be chain with one another.
This makes redirectors only useful if one wishes to specifically leverage the lack of chaining, such as causing a hard incompatibility with any other mod trying to redirect the same target.

The primary use-case of Mixins is to modify something within a target class. This is mainly done via injectors, however, using the injector best suited for the job ensures a more compatible and often easier to maintain solution. This section aims to provide advice on which common situations typically call for which injectors and tools. This is however not exhaustive and not meant to be absolutely prescriptive, you should rather use this page to learn the general use-cases of certain injectors to then be able to apply it to your own situations.

A common use-case for Mixins is adding your own operations into an external class's methods. In a lot of cases, this can be covered by @Inject, which can mainly be used to add a call to its annotated handler method.