Difference between revisions of "User:ChampionAsh5357/Sandbox/Fluids API"

From Forge Community Wiki
(Start Fluid API writing.)
 
(Quick primer)
Line 60: Line 60:
 
* <code>ForgeFlowingFluid$Properties(Fluid, Fluid, FluidAttributes)</code> -> <code>ForgeFlowingFluid$Properties(FluidType, Fluid, Fluid)</code>
 
* <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>
 
* <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.
 +
 +
<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.
 +
 +
=== 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.
 +
 +
== 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.

Revision as of 01:43, 15 June 2022

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.

Quick Guide

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

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

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 FluidType, which replaced FluidAttributes.

Removal of FluidAttributes

FluidAttributes has been completely removed with most of its logic being delegated to either FluidType or IFluidTypeRenderProperties 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

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

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

isVaporizedOnPlacement

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

IFluidTypeRenderProperties

IFluidTypeRenderProperties 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 #getStillTexture and #getFlowingTexture respectively.

Modified Accessors

All properties in FluidType and IFluidTypeRenderProperties 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 FluidType 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: #canHydrate(Level Accessor) and #supportsBoating.

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

#supportsBoating works similarly with FluidType and Boat. The FluidType can define in general if boats should work on it while a specific Boat 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 IForgeBlock#getBlockPathType, IForgeBlock#getAdjacentBlockPathType, FluidType#getBlockPathType, and FluidType#getAdjacentBlockPathType. 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 OPEN, WALKABLE or BLOCKED 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 BlockPathTypes#create.

IForgeEntity

IForgeEntity 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

IForgeLivingEntity 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 FluidType.

SoundAction

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

Fluid Interactions

Fluid interactions are handled by the FluidInteractionRegistry. Interactions define the behavior a block should handle in all directions besides down. The down direction must be defined by the fluid in FlowingFluid#spreadTo, and will not be considered in this registry. An interaction can be registered using #addInteraction in FMLCommonSetupEvent 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.

Gaseous Fluids

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

Retrieved from ‘https://forge.gemwire.uk/index.php?title=User:ChampionAsh5357/Sandbox/Fluids_API&oldid=3276’