Generate Bedrock resource-pack visuals for Java biomes

[kayvdlans]

Summary

Since I wanted to create some custom biomes for a personal server I looked for current support for custom foliage and water colors. I came across this issue, where a comment from a few years ago sparked some interest in actually implementing this.

This PR adds an optional biome-visuals.json file to the Geyser config directory. Geyser will validate this file and generate a .mcpack that contains bedrock client biome- and fog definitions for every configured Java identifier in the biome-visuals.json file. This feature supports both completely custom biomes, as well as custom colors for vanilla biomes.

Custom mappings are kept separate from the vanilla mapping registry, and IDs will start at 30000, which is Bedrock's starting range for custom biome runtime IDs (It's not arbitrary, I swear ;)).

When the Java biome registry is received, Geyser will now create Bedrock definitions for configured custom biomes using the biome's temperature, downfall, precipitation flag, and color values. The custom definitions are appended to the vanilla definitions sent in BiomeDefinitionListPacket, When Geyser encodes chunk biome data for Bedrock, it uses the corresponding custom IDs.

Configuration

Properties

The configuration is structured the same way as biomes are defined in Java data packs. Only the water_color property is actually required, everything else is optional. Bedrock will automatically fall back to defaults for properties that are not defined. The configuration supports both integers and strings with a hexadecimal value (#[0-9a-fA-F]{6}).

Bedrock has a separate "weather" fog setting, while Java uses the standard fog_color and does some extra magic in the background, which makes it appear darker than it does in Bedrock. This could be an area of improvement; to add a separate weather_fog_color property to amend this issue.

dry_foliage_color is also not a thing in Bedrock, so its used as a fallback to fill in the foliage color, when foliage_color is not present.

There are also two other properties in bedrock for the fog: lava, and lava_resistance, but since these are not adjustable in Java either, these are left out for now as well.

Required properties

• effects -> water_color

Optional properties

• attributes -> minecraft:visuals/sky_color
• attributes -> minecraft:visuals/fog_color
• attributes -> minecraft:visuals/water_fog_color
• effects -> foliage_color
• effects -> dry_foliage_color
• effects -> grass_color

Example

{
  "format_version": 1,
  "biomes": {
    "example:custom_biome": {
      "attributes": {
        "minecraft:visuals/sky_color": "#78A7FF",
        "minecraft:visuals/fog_color": "#C0D8FF",
        "minecraft:visuals/water_fog_color": "#050533"
      },
      "effects": {
        "water_color": "#3F76E4",
        "foliage_color": "#59AE30",
        "dry_foliage_color": "#59AE30",
        "grass_color": "#7CBD6B"
      }
    },
    "example:custom_biome_2": {
      "attributes": {
        "minecraft:visual/fog_color": 14145761,
        "minecraft:visual/water_fog_color": 329011,
        "minecraft:visual/sky_color": 10858685
      },
      "effects": {
        "water_color": 3750089
      }
    },
    "minecraft:plains": {
      "effects": {
        "water_color": "#3F76E4"
      }
    }
  }
}

Fog Distance

For the fog distance I used the Bedrock defaults, and these are currently not configurable from the biome-visuals.json.

Generated distance fog uses Bedrock's standard ranges:

Environment	Start	End	Distance type
Air	0.92	1.0	Render-relative
Weather, when configured	0.23	0.7	Render-relative
Water	0	60	Fixed blocks

Current Limitations

Java and Bedrock render colors differently

Identical RGB values do not guarantee the output will be the same on both platforms. This is especially noticable with weather fog, where Bedrock's colors will be a lot more vibrant. It seems Java blends the fog color with different colors, including render distance fog, which I don't think Bedrock does (but correct me if I'm wrong).

"Fancy Leaves" might not behave as expected with low biome temperatures

This is a bit of an odd one. Bedrock has a graphics setting called "Fancy Leaves", which can be toggled on or off. When the temperature gets too low (i.e. 0.0, not sure where the threshold is), leaves will not listen to foliage_colors and uses a climate based override. This has the cool effect of turning white when it snows, but the base color can not be overriden. There is one way to get around this, and that is toggling off "Fancy Leaves".

Let's see if Mojang is willing to do anything about it at some point: MCPE-241589

Lava Fog and Lava Resistance Fog are not implemented

This is a limitation in Java 26.2 where it's (for now?) not possible to change fog colors for Lava. It is possible to change in Bedrock, but it would not make sense to expose this when it would be Bedrock-only functionality.

Comparisons

Something to keep in mind, all of the comparisons have been made with the "Fancy" setting in Bedrock, "Vibrant Visuals" might look a bit different, but will still implement these color changes.

Java blends the biome fog colors a bit more, so when standing on the edge between two biomes it will show a blended variant, which looks a bit more pink, rather than the red. Moving over to the right would lead to nearly identical colors.

Java	Bedrock	Bedrock (No Fancy Leaves)

For weather there is a lot more going on in Java with regards to color. In general it seems like the fog gets darkened when there is weather, and once again being on the edge of the biomes doesn't help the blending of the biome colors. Regardless there is quite a significant difference here, which is why I included a separate weather_fog_color for Bedrock.

Java	Bedrock

Underwater colors are a bit more vibrant for Bedrock as well, but generally seem close enough.

Java	Bedrock

Possible Improvements

Some of these color differences could probably be fixed by tweaking fog distances, so it could be a good idea to make this configurable in the biome-visuals.json file in the future. For now I think it serves it's purpose well enough and will at least function as a first step towards parity between Java and Bedrock when it comes to biomes.

AI Usage

For this development I have used some help from Copilot for exploration of the codebase, understanding some Java language features (sorry I'm a .NET dev), also the test code is drafted by AI with some manual adjustments.

[Camotoy]

Thanks for the PR! My initial overarching thought is that the mappings should probably represent the structure of Java datapack custom biomes, similar to what we did with waypoint styles. That way, if people want to manually port over their custom biomes, it's as easy as possible.

[kayvdlans]

Yeah that makes sense. My initial thought was to just flatten it into the simplest form it could possibly be. Will have a look at adjusting it to the structure of the Java datapacks. We would probably be looking at something like this:

{
  "format_version": 1,
  "biomes": {
    "geyser:custom_biome": {
      "attributes": {
        "minecraft:visual/sky_color": "#FFFFFF",
        "minecraft:visual/fog_color": "#FFFFFF",
        "minecraft:visual/water_fog_color": "#FFFFFF"
      },
      "effects": {
        "water_color": "#FFFFFF",
        "foliage_color": "#FFFFFF",
        "dry_foliage_color": "#FFFFFF",
        "grass_color": "#FFFFFF"
      }
    }
  }
}

I already was working on a script that automatically scans a folder for worldgen\biome\ and tries to parse the values into the usable biome-visuals.json to make porting it much simpler. Still needs some work, but managed to get all terralith biomes to be "exported" with a single command.

Also thought I'd share an actual example, rather than the over the top colors:

Java	Bedrock

[kayvdlans]

I updated the structure to represent Java's biome structure, and added the ability to use both integers and strings in a hexadecimal format for better compatibility.

[onebeastchris]

Hello! Thank you for the PR. Structure-wise (mainly API!) we'd prefer the approach taken in #6658 - would you be willing in contributing missing features that are implemented here there? Happy to assist with this - feel free to reach out via discord :)

[kayvdlans]

I will need to have a proper look at it, but after a quick look it seems to implement all the same features (and a little bit more).

Definitely more than okay with moving forward with that PR ^^.

[onebeastchris]

Thank you for understanding! We still appreciate your PR, even if we'll end up merging the linked one.