WATER DOCUMENTATION

This is documentation for a preview release of Minecraft. New features, components, and capabilities in this release are not final and might change without notice before the final release.
Be sure to check the documentation once the release is out of preview if your add-on isn't working properly. Resource and Behavior Packs created for the preview are not guaranteed to work on the final release.

Index

Overview

There are many different Water controls in Minecraft. Things such as wave frequency, wave speed, and caustics scale are all water settings.
You can override all of these settings to change the caustic and wave visuals, and even biome water color contribution!

JSON Format

All water settings overrides should specify the version that they target via the "format_version" field. The remainder of the water data is divided up into independent JSON sub-objects for each water control.
These overrides define the water data of the overarching water settings collection. To be valid, a definition must include exactly one of these type objects. See the full water settings schema below for additional details and the full list of supported water overrides.
Here is a sample water settings file.

{
          "format_version": "1.21.120",
          "minecraft:water_settings": {
            "description": {
              "identifier": "test:water" // The identifier for these water settings. The identifier must include a namespace.
            },
            "particle_concentrations": { // The concentration of different optical particles in water.
              "chlorophyll": 1.306, // Chlorophyll concentration in mg/L
              "cdom": 7.102, // Colored dissolved organic matter (CDOM) concentration in mg/L. Also called yellow matter.
              "suspended_sediment": 0.452 // Suspended sediment concentration in mg/L
            },
            "caustics": {
              "enabled": true,
              "frame_length": 0.05,
              "texture": "",
              "scale": 5.0,
              "power": 2
            },
            "waves": {
              "enabled": true,
              "frequency": 0.01,
              "octaves": 16,
              "depth": 2.0,
              "speed": 5.0,
              "shape": 7.0,
              "pull": 0.25,
              "mix": 1.0,
              "frequency_scaling": 0.5,
              "speed_scaling": 0.0
            }
          }
        }

Adding Water Settings

Water Settings are read from JSON files in the "water" subfolder of resource packs. Loading enforces one water settings collection per file. The settings collection's identifier acts as its name and must be namespaced. If two resource packs define the same water settings name (including namespace), then the settings from the highest pack in the stack will be used. Adding a file with a new name to the water data location will make it available for the game to use, while existing water settings can be overridden using another settings collection with the same identifier.

Schema

CausticsParameters

Name	Type	Required?	Description
enabled	Boolean	Optional	Whether or not caustics are on or off.
frame_length	Float	Optional	A range from 0.01 to 5.0 which controls how many seconds to spend on each frame of animation in the caustics texture.
power	Float	Optional	A range from 1 to 6 which controls how bright the caustics effect appears.
scale	Float	Optional	A range from 0.1 to 5.0 which controls how size of the repetition of the caustics texture.
texture	String	Optional	Resource location to a texture for controlling the shape of the caustics; if not used, a built-in Minecraft texture will be supplied automatically.

PSY

Name	Type	Required?	Description
cdom	Float	Optional	Concentration of chromophoric dissolved organic matter from 0.0 to 15.0 in mg/L; higher concentrations produce more yellow/yellow-brown colors.
chlorophyll	Float	Optional	Concentration of chlorophyll from 0.0 to 10.0 in mg/L; higher concentrations produce more green colors.
suspended_sediment	Float	Optional	Concentration of suspended sediment from 0.0 to 300.0 in mg/L; higher concentrations produce more red/red-brown colors.

Water Config JSON File v4

Name	Type	Required?	Description
format_version	String	Required	Specifies the version of the game these Water Settings were made in. If the version is lower than the current version, any changes made to the settings in the vanilla version will be applied to it.
minecraft:water_settings	Object of type WaterSettings	Required	Water Settings definition which includes the 'particle_concentrations,' 'waves,' 'biome_water_color_contribution,' and 'caustics' sections.

WaterDescription

Name	Type	Required?	Description
identifier	Object of type Identifier	Required	The name of this Water Description in the format 'namespace_name:description_name'.

WaterSettings

Name	Type	Required?	Description
biome_water_color_contribution	Float	Optional	Controls how much the surface_color value defined in *.client_biome.json files will be mixed into the base color of the water in Vibrant Visuals.
caustics	Object of type CausticsParameters	Optional	Caustics make bodies of water more realistic by projecting light rays on underwater surfaces. These rays then scatter and dance as the surface of the water moves. This effect is enabled by default, but can be selectively disabled in given water configurations.
description	Object of type WaterDescription	Required
particle_concentrations	Object of type PSY	Optional	The composition of particles in a body of water determines its color and how light behaves as it travels through the water. We've boiled them down to three concentrations in mg/L. Use these values to simulate crystal clear lakes, deep oceans, or muddy rivers.
waves	Object of type WaterSurfaceParameters	Optional	Waves are an optional effect that can be used to complement water surface animations to make your water appear more realistic. You can blend them with existing water texture animations, or replace them entirely. The waves in Vibrant Visuals are purely an image-based effect—waves don't actually move the vertices of the water surface, so the water surface geometry will remain unchanged.

WaterSurfaceParameters

Name	Type	Required?	Description
depth	Float	Optional	A range from 0.0 to 3.0 which controls the amount of wave displacement.
direction_increment	Float	Optional	A range from 0.0 to 360.0 which controls how much the heading changes between each octave.
enabled	Boolean	Optional	Whether or not waves are on or off.
frequency	Float	Optional	A range from 0.01 to 3.0 which controls the size of individual waves; higher values create more tightly packed waves.
frequency_scaling	Float	Optional	A range from 0.0 to 2.0 which controls how much frequencies change in subsequent octaves.
mix	Float	Optional	A range from 0.0 to 1.0 which controls how much each octave will blend into the neighboring octave.
octaves		Optional	A range from 1 to 30 which determines how many layers of waves to simulate; high values result in more complex waves.
pull	Float	Optional	A range from -1.0 to 1.0 which controls how much smaller waves are pulled into larger ones.
shape	Float	Optional	A range from 1.0 to 10.0 which adjusts the shape of the wave.
speed	Float	Optional	A range from 0.01 to 10.0 which controls the starting speed of the first waves.
speed_scaling	Float	Optional	A range from 0.0 to 2.0 which controls how much faster/slower subsequent octaves move.

WATER DOCUMENTATION

Index#

Overview#

JSON Format#

Adding Water Settings#

Schema#

CausticsParameters#

PSY#

Water Config JSON File v4#

WaterDescription#

WaterSettings#

WaterSurfaceParameters#