Creating a Biome Provider from Scratch

This guide will outline the process of creating a biome provider from the beginning using the pipeline type to distribute biomes.

If you haven’t already, please read the Config Development Introduction & Creating A Pack From Scratch for more information before continuing.

For a more detailed and in-depth guide about creating a new biome provider from scratch, please read this unofficial development guide, Pipeline Biome Provider.

If you’re stuck or need an example, you can find reference config packs for this guide on the GitHub repo.

Setting up a New Pipeline

PROCEDURE

1. Add pipeline biome provider

A biome provider determines and configures where biomes will generate in the world.

The pipeline biome provider is typically used to procedurally distribute biomes in 2D.

The pipeline operates utilizing an initial biome layout that goes through consecutive stages that modify this layout to a final layout result that determines the biome distribution placement.

Open your pack manifest in your editor of choice.

Add the biome-provider-pipeline-v2 addon as a dependency, using versions 1.+.

This addon will allow us to create a pipeline biome provider.

pack.yml
1id: YOUR_PACK_ID
2version: 0.6.0
3
4addons:
5  ...
6  biome-provider-pipeline-v2: "1.+"

Add the highlighted lines below to replace the current SINGLE biome provider and start creating the biome pipeline.

pack.yml
1id: YOUR_PACK_ID
2
3...
4
5biomes:
6  type: PIPELINE
7  resolution: 4

resolution determines the size of each biome ‘pixel’ in blocks.

Increasing resolution will improve performance at the cost of blocky edges in biome placement with a resolution of 4 being the best balance between performance and obvious blocky edges.

2. Add pipeline blending

The biome pipeline will require blending that will warp the edges between biomes in order to lessen the blocky edges created from the pipeline resolution increase.

Add the highlighted lines below to add blending to the biome pipeline.

OPEN_SIMPLEX_2 will be utilized for this.

pack.yml
 1id: YOUR_PACK_ID
 2
 3...
 4
 5biomes:
 6  type: PIPELINE
 7  resolution: 4
 8  blend:
 9    amplitude: 2
10    sampler:
11      type: OPEN_SIMPLEX_2
12      frequency: 0.1

blend.amplitude determines the strength of the blending between each biome.

blend.sampler will contain the noise sampler and its parameters that will blend the edges between biomes.

Note

Documentation of OPEN_SIMPLEX_2 and other noise samplers can be found here.

3. Add the pipeline source

The biome pipeline will require a source that will serve as the initial biome layout.

Add the highlighted lines below to add a source to the biome pipeline.

pack.yml
 1id: YOUR_PACK_ID
 2
 3...
 4
 5biomes:
 6  type: PIPELINE
 7  resolution: 4
 8  blend:
 9    amplitude: 2
10    sampler:
11      type: OPEN_SIMPLEX_2
12      frequency: 0.1
13  pipeline:
14    source:
15      type: SAMPLER
16      sampler:
17        dimensions: 2
18        type: CONSTANT
19      biomes:
20        - land: 1

source.sampler utilizes a noise sampler to distribute the initial biome layout. We’ll leave it as CONSTANT as this is a rather simple pipeline source.

source.biomes consists of the weighted list of pipeline biomes that will serve as the initial layout.

In this case, we’re using a placeholder or ephemeral pipeline biome that will have to be replaced by an actual biome through a pipeline stage later on, otherwise the pack won’t load.

Tip

It is best to put placeholder biomes in all lowercase to distinguish them from biome IDs that are typically in all uppercase.

4. Add the pipeline stage

The biome pipeline will require a stage to replace the placeholder biome that the source initially laid out.

Add the highlighted lines below to add a REPLACE stage to the biome pipeline.

pack.yml
 1id: YOUR_PACK_ID
 2
 3...
 4
 5biomes:
 6  type: PIPELINE
 7  resolution: 4
 8  blend:
 9    amplitude: 2
10    sampler:
11      type: OPEN_SIMPLEX_2
12      frequency: 0.1
13  pipeline:
14    source:
15      type: SAMPLER
16      sampler:
17        dimensions: 2
18        type: CONSTANT
19      biomes:
20        - land: 1
21    stages:
22      - type: REPLACE
23        sampler:
24          type: OPEN_SIMPLEX_2
25          frequency: 0.01
26        from: land
27        to:
28          - FIRST_BIOME: 1
29          - SECOND_BIOME: 1

The stages parameter consists of the list of pipeline stages that will modify the source layout.

The REPLACE pipeline stage utilizes the parameters sampler, from, and to.

  • Sampler - Determines the noise sampler that will influence replacement biome selection

  • From - Specifies the tag or biome that will be replaced

  • To - Specifies the weighted list of pipeline biome(s) that will replace the from biome

Weighted lists covered in detail here.

Note

Biomes other than FIRST_BIOME will need to be sourced to have another biome to distribute through the pipeline.

There is a SECOND_BIOME sample with a palette located on GitHub, which is also shown below.

second_biome.yml
 1id: SECOND_BIOME
 2type: BIOME
 3vanilla: minecraft:desert
 4
 5terrain:
 6  sampler:
 7    type: EXPRESSION
 8    dimensions: 3
 9    expression: -y + 64
10
11  sampler-2d:
12    type: EXPRESSION
13    dimensions: 2
14    expression: (simplex(x, z)+1) * 2
15    samplers:
16      simplex:
17        type: OPEN_SIMPLEX_2
18        dimensions: 2
19        frequency: 0.04
20
21palette:
22  - SAND_PALETTE: 319
sand_palette.yml
 1id: SAND_PALETTE
 2type: PALETTE
 3
 4layers:
 5  - materials: minecraft:sand
 6    layers: 3
 7  - materials: minecraft:sandstone
 8    layers: 2
 9  - materials: minecraft:stone
10    layers: 1

Tip

You can utilize multiple stages consecutively to further distribute the biome placement with SELF representing the from biome being replaced.

pack.yml
 1stages:
 2  - type: REPLACE
 3    sampler:
 4      type: OPEN_SIMPLEX_2
 5      frequency: 0.01
 6    from: land
 7    to:
 8      - FIRST_BIOME: 1
 9      - SECOND_BIOME: 1
10      - THIRD_BIOME: 1
11
12  - type: REPLACE
13    sampler:
14      type: OPEN_SIMPLEX_2
15      frequency: 0.01
16      salt: 3423
17    from: FIRST_BIOME
18    to:
19      - SELF: 1
20      - FOURTH_BIOME: 1

For the case above, the land placeholder biome will be distributed into the FIRST_BIOME, SECOND_BIOME, and THIRD_BIOME by the first REPLACE stage then the following REPLACE stage will distribute the FIRST_BIOME into FIRST_BIOME represented by SELF and FOURTH_BIOME as well.

5. Load your pack

At this stage, your pack should now be capable of biome distribution! You can load up your pack by starting your development client / server which contains the pack you have just defined. You can confirm that your pack has loaded if the pack id (as specified in the pack manifest) appears when using the /packs command, or in your console when starting the server / client up.

If for whatever reason your pack does not load, an error message will show up in console explaining why the pack has failed to load, please read through any of these errors and try to interpret what you may have done wrong, and follow through the previous steps again carefully.

If you still are unable to load the pack, feel free to contact us with any relevant errors.

Note

The /packs reload command cannot be used when new biome config files are added to a config pack since the biome registry gets frozen upon world generation.

Using the command will result with a An internal error occured while attemping to perform this command message.

Clients might only need to create a new world while servers may need to completely restart in order to load new biomes when the biome registry isn’t frozen.

Tip

A useful tool for visually previewing the biome distribution defined by your biome provider is the Biome Tool that can be found here.

Conclusion

Once you have verified your pack has loaded correctly, you can now generate a world with multiple biomes distributed through the biome provider pipeline!

Reference configurations for this guide can be found on GitHub here.

../../../_images/pipeline.png