View source for User:ChampionAsh5357/Sandbox/Fluids API

In Forge 41.0.28, the Fluid API had been completely overhauled. These changes expanded the system to allow for custom physics logic and additional behavior not tied directly to the water and lava tags. This guide will go through all the changes and additions that Fluids now provide for you to use.

An example of the new fluid system can be found in the [https://github.com/MinecraftForge/MinecraftForge/blob/1.19.x/src/test/java/net/minecraftforge/debug/fluid/FluidTypeTest.java test mod].

== Quick Guide ==

This is a quick guide representing the one to one conversions that the Fluid API changed

* <code>FluidAttributes</code> -> <code>FluidType</code> (This is a Forge Registry ''forge:fluid_type'')
* <code>FluidAttributes#BUCKET_VOLUME</code> -> <code>FluidType#BUCKET_VOLUME</code>
* <code>FluidAttributes#getBucket</code> -> <code>FluidType#getBucket</code>
* <code>FluidAttributes#getBlock</code> -> <code>FluidType#getBlockForFluidState</code>
* <code>FluidAttributes#getStateForPlacement</code> -> <code>FluidType#getStateForPlacement</code>
* <code>FluidAttributes#canBePlacedInWorld</code> -> <code>FluidType#canBePlacedInLevel</code>
* <code>FluidAttributes#isLighterThanAir</code> -> <code>FluidType#isLighterThanAir</code>
* <code>FluidAttributes#doesVaporize</code> -> <code>FluidType#isVaporizedOnPlacement</code>
* <code>FluidAttributes#vaporize</code> -> <code>FluidType#onVaporize</code>
* <code>FluidAttributes#getDisplayName(FluidStack)</code> -> <code>FluidType#getDescription(FluidStack)</code>
* <code>FluidAttributes#getTranslationKey(FluidStack)</code> -> <code>FluidType#getDescriptionId(FluidStack)</code>
* <code>FluidAttributes#getTranslationKey</code> -> <code>FluidType#getDescriptionId</code>
* <code>FluidAttributes#getLuminosity</code> -> <code>FluidType#getLightLevel</code>
* <code>FluidAttributes#getDensity</code> -> <code>FluidType#getDensity</code>
* <code>FluidAttributes#getTemperature</code> -> <code>FluidType#getTemperature</code>
* <code>FluidAttributes#getViscosity</code> -> <code>FluidType#getViscosity</code>
* <code>FluidAttributes#isGaseous</code> -> <code>Tags$Fluids#GASEOUS</code>
* <code>FluidAttributes#getRarity</code> -> <code>FluidType#getRarity</code>
* <code>FluidAttributes#getColor</code> -> <code>IFluidTypeRenderProperties#getColorTint</code>
* <code>FluidAttributes#getStillTexture</code> -> <code>IFluidTypeRenderProperties#getStillTexture</code>
* <code>FluidAttributes#getFlowingTexture</code> -> <code>IFluidTypeRenderProperties#getFlowingTexture</code>
* <code>FluidAttributes#getOverlayTexture</code> -> <code>IFluidTypeRenderProperties#getOverlayTexture</code>
* <code>FluidAttributes#getFillSound</code> -> <code>FluidType#getSound(SoundActions.BUCKET_FILL)</code>
* <code>FluidAttributes#getEmptySound</code> -> <code>FluidType#getSound(SoundActions.BUCKET_EMPTY)</code>
* <code>FluidAttributes#getLuminosity(FluidStack)</code> -> <code>FluidType#getLightLevel(FluidStack)</code>
* <code>FluidAttributes#getDensity(FluidStack)</code> -> <code>FluidType#getDensity(FluidStack)</code>
* <code>FluidAttributes#getTemperature(FluidStack)</code> -> <code>FluidType#getTemperature(FluidStack)</code>
* <code>FluidAttributes#getViscosity(FluidStack)</code> -> <code>FluidType#getViscosity(FluidStack)</code>
* <code>FluidAttributes#isGaseous(FluidStack)</code> -> REMOVED
* <code>FluidAttributes#getColor(FluidStack)</code> -> <code>IFluidTypeRenderProperties#getColorTint(FluidStack)</code>
* <code>FluidAttributes#getStillTexture(FluidStack)</code> -> <code>IFluidTypeRenderProperties#getStillTexture(FluidStack)</code>
* <code>FluidAttributes#getFlowingTexture(FluidStack)</code> -> <code>IFluidTypeRenderProperties#getFlowingTexture(FluidStack)</code>
* <code>FluidAttributes#getFillSound(FluidStack)</code> -> <code>FluidType#getSound(FluidStack, SoundActions.BUCKET_FILL</code>
* <code>FluidAttributes#getEmptySound(FluidStack)</code> -> <code>FluidType#getSound(FluidStack, SoundActions.BUCKET_EMPTY)</code>
* <code>FluidAttributes#getLuminosity(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getLightLevel(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getDensity(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getDensity(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getTemperature(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getTemperature(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getViscosity(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getViscosity(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#isGaseous(BlockAndTintGetter, BlockPos)</code> -> REMOVED
* <code>FluidAttributes#getRarity(BlockAndTintGetter, BlockPos)</code> -> REMOVED
* <code>FluidAttributes#getColor(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getColorTint(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getStillTexture(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getStillTexture(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getFlowingTexture(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getFlowingTexture(FluidState, BlockAndTintGetter, BlockPos)</code>
* <code>FluidAttributes#getFillSound(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getSound(Player, BlockGetter, BlockPos, SoundActions.BUCKET_FILL)</code>
* <code>FluidAttributes#getEmptySound(BlockAndTintGetter, BlockPos)</code> -> <code>FluidType#getSound(Player, BlockGetter, BlockPos, SoundActions.BUCKET_EMPTY)</code>
* <code>FluidAttributes#getTextures</code> -> <code>IFluidTypeRenderProperties#getTextures</code>
* <code>FluidAttributes$Builder</code> -> <code>FluidType$Properties</code>
* <code>IForgeBlock#getAiPathNodeType</code> -> <code>IForgeBlock#getBlockPathType</code>
* <code>IForgeEntity#canBeRiddenInWater</code> -> <code>IForgeEntity#canBeRiddenUnderFluidType</code>
* <code>IForgeFluid#isEntityInside</code> -> REMOVED
* <code>IForgeFluid#isAABBInsideMaterial</code> -> REMOVED
* <code>IForgeFluid#getAttributes</code> -> <code>IForgeFluid#getFluidType</code>
* <code>IForgeFluidState#isEntityInside</code> -> REMOVED
* <code>ForgeFlowingFluid$Properties(Fluid, Fluid, FluidAttributes)</code> -> <code>ForgeFlowingFluid$Properties(FluidType, Fluid, Fluid)</code>
* <code>ForgeFlowingFluid#canMultiply</code> -> <code>FluidType#canConvertToSource(FluidState, LevelReader, BlockPos)</code>

== Vanilla Breaking Change: No Physics in Tags ==

One of the largest changes within the Fluid API is that Fluid Tags no longer control the physics of fluids. To account for this, a different unifying object which can represent any group of fluids must be chosen. After much consideration, this became <code>FluidType</code>, which replaced <code>FluidAttributes</code>.

=== Removal of FluidAttributes ===

<code>FluidAttributes</code> has been completely removed with most of its logic being delegated to either <code>FluidType</code> or <code>IFluidTypeRenderProperties</code> for rendering. The object itself wasn't unique and tended to be reconstructed whenever referenced. As such, it was removed in favor of a more singleton approach.

== FluidType ==

<code>FluidType</code> replaces <code>FluidAttributes</code>. All fluids must override <code>IForgeFluid#getFluidType</code> similar to the previous <code>#getAttributes</code>. Additionally, the <code>FluidType</code> can be accessed from the fluid or fluid state for convenience.

<syntaxhighlight lang="java">
private static final DeferredRegister<Fluid> FLUIDS = DeferredRegister.create(ForgeRegistries.FLUIDS, ID);

// TestFluid extends FlowingFluid
private static final RegistryObject<FlowingFluid> TEST_FLUID = FLUIDS.register("test_fluid", () -> new TestFluid() {
    @Override
    public FluidType getFluidType() {
        return TEST_FLUID_TYPE.get();
    }
});
</syntaxhighlight>

<code>FluidType</code> is a forge registry, and as such needs to be registered. If using <code>DeferredRegister</code>, you must use the one that takes in the registry name and modid since the registry does not exist during mod construction.

<syntaxhighlight lang="java">
private static final DeferredRegister<FluidType> FLUID_TYPES = DeferredRegister.create(ForgeRegistries.Keys.FLUID_TYPES, ID);

private static final RegistryObject<FluidType> TEST_FLUID_TYPE = FLUID_TYPES.register("test_fluid", () -> new FluidType(FluidType.Properties.create()));
</syntaxhighlight>

=== isVaporizedOnPlacement ===

<code>FluidType#isVaporizedOnPlacement</code> has now been expanded to allow for vaporization to occur outside of only ultra warm dimensions. To do so, simply override the method.

== IFluidTypeRenderProperties ==

<code>IFluidTypeRenderProperties</code> contains all rendering related logic to fluids. This includes the color tint, still texture, flowing texture, and overlay texture. Note that the still texture and flowing texture must be specified by overriding <code>#getStillTexture</code> and <code>#getFlowingTexture</code> respectively.

== Modified Accessors ==

All properties in <code>FluidType</code> and <code>IFluidTypeRenderProperties</code> have either an entity, level, or stack based accessor attached to it. These provide context in question if the behavior of the fluid should change in relation to the entity its acting upon, the location of the fluid in the level, or the containing fluid stack respectively.

There are some accessors with no parameters. These are typically because the use case may not be fully defined in every context that are available to the modder. They should not be used whenever possible as they may be removed in future releases once the context has been fully specified.

== Chained Methods ==

A good portion of the accessors in <code>FluidType</code> are chained in some capacity. This means that modders who are using fluids from other mods can specify unique behavior without having to modify the fluid itself. Let's take two examples: <code>#canHydrate(Level Accessor)</code> and <code>#supportsBoating</code>.

<code>#canHydrate</code> can be modified by the <code>FluidType</code>, <code>Fluid</code>, or <code>Block</code>. This means that the <code>FluidType</code> can define general behavior to use while the <code>Block</code> may define specific behavior for if it can be hydrated.

<code>#supportsBoating</code> works similarly with <code>FluidType</code> and <code>Boat</code>. The <code>FluidType</code> can define in general if boats should work on it while a specific <code>Boat</code> can determine whether it actually can float on the fluid.

== Entity Pathing ==

Entity pathing can now be specified for a given block or the underlying fluid using <code>IForgeBlock#getBlockPathType</code>, <code>IForgeBlock#getAdjacentBlockPathType</code>, <code>FluidType#getBlockPathType</code>, and <code>FluidType#getAdjacentBlockPathType</code>. For clarity, the regular block path type gets the raw type to be used if the adjacents are not specified. The adjacent path type specifically determines which one the entity will move to and will either default to <code>OPEN</code>, <code>WALKABLE</code> or <code>BLOCKED</code> internally. Typically, the entity will pathfind to the smallest positive malus of the type, where negative numbers are considered intraversable. Additional types can be created using <code>BlockPathTypes#create</code>.

== IForgeEntity ==

<code>IForgeEntity</code> now contains many additional commands to handle fluid physics logic. These include the height, which fluid the entity's eyes are in, and if an entity is in a fluid type. All of these methods are properly documented in the extension. Note that these replace their vanilla counterparts and should be used instead.

== IForgeLivingEntity ==

<code>IForgeLivingEntity</code> contains two unique fluid logic handlers: how an entity "jumps" in a fluid, and how they "sink". These methods can currently only be overridden on an entity and not by the <code>FluidType</code>.

== SoundAction ==

<code>SoundAction</code> is the abstracted sound manager for defining which sound to play in a given context. It works exactly like <code>ToolAction</code> where it simply defines a unique name that performs a given action. A new action can be created using <code>SoundAction#get</code>. Vanilla actions are defined within <code>SoundActions</code> (filling/empty bucket, vaporizing).

== Fluid Interactions ==

Fluid interactions are handled by the <code>FluidInteractionRegistry</code>. Interactions define the behavior a block should handle in all directions besides down. The down direction must be defined by the fluid in <code>FlowingFluid#spreadTo</code>, and will not be considered in this registry. An interaction can be registered using <code>#addInteraction</code> in <code>FMLCommonSetupEvent</code> by specifying the source of the interaction (which is typically the fluid being replaced), and the interaction information which defines the conditions of when the interaction should occur and what the interaction should do.

private void commonSetup(FMLCommonSetupEvent event) {
    // Test Fluid + Lava (source/flowing) -> Gold Block (Test fluid source/flowing gets replaced)
    FluidInteractionRegistry.addInteraction(TEST_FLUID_TYPE.get(), new FluidInteractionRegistry.InteractionInformation(ForgeMod.LAVA_TYPE.get(), Blocks.GOLD_BLOCK.defaultBlockState()));
}

== Gaseous Fluids ==

A <code>Fluid</code> is considered gaseous at room temperature if it is in the <code>forge:gaseous</code> tag. This is typically correlated with a negative density.