Differences

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

--- tutorial:transfer-api [2021/10/29 20:45] – technici4n
+++ tutorial:transfer-api [2023/07/19 13:38] (current) – technici4n
@@ Line 1: / Line 1: @@
-====== [WIP] Understanding the Fabric Transfer API ======
+====== Fluid, Item and Energy Transfer ======
-This tutorial gives a brief overview of how the Fabric Transfer API works, and how you can use it for your own mods.
-For any question, please go to the ''#fluid-volume-api-debating'' channel on the discord server.
-===== Creating a simple tank =====
+All Transfer API classes are marked as ''@ApiStatus.Experimental''. This is temporary, and it means that there may be occasional breaking changes if a design flaw is encountered in the API, but we will try not to break the API to avoid disrupting the large amount of mods that are using it already. In practice, this means that you can mostly ignore this warning, and disable it in your IDE if it's too annoying.
-Let's see how we can make a block entity contain some fluid:
-<code java>
-public class MyTankBlockEntity extends BlockEntity {
-	// This field is going to contain the amount, and the fluid variant (more on that in a bit).
-	public final SingleVariantStorage<FluidVariant> fluidStorage = new SingleVariantStorage<>() {
-		@Override
-		protected FluidVariant getBlankVariant() {
-			return FluidVariant.blank();
-		}
-		@Override
+==== Transactions ====
-		protected long getCapacity(FluidVariant variant) {
+The Fabric Transfer API relies heavily on the concept of transactions.
-			// Here, you can pick your capacity depending on the fluid variant.
-			// For example, if we want to store 8 buckets of any fluid:
-			return 8 * FluidConstants.BUCKET;
-		}
-		@Override
+  - [[tutorial:transfer-api/transactions|The Transaction system]]. Before looking at the details of how transfer works, we take a detour to discuss transactions.
-		protected void onFinalCommit() {
-			// Called after a successful insertion or extraction, markDirty to ensure the new amount and variant will be saved properly.
-			markDirty();
-		}
-	};
-	@Override
+==== The Fluid Transfer API ====
-	public NbtCompound writeNbt(NbtCompound tag) {
+The Fabric Fluid Transfer API is how fluid-containing blocks such as machines, pipes, and tanks communicate with each other. It's what allows all mods to be compatible with each other as far as fluid transfer is concerned. (If you are coming from Forge, it serves a purpose similar to ''IFluidHandler'').
-		tag.put("fluidVariant", fluidStorage.variant.toNbt());
-		tag.putLong("amount", fluidStorage.amount);
-		return super.writeNbt(tag);
-	}
-	@Override
-	public void readNbt(NbtCompound tag) {
-		super.readNbt(tag);
-		fluidStorage.variant = FluidVariant.fromNbt(tag.getCompound("fluidVariant"));
-		fluidStorage.amount = tag.getLong("amount");
-	}
-}
-</code>
-Alright, now we can contain some fluid, and we are properly saving it if it changes.
+  - [[tutorial:transfer-api/simpletank|Creating a tank block entity]] walks you through how you can create a simple tank block entity, and what ''FluidVariant'' is.
-Now, we must register ensure that other mods can properly interact with our tank:
+  - [[tutorial:transfer-api/storage|Understanding Storage<FluidVariant>]] teaches what ''Storage<FluidVariant>'' is and how to use it.
-<code java>
+  - [[tutorial:transfer-api/fluid_implementation|How to implement Storage<FluidVariant>]] provides an overview of the storage implementations provided by Fabric that you can use in your mods, with plenty of example code.
-BlockEntityType<MyTankBlockEntity> MY_TANK = // see block entity tutorial
-// Put this in your mod initializer, after you have created the block entity type:
+==== The Item Transfer API ====
-FluidStorage.SIDED.registerForBlockEntity((myTank, direction) -> myTank.fluidStorage, MY_TANK);
+The Fabric Item Transfer API is used by item-containing blocks such as chests, machines, or storage drawers to communicate with other. (If you are coming from Forge, it serves a purpose similar to ''IItemHandler'').
-</code>
+  - [[tutorial:transfer-api/item_storage|Item transfer with Storage<ItemVariant>]] explains how the item API is almost the same as the fluid API, how wrappers around Inventory/PlayerInventory can be retrieved, and how item storages can be implemented in practice.
-=== But wait, what is a FluidVariant ? ===
+//Note: the existing item transfer API in Minecraft should be avoided in fabric mods due to its severe limitations. If you don't know what this means, you can ignore this warning.//
-A ''FluidVariant'' is what the Transfer API uses to represent the "type" of a fluid. It contains the ''Fluid'' in the minecraft sense, and also an optional NBT compound tag:
-<code java>
-// Creating a fluid variant from a fluid, without an NBT tag.
-FluidVariant waterVariant = FluidVariant.of(Fluids.WATER);
-waterVariant.getFluid() // returns Fluids.WATER
-waterVariant.copyNbt() // returns a copy of the optional nbt tag, in this case null
-// Creating a fluid variant from a fluid, with an NBT tag.
-NbtCompound customTag = new NbtCompound();
-customTag.putBoolean("magic", true);
-FluidVariant magicWater = FluidVariant.of(Fluids.WATER, customTag);
-</code>
-Variants are always compared with ''.equals'', NEVER WITH ''=='' !
+==== Fluid-containing items ====
-<code java>
+  - [Not finished] [[tutorial:transfer-api/fluid-containing-items|How to use and implement the fluid-containing item API]].
-waterVariant.equals(waterVariant); // returns true
-waterVariant.equals(magicWater); // returns false
-// You can easily test if a variant has some fluid:
-waterVariant.isOf(Fluids.WATER); // returns true
-magicWater.isOf(Fluids.WATER); // returns true
-</code>
-They can easily be serialized to and from NBT or network packets:
+==== The TechReborn Energy API ====
-<code java>
+  - [Not yet written] 1. [[tutorial:energy-blockentity|how to create an energy storage block entity]]
-// NBT
-NbtCompound compound = variant.toNbt();
-FluidVariant variant = FluidVariant.fromNbt(compound);
-// Network packets
-variant.toPacket(buf);
-FluidVariant variant = FluidVariant.fromPacket(buf);
-</code>
-=== More on Fabric API Lookup ===
-To understand what the call to ''FluidStorage.SIDED'' does, please have a look at [[https://maven.fabricmc.net/docs/fabric-api-0.40.0+1.17/net/fabricmc/fabric/api/lookup/v1/block/BlockApiLookup.html|the Usage Example in the documentation of ''BlockApiLookup'']].
-The Fabric API Lookup system allows blocks to expose interfaces such as ''Storage<FluidVariant>'', so that pipes and other devices can use them.