Fluid API: The Good, The Bad, and The Ugly

[ChampionAsh5357]

So, the Fluid API has been out since 1.19 and it has worked somewhat well. However, there are plenty of bugs and missing features that I didn't take into account when designing it (e.g., bubble columns, mobs other than the player swimming, fluid interactions in the UP direction). Additionally, there are a few features where people have gone 'what the...' because of the previously intended use-cases in mods (e.g., color tints only on the client, on vaporize containing additional checks within the method).

For this reason, I'm opening up this discussion to consolidate as much feedback as possible about the current features, or lack thereof, of the fluid API. I'm going to be taking another pass at design and implementation targeting 1.21 or 1.22 depending on the next Minecraft release and when I get another laptop since my current one is a hot brick.

Thanks!

[TelepathicGrunt]

First thought I have, vanilla's fluid tags should still work with modded fluids added in case people do want all the behaviors of the vanilla tag. Like me with my Sugar Water which is suppose to be a near exact replica of vanilla water with a few extra features added. As a result, i had to throw a ton of mixins at the system as not every behavior is replicated with the api as you mentioned

Also, I had to do multiple mixins to fishing hook to make it work with my fluid since even with the vanilla fluid tag, there's a hardcoded vanilla water check in it.

[Matyrobbrt]

Personally, I don't think the vanilla tags should still work with modded fluids. The vanilla tags are basically used to group flowing and still fluids, and given that they define a set of very specific behaviour (such as boats, sponge absorption, fog) I don't see them usable for anything but facsimile vanilla fluids.

The vanilla tag (water specifically) is widely used in recipes and was polluted with practically all fluids that can be placed in the world because that's how you'd define behaviour. While yes this was caused by the lack of the fluid API, if the vanilla tags still work a lot of mods would prefer to just tag their fluids as water because it causes the fluid to "feel" like one, and I don't want to cool reactors with honey and chocolate.

[TelepathicGrunt]

If the API was fully fleshed out and working, the mods would opt out of the water tag and use the API to define behavior. But in cases where a mod does something like molten lead or molten steel, they may want the lava tag to reduce work as molten stuff is basically lava anyway. Basically both tag and API can co-exist. Could even have it where if API version of a behavior is defined, it overrides the vanilla tag's behavior but other vanilla fluid tag behavior stays

[Matyrobbrt]

But would you want to use molten steel as a fuel source for furnaces or for generators? Would you like your molten steel to be made into obsidian? Tagging fluids with vanilla tags for the behaviour causes this kind of problems, it brings us back to "honey but it's water".
The current fluid api does not fully replace tags yes, but IMO we should aim for it to replace them completely.

[ChampionAsh5357]

In general, logic on a fluid should either directly propogate to the FluidType or to some instance on the tag representing the 'shared' logic between still and flowing. It would either makes sense to just use tags all the way and somehow attach an object to that, or we replace all logic with FluidType and have that be the central source for operation. I generally prefer the latter, but the former is currently what vanilla uses so it requires less of a giant redirect for everything.

If we are to still use the modded FluidType, to get around the issues with the water or lava behavior, we could simply make a constructor that copies from another FluidType or make a static constructor method that creates a FluidType with all the default water behavior.

[HenryLoenwind]

I haven't kept up, but I'll repeat what I said years ago:

The only way to make this work is to inject a callback into each and every location that does any kind of check for a fluid. So, for example, if the vanilla code is something like:

if (block is water) {
  ...
} else if (block is lava) {
...
} else {
...
}

It should be transformed into:

switch (block.getFluidHandler().getOrHandleFluidAction(EnumCodeLocation.PLAYER_SWIMMING14, player, pos, ...)) {
  case WATER:
    ...
  case LAVA:
    ...
  case HANDLED:
    break; // the callback already handled everything
  case SOLID: case: AIR: case ...: default:
     ...
}

With some callbacks returning values to use where it's appropriate instead of having to reimplement the wheel.

What other return values in addition to WATER, LAVA and HANDLED would be useful can only be determined while doing the conversion. It may well be that NOT_FLUID is the only useful value, or it may be that having some fluids act like air/solid in some cases would make sense (i.e. there are code paths to take that are more useful than HANDLED).

Also, having WATER_SOURCE and WATER_FLOWING instead of WATER may be needed. Thankfully switch() statements allow clumping as many possible values into one code path as you want with no additional runtime cost. And this could even be streamlined by having a .asMaterial() method on the enum values that reduces the result to WATER/LAVA/HANDLED/ELSE.

Note that that fluid handler would have callbacks for every single interaction. To reduce the number of methods to add, I envisioned the enum parameter in addition to the varying context parameters. That enum would have a unique value for each and every code location that calls the handler.

There would be singletons of the handler for all non-fluid-Blocks that don't have their own specific handler as well as the vanilla fluid blocks, which would be a perfect location to fire some events. Obviously, not for every callback, but there are some checks mods may override without having a block in the world (e.g. hydrating farmland in a large area, swimming in air while an item is equipped. or drowning in air while morphed into a fish).

PS: Obviously, the default modded-fluid block would proxy the getFluidHandler() to the fluid. Forcing all checks to have a block at hand would not be the wisest. This also would allow blocks like an open tank (swimming pool) to act like the fluid that is in them.

PS2: No, this is not a fully fledged-out design but a rough idea. And yes, this would add hundreds of patches.

[TelepathicGrunt]

@FiniteReality weren't you thinking of doing fluid api rework? Or is it shelved again?