======= Interface Injection =======

This is a new technique introduced by Loom 0.11 to add methods into a specific existing class.
More specifically, you can create an Interface, and then inject this interface into the class.
As result the target class will acquire all the methods of the interface, as if it always had them.
Interface injection is a compile time only feature, this means that a Mixin should also be used to implement the interface into the target class.

This is particularly useful for libraries, with this you can add new methods to existing classes and use them without the need of casting or reimplementing the interface every time.

Fabric API takes advantage of this technique. For example, ''TagBuilder'' implements ''FabricTagBuilder'', ''BlockEntityType'' implements ''FabricBlockEntityType'', so that you can directly use the instance methods in the Fabric API on the vanilla objects.

Let's explain better with an example:

The scope of this example is to add the following method into ''<yarn net.minecraft.class_3609>'' to get the sound of the bucket when emptied.
This, normally, is not possible because ''<yarn net.minecraft.class_3609>'' does not have a similar method.

<yarncode java [enable_line_numbers="false"]>
Optional<class_3414> getBucketEmptySound$myMod()
</yarncode>

To add the method into the class, first of all you need to create an interface with it:

<yarncode java [enable_line_numbers="false"]>
package net.fabricmc.example;

public interface BucketEmptySoundGetter {
	default Optional<class_3414> getBucketEmptySound$myMod() {
		return Optional.empty();
	}
}
</yarncode>

:!: The method body in the interface may not be used because it will be overridden by the mixin class. However, you must specify the method body, which means the method must be ''default''. You can make it return null or throw ''UnsupportedOperationException'', but you //cannot// make it abstract, such as ''Optional<yarn class_3414> getBucketEmptySound()'', or exceptions will be thrown when compiling!

ℹ️ It's highly recommended to add a dollar-character or underscore character with the mod name as the prefix or suffix of the method name, in order to avoid method name conflict with other mods.

Now you need to implement this interface into ''<yarn net.minecraft.class_3609>'' with a mixin implementing the interface:

<yarncode java [enable_line_numbers="false"]>
@Mixin(class_3609.class)
abstract class MixinFlowableFluid implements BucketEmptySoundGetter {
	@Override
	public Optional<class_3414> getBucketEmptySound$myMod() {
	    //This is how to get the default sound, copied from BucketItem class.
	    return Optional.of(((class_3609) (Object) this).method_15791(class_3486.field_15518) ? class_3417.field_15010 : class_3417.field_14834);
	}
}
</yarncode>

Lastly you need to inject the interface into ''<yarn net.minecraft.class_3609>''.
The following snippet can be added to your ''fabric.mod.json'' file to add one or more interfaces to the ''<yarn net.minecraft.class_3609>'' class.
Note that all class names here must use the "internal names" that use slashes instead of dots (''path/to/my/Class'').

<code json fabric.mod.json [enable_line_numbers="false"]>
{
	"custom": {
		"loom:injected_interfaces": {
			"net/minecraft/class_3609": ["net/fabricmc/example/BucketEmptySoundGetter"]
		}
	}
}
</code>

Now you can use the new method:

<yarncode java [enable_line_numbers="false"]>
Optional<class_3414> sound = mytestfluid.getBucketEmptySound$myMod();
</yarncode>

You could also override this method in classes extending ''<yarn class_3609>'' to implement custom behaviours.

Sometimes, your interface injections may need to include the ''$'' symbol, but the Groovy template processor may interpret this as a template variable if you are replacing variables (such as ''${version}'') in your ''fabric.mod.json''. A workaround for this is to use the Unicode escape for ''$'', which is ''\u0024''.