Fabric API Provider

[grondag]

Replaces #1067

This module allows API instances to be associated with game objects without specifying how the association is implemented. This is useful when the same API could be implemented more than once or implemented in different ways.

For example, a fluid API might be implemented for a block in the following ways:

• Using BlockState and some kind of wrapper (A vanilla cauldron implementation might do this)
• Directly in a BlockEntity for a simple tank
• As a more complicated data structure for a multi-block tank
• As one of several instances within a machine block containing multiple fluid buffers

This variation is managed by a mapping function given when an API provider is registered. The provider interface
is meant to be extended as needed to handle a given use case. (Sidedness, instance ID, permissions, etc)

Once registered, API providers can be retrieved without any knowledge of the API or provider implementations, and then used according to the contract of the provider to obtain an API instance.

Note that this model allows API providers to be associated with game objects that don't natively support them. This will require a wrapper or data attachment facility (or mixins) to be effective in most cases, all of which are outside the scope of this module. However, the decoupling of retrieval from implementation affords maximum flexibility for implementors.

This module could easily extended to cover additional game objects and probably should be if accepted.

This module could be implemented with slightly more efficiency if a data attachment facility were available, but that is left for another day.

Here is a simple (and silly) example of usage:

// The API we want to expose
interface Boop {
	void boop();
}

// Our absent provider
static final Boop NO_BOOP_FOR_YOU = () -> {};

// Our provider interface - in this case we don't rely on block entity
// Illustrates how providers can add the access parameters they need
@FunctionalInterface
interface BoopProvider extends ApiProvider<BoopProvider, Boop> {
	Boop getBoop(Direction side, PlayerEntity player);

	@Override
	default Boop getApi() {
		return NO_BOOP_FOR_YOU;
	}
}

// Our singleton provider access mapping function - real examples would usually get/create providers from game state
static final BoopProvider HAVE_A_BOOP_MAYBE = (side, player) -> (side == Direction.UP && player.isSneaking()) ? () -> System.out.println("Boop! Side = " + side.toString()) : NO_BOOP_FOR_YOU;

// Registration of our access along with our absent provider 
public static final BlockApiProviderAccess<BoopProvider, Boop> BOOP_ACCESS = BlockApiProviderAccess.registerAcess(new Identifier("boop:boop"), Boop.class, (side, player) -> NO_BOOP_FOR_YOU);

// Registration of our provider for a specific block
static {
	BOOP_ACCESS.registerProviderForBlock((world, pos, blockState) -> HAVE_A_BOOP_MAYBE, Blocks.COBBLESTONE);
}

// Would be called from a block or item in response to a player action
static void boopItUp(PlayerEntity player, BlockHitResult hit) {
	BOOP_ACCESS.getProviderFromBlock(player.world, hit.getBlockPos()).getBoop(hit.getSide(), player).boop();
}

// A variant of our provider meant for ItemStacks
// Illustrates how same API can have different provider methods.
interface StackBooper extends ApiProvider<StackBooper, Boop> {
	Boop getBoop(ItemStack stack);

	@Override
	default Boop getApi() {
		return NO_BOOP_FOR_YOU;
	}
}

// Registration of our item access along with our absent provider
public static final ItemApiProviderAccess<StackBooper, Boop> BOOP_ITEM_ACCESS = ItemApiProviderAccess.registerAccess(new Identifier("boop:boop"), Boop.class, stack -> NO_BOOP_FOR_YOU);

// Another silly provider
static StackBooper BOOP_THE_STACK = stack -> stack.getCount() == 1 ? () -> System.out.println("Boop!") : NO_BOOP_FOR_YOU;

// Registration of our provider for a few random items
static {
	BOOP_ITEM_ACCESS.registerProviderForItem(s -> BOOP_THE_STACK, Items.RED_CARPET, Items.RED_CONCRETE, Items.REDSTONE);
}

// would be called from an item or block in response to a player action
static void boopThatStack(ItemStack stack) {
	BOOP_ITEM_ACCESS.getProviderFromStack(stack).getBoop(stack).boop();
}

[i509VCB]

make sure asItem does not return null also

[Pyrofab]

Should this really be declared as a functional interface if mods are supposed to add more methods ? It seems that the fact it can be implemented as a lambda is coincidental rather than really planned.

[grondag]

It is an intentional suggestion that sub-types remain lambda-friendly, with the existing method and any overloads getting default implementations. If a provider function is going to be very complex it will likely need a context object and in that case a functional interface should also be viable.

That said, implementations aren't forced to maintain the functional interface contract if it doesn't work for them.

Another option I had considered was to remove ApiProvider entirely and allow any type at all. The system seemed more difficult to understand that way but it would be even more flexible - would make it easier to have providers that a "single hop" - the mapping function returns the API instance directly if the minimal built-in access patterns are sufficient.

[Pyrofab]

Seems reasonable to keep the annotation then.

[shartte]

This probably needs some form of pre-release to easily test it with potential candidate APIs that might use it (i.e. fluid, item transfer or similar)

[i509VCB]

Need to convert function to an EntityProviderFunction

[i509VCB]

Also an ItemStackProviderFunction here

[i509VCB]

Do we want to call this getAbsentApi? getBlah allows some languages like kotlin to infer the method as a val and makes access in those languages much nicer

[Juuxel]

Yeah, especially since Yarn uses bean prefixes for accessor methods.

[i509VCB]

Similar concern to absentApi

[i509VCB]

Similar concern to absentProvider

[i509VCB]

Be consistent here, qualify with this or don't qualify other fields

[grondag]

There is another PR being worked in FabLabs that picks up where this one left off. No reason to have it clutter up the place.