Fabric Transfer API: "fluid only" edition

build.gradle

@@ -175,7 +175,7 @@ allprojects {
 
 	checkstyle {
 		configFile = rootProject.file("checkstyle.xml")
-		toolVersion = "8.31"
+		toolVersion = "8.43"
 	}
 
 	tasks.withType(AbstractArchiveTask) {

fabric-transfer-api-v1/README.md

@@ -0,0 +1,36 @@
+# Fabric Transfer API (v1)
+This module provides common facilities for the transfer of fluids and other game resources.
+
+## Transactions
+The [`Transaction`](src/main/java/net/fabricmc/fabric/api/transfer/v1/transaction/Transaction.java) system provides a
+scope that can be used to simulate any number of transfer operations, and then cancel or validate all of them at once.
+One can think of transactions as video game checkpoints. A more detailed explanation can be found in the class javadoc of `Transaction`.
+Every transfer operation requires a `Transaction` parameter.
+[`SnapshotParticipant`](src/main/java/net/fabricmc/fabric/api/transfer/v1/transaction/base/SnapshotParticipant.java)
+is the reference implementation of a "participant", that is an object participating in a transaction.
+
+## Storages
+A [`Storage<T>`](src/main/java/net/fabricmc/fabric/api/transfer/v1/storage/Storage.java) is any object that can store resources of type `T`.
+Its contents can be read, and resources can be inserted into it or extracted from it.
+[`StorageUtil`](src/main/java/net/fabricmc/fabric/api/transfer/v1/storage/StorageUtil.java) provides a few helpful functions to work with `Storage`s,
+for example to move resources between two `Storage`s.
+The [`storage/base`](src/main/java/net/fabricmc/fabric/api/transfer/v1/storage/base) package provides a few helpers to accelerate
+implementation of `Storage<T>`.
+
+## Fluid transfer
+A `Storage<FluidVariant>` is any object that can store fluids. It is just a `Storage<T>`, where `T` is
+[`FluidVariant`](src/main/java/net/fabricmc/fabric/api/transfer/v1/fluid/FluidVariant.java), the immutable combination of a `Fluid` and additional NBT data.
+Instances can be accessed through the API lookups defined in [`FluidStorage`](src/main/java/net/fabricmc/fabric/api/transfer/v1/fluid/FluidStorage.java).
+
+Implementors of fluid inventories with a fixed number of "slots" or "tanks" can use
+[`SingleFluidStorage`](src/main/java/net/fabricmc/fabric/api/transfer/v1/fluid/base/SingleFluidStorage.java),
+and combine them with `CombinedStorage`.
+
+The unit for fluid transfer is 1/81000ths of a bucket, also known as _droplets_.
+[`FluidConstants`](src/main/java/net/fabricmc/fabric/api/transfer/v1/fluid/FluidConstants.java) contains a few helpful constants
+to work with droplets.
+
+Client-side [Fluid variant rendering](src/main/java/net/fabricmc/fabric/api/transfer/v1/client/fluid/FluidVariantRendering.java) will use regular fluid rendering by default,
+ignoring the additional NBT data.
+`Fluid`s that wish to render differently depending on the stored NBT data can register a
+[`FluidVariantRenderHandler`](src/main/java/net/fabricmc/fabric/api/transfer/v1/client/fluid/FluidVariantRenderHandler.java).

fabric-transfer-api-v1/build.gradle

@@ -0,0 +1,17 @@
+archivesBaseName = "fabric-transfer-api-v1"
+version = getSubprojectVersion(project, "0.3.4")
+
+moduleDependencies(project, [
+	'fabric-api-base',
+	'fabric-api-lookup-api-v1',
+	'fabric-lifecycle-events-v1', // transitive dependency of API Lookup
+	'fabric-rendering-fluids-v1',
+	'fabric-textures-v0' // transitive dependency of Rendering Fluids
+])
+
+dependencies {
+	testmodImplementation project(path: ':fabric-object-builder-api-v1', configuration: 'dev')
+	testmodImplementation project(path: ':fabric-resource-loader-v0', configuration: 'dev')
+	testmodImplementation project(path: ':fabric-tag-extensions-v0', configuration: 'dev')
+	testmodImplementation project(path: ':fabric-tool-attribute-api-v1', configuration: 'dev')
+}

fabric-transfer-api-v1/src/main/java/net/fabricmc/fabric/api/transfer/v1/client/fluid/FluidVariantRenderHandler.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.api.transfer.v1.client.fluid;
+
+import java.util.List;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Nullable;
+
+import net.minecraft.client.item.TooltipContext;
+import net.minecraft.client.texture.Sprite;
+import net.minecraft.text.Text;
+
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+import net.fabricmc.fabric.api.client.render.fluid.v1.FluidRenderHandler;
+import net.fabricmc.fabric.api.client.render.fluid.v1.FluidRenderHandlerRegistry;
+import net.fabricmc.fabric.api.transfer.v1.fluid.FluidVariant;
+
+/**
+ * Defines how {@linkplain FluidVariant fluid variants} of a given Fluid should be displayed to clients.
+ * Register with {@link FluidVariantRendering#register}.
+ *
+ * @deprecated Experimental feature, we reserve the right to remove or change it without further notice.
+ * The transfer API is a complex addition, and we want to be able to correct possible design mistakes.
+ */
+@ApiStatus.Experimental
+@Deprecated
+@Environment(EnvType.CLIENT)
+public interface FluidVariantRenderHandler {
+	/**
+	 * Return the name that should be used for the passed fluid variant.
+	 */
+	default Text getName(FluidVariant fluidVariant) {
+		return fluidVariant.getFluid().getDefaultState().getBlockState().getBlock().getName();
+	}
+
+	/**
+	 * Append additional tooltips to the passed list if additional information is contained in the fluid variant.
+	 *
+	 * <p>The name of the fluid, and its identifier if the tooltip context is advanced, should not be appended.
+	 * They are already added by {@link FluidVariantRendering#getTooltip}.
+	 */
+	default void appendTooltip(FluidVariant fluidVariant, List<Text> tooltip, TooltipContext tooltipContext) {
+	}
+
+	/**
+	 * Return the sprite that should be used to render the passed fluid variant, for use in baked models, (block) entity renderers, or user interfaces.
+	 *
+	 * <p>Null may be returned if the fluid variant should not be rendered.
+	 */
+	@Nullable
+	default Sprite getSprite(FluidVariant fluidVariant) {
+		// Use the fluid render handler by default.
+		FluidRenderHandler fluidRenderHandler = FluidRenderHandlerRegistry.INSTANCE.get(fluidVariant.getFluid());
+
+		if (fluidRenderHandler != null) {
+			return fluidRenderHandler.getFluidSprites(null, null, fluidVariant.getFluid().getDefaultState())[0];
+		} else {
+			return null;
+		}
+	}
+
+	/**
+	 * Return the color to use when rendering {@linkplain #getSprite the sprite} of this fluid variant.
+	 */
+	default int getColor(FluidVariant fluidVariant) {
+		// Use the fluid render handler by default.
+		FluidRenderHandler fluidRenderHandler = FluidRenderHandlerRegistry.INSTANCE.get(fluidVariant.getFluid());
+
+		if (fluidRenderHandler != null) {
+			return fluidRenderHandler.getFluidColor(null, null, fluidVariant.getFluid().getDefaultState());
+		} else {
+			return -1;
+		}
+	}
+
+	/**
+	 * Return {@code true} if this fluid should fill tanks from top.
+	 */
+	default boolean fillsFromTop(FluidVariant fluidVariant) {
+		// By default, fluids should be filled from the bottom.
+		return false;
+	}
+}

fabric-transfer-api-v1/src/main/java/net/fabricmc/fabric/api/transfer/v1/client/fluid/FluidVariantRendering.java

@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.api.transfer.v1.client.fluid;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Nullable;
+
+import net.minecraft.client.item.TooltipContext;
+import net.minecraft.client.texture.Sprite;
+import net.minecraft.fluid.Fluid;
+import net.minecraft.text.LiteralText;
+import net.minecraft.text.Text;
+import net.minecraft.util.Formatting;
+import net.minecraft.util.registry.Registry;
+
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+import net.fabricmc.fabric.api.lookup.v1.custom.ApiProviderMap;
+import net.fabricmc.fabric.api.transfer.v1.fluid.FluidVariant;
+
+/**
+ * Client-side display of fluid variants.
+ *
+ * @deprecated Experimental feature, we reserve the right to remove or change it without further notice.
+ * The transfer API is a complex addition, and we want to be able to correct possible design mistakes.
+ */
+@ApiStatus.Experimental
+@Deprecated
+@Environment(EnvType.CLIENT)
+public class FluidVariantRendering {
+	private static final ApiProviderMap<Fluid, FluidVariantRenderHandler> HANDLERS = ApiProviderMap.create();
+	private static final FluidVariantRenderHandler DEFAULT_HANDLER = new FluidVariantRenderHandler() { };
+
+	/**
+	 * Register a render handler for the passed fluid.
+	 */
+	public static void register(Fluid fluid, FluidVariantRenderHandler handler) {
+		if (HANDLERS.putIfAbsent(fluid, handler) != null) {
+			throw new IllegalArgumentException("Duplicate handler registration for fluid " + fluid);
+		}
+	}
+
+	/**
+	 * Return the render handler for the passed fluid, if available, and {@code null} otherwise.
+	 */
+	@Nullable
+	public static FluidVariantRenderHandler getHandler(Fluid fluid) {
+		return HANDLERS.get(fluid);
+	}
+
+	/**
+	 * Return the render handler for the passed fluid, if available, or the default instance otherwise.
+	 */
+	public static FluidVariantRenderHandler getHandlerOrDefault(Fluid fluid) {
+		FluidVariantRenderHandler handler = HANDLERS.get(fluid);
+		return handler == null ? DEFAULT_HANDLER : handler;
+	}
+
+	/**
+	 * Return the name of the passed fluid variant.
+	 */
+	public static Text getName(FluidVariant fluidVariant) {
+		return getHandlerOrDefault(fluidVariant.getFluid()).getName(fluidVariant);
+	}
+
+	/**
+	 * Return the tooltip for the passed fluid variant, including the name and additional lines if available
+	 * and the id of the fluid if advanced tooltips are enabled.
+	 */
+	public static List<Text> getTooltip(FluidVariant fluidVariant, TooltipContext context) {
+		List<Text> tooltip = new ArrayList<>();
+
+		// Name first
+		tooltip.add(getName(fluidVariant));
+
+		// Additional tooltip information
+		getHandlerOrDefault(fluidVariant.getFluid()).appendTooltip(fluidVariant, tooltip, context);
+
+		// If advanced tooltips are enabled, render the fluid id
+		if (context.isAdvanced()) {
+			tooltip.add(new LiteralText(Registry.FLUID.getId(fluidVariant.getFluid()).toString()).formatted(Formatting.DARK_GRAY));
+		}
+
+		// TODO: consider adding an event to append to tooltips?
+
+		return tooltip;
+	}
+
+	/**
+	 * Return the sprite that should be used to render the passed fluid variant, or null if it's not available.
+	 * The sprite should be rendered using the color returned by {@link #getColor}.
+	 */
+	@Nullable
+	public static Sprite getSprite(FluidVariant fluidVariant) {
+		return getHandlerOrDefault(fluidVariant.getFluid()).getSprite(fluidVariant);
+	}
+
+	/**
+	 * Return the color that should be used to render {@linkplain #getSprite the sprite} of the passed fluid variant.
+	 */
+	public static int getColor(FluidVariant fluidVariant) {
+		return getHandlerOrDefault(fluidVariant.getFluid()).getColor(fluidVariant);
+	}
+
+	/**
+	 * Return {@code true} if this fluid variant should be rendered as filling tanks from the top.
+	 */
+	public static boolean fillsFromTop(FluidVariant fluidVariant) {
+		return getHandlerOrDefault(fluidVariant.getFluid()).fillsFromTop(fluidVariant);
+	}
+}