Soft Fluids

Soft Fluids

A lightweight virtual fluid system built around containers, not world fluids.

A soft fluid doesn't flow or fill the world. It knows which items hold it (bottle, bucket, bowl, block), how much each holds, what it looks like, and whether drinking it feeds you. That's enough for tanks, cauldrons, jars and pipes without registering a real Fluid, and it maps onto other mods' fluids so a Create honey and a Bumblezone honey are the same thing in your tank.

Soft fluids are a datapack registry, so packs can add and change them without any code.

Getting Started

Files go in data/[your namespace]/moonlight/soft_fluid/[name].json.

{
  "still_texture": "moonlight:block/soft_fluids/honey_liquid",
  "flowing_texture": "moonlight:block/soft_fluids/honey_liquid",
  "translation_key": "fluid.minecraft.honey",
  "tint_method": "no_tint",
  "containers": [
    {
      "empty": "minecraft:glass_bottle",
      "filled": ["minecraft:honey_bottle"],
      "capacity": "BOTTLE",
      "fill_sound": "minecraft:block.honey_block.place",
      "empty_sound": "minecraft:block.honey_block.break"
    }
  ],
  "food": {
    "item": "minecraft:honey_bottle",
    "divider": "BOTTLE"
  },
  "equivalent_fluids": ["create:honey", "minecraft:honey"]
}

JSON Format

Field	Type	Default	Description
still_texture	id	required	Texture used when still
flowing_texture	id	required	Texture used when flowing
translation_key	translatable component	generic fluid	Display name
luminosity	0 to 15	0	Light the fluid gives off
emissivity	0 to 15	0	How brightly it renders regardless of light
color	hex string or int	-1 (none)	Tint applied to the textures
tint_method	enum	still_and_flowing	Which textures the tint applies to. no_tint, still, flowing, still_and_flowing
containers	list	empty	The item to fluid mapping, see below
food	food object or item id	none	What drinking it does
preserved_components_from_item	item component types	empty	Data components copied from the container item onto the fluid stack, so a potion keeps its effects
equivalent_fluids	list of fluid ids	empty	Real fluids that count as this one. Entries can be {"id": "...", "required": false} so missing mods don't error
use_texture_from	id	none	Take the rendering data from another mod's fluid instead of the textures above

containers

Each entry is one empty container and the filled items that correspond to it.

Field	Type	Default	Description
empty	item id	required	The empty container. minecraft:air for things that leave nothing behind, like a honey block
filled	list of item ids	required	Items that count as this container, filled
capacity	BOTTLE, BOWL, BUCKET, BLOCK, or a number	required	How much it holds
fill_sound	sound id	none
empty_sound	sound id	none

Capacities are relative units, not millibuckets. A bucket is 4 bottles on Forge and 3 on Fabric, matching each loader's own convention, which is why you should use the names rather than numbers.

food

Either an item id on its own, or an object:

Field	Type	Default	Description
item	item id	required	The item whose food properties and drink behavior are used
divider	capacity or number	1	How much fluid one "serving" is

In code

SoftFluidTank tank = SoftFluidTank.create(SoftFluid.BOTTLE_COUNT * 4);

// handles the whole interaction: which hand, filling or draining, sounds, item swap
tank.interactWithPlayer(player, hand, level, pos);

SoftFluidStack is the fluid plus an amount plus data components, and converts to and from real fluids with fromFluid. Blocks can implement ISoftFluidProvider, ISoftFluidConsumer or ISoftFluidTankProvider so other mods' pipes and pumps can see the tank.

New fluids can also be registered from code, but a datapack file is usually the right answer.