Documentation for Fluid API #435
Description
The general gist of it is as follows:
Forge provided a Fluid API for mods to utilize so everyone can have compatible fluids galore! The trick is that while we could expose said Fluid API directly, it involves a lot of casting back and forth between Forge's IFluidHandlers and API's TileEntity instances. The workaround? Represent fluid "tanks" as DataHolders since Forge only really makes it a point that IFluidHandlers (things that have multiple FluidStacks depending on direction) are only compatible as being TileEntity instances.
Having that said, it's still possible for ItemStacks to be IFluidContainerItems as well, but the difference is that a single FluidStack will exist on the container ItemStack instead of several FluidStacks.
The FluidStack is the literal equivalent to an ItemStack. They're stacks of Fluids (represented as FluidType in our API) with possible custom extra mod data. Given that FluidStacks are entirely mutable, a "snapshot" had to be created, giving us the FluidStackSnapshot akin to the ItemStackSnapshot.
Now, the goal of the API is that there's full exposure to manipulating these IFluidHandlers (which are always TileEntity instances anyways) through the Data API.
Lastly, there's of course native Fluid API support (provided by SpongeCommon) for Vanilla fluids, though this is limited to water buckets, lava buckets, and buckets.
The unit of measurement of a FluidStack is "millibuckets", or 1000mB = 1 bucket.
@diesieben07 can possibly help in documenting how fluids are "intended" to work, but given that there's already this abstraction layer achieved though the Data API, most all of this is documented in either the package.info or in any of the Fluid API classes in our API.