> ## Documentation Index
> Fetch the complete documentation index at: https://items.lodemc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Fluids

> Custom liquids that flow and swim like water, with their own colour, look, light, effects and bucket.

A fluid is a liquid of its own on the server: it flows, makes sources, fills buckets and does things to whoever touches it. Players' games see it as **water**, so swimming, flowing and falling into it feel exactly like water, and it is painted with its own colour and look.

```yaml items/fluids/shimmer/shimmer.yml theme={null}
shimmer:
  type: fluid
  color: "#C9A8FF"
  style:
    colors: ["#F5B8FF", "#A8F0FF", "#C9A8FF"]
    pattern: shimmer
  light: 7
  effects: ["levitation 10s 1"]
  bucket-texture: shimmer_bucket.png
  name: "<light_purple>Shimmer Bucket"
```

Reload, run `/lodeitems give shimmer` and pour it. The bucket has the same id as the fluid; an empty vanilla bucket picks a source back up.

Lode Items comes with two examples in `items/fluids/`: **Shimmer** (glowing opal, makes you float) and **Sulfur Acid** (yellow and bubbling, hurts and poisons).

## Looks

**color** `colour` (default: #3F76E4)

Its water colour. Every player sees at least this, including players with shader packs.

**style** `section`

How it is painted over water's ripples:

| Key | Default | Does |
| - | - | - |
| `colors` | `color` | Up to 6 colours it moves through. One colour is steady. |
| `pattern` | `swirl` | `flat`, `swirl`, `shimmer` or `pulse`. |
| `speed` | `1` | How fast it moves, `0` to `20`. `0` is still. |
| `opacity` | `0.75` | `0` to `1`. Water is about `0.7`. |
| `glow` | `false` | Ignores darkness, like lava. |

Without `style`, it is plain water in `color`.

**texture** `png`

Your own texture instead of water's. Animated textures have their frames stacked downwards, like vanilla. At most 16 frames, and all fluids' textures together must stay small (they're scaled to 32 px).

**flowing-texture** `png`

Drawn on flowing tops and on the sides, and moves with the flow. Lines along the flow look best. Defaults to `texture`.

**frame-time** `ticks` (default: 2)

How long each frame shows.

**interpolate** `boolean` (default: true)

Blends each frame into the next, like vanilla water.

**light** `0 to 15` (default: 0)

Light its sources give off. Flowing parts don't glow, only sources. This is also the one glow players with shader packs see.

### Players with shader packs

Shader packs (Iris, OptiFine) draw water themselves, so those players don't see `style` or `texture`: they see the fluid in its `color`, plus its `light`.

**shader-colors** `list`

Up to 6 colours shader-pack players see instead of just `color`, laid out as a still patchwork of 4×4 areas that the game blends into soft gradients. Use colours close to each other; very different ones show as patches.

## Behaviour

**effects** `list`

Potion effects while touching it, as `name [duration] [level]`: `["levitation 10s 1", "poison 5s 2"]`. The duration defaults to 10 seconds, the level to 1.

**damage** `number` (default: 0)

Health taken while touching it (2 is one heart), as often as the target can be hurt again.

**flow-speed** `ticks` (default: 5)

Ticks between flow steps. Water is 5, lava 30.

**flow-distance** `1 to 8` (default: 7)

How far it flows from a source on flat ground. Water is 7.

**infinite** `boolean` (default: true)

Two sources make a third, like water.

## The bucket

`bucket-texture`, `name`, `lore` and every other [item option](https://items.lodemc.net/items.md) set up the bucket. Without `bucket-texture` it looks like a water bucket. It stacks to 1 unless you set `stack-size`. Pouring fires a normal block place, so protection plugins apply.

## Limits

* The server reserves `fluids.slots` fluids at startup (default 8, at most 24) in [config.yml](https://items.lodemc.net/configuration.md#fluids). Raising it needs a restart.
* **Adding a fluid or changing its `color` or `shader-colors` needs a restart**, because the colours are sent through biomes that are set up when the server starts. Reload warns when that's the case. Other options apply on reload.
* Real water in the same 4×4×4 area as a fluid takes the fluid's colour.
* Lode Items' fluid look replaces the game's terrain shader, so another resource pack that replaces it can't be used at the same time.
* [Bedrock players](https://items.lodemc.net/bedrock.md) see plain water.

> [!WARNING]
>
> Never lower `fluids.slots` below what you use: placed fluids in the removed slots turn to air.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.