=============
PipelineBiome
=============

:superscript:`*Config object requires the 'biome-provider-pipeline-v2' addon to use`

A representation of a biome to be distributed across the biome pipeline.

Pipeline biomes may either represent:

- Regular :doc:`/config/documentation/objects/Biome`\s

- Placeholder biomes
  
- Replacement targets
  
Representing Regular Biomes
===========================

If defined as an existing biome's id, then the pipeline biome will simply represent the biome. The pipeline biome representing
a regular biome will use all the regular biome's tags.

Placeholder Biomes
==================

If a pipeline biome does not correspond to any regular biome id, it will be treated as a placeholder biome instead.

Placeholder biomes act as regular biomes being passed through the biome pipeline, but can be used as placeholder names representing
anything you'd like. Conventionally placeholder biomes should be all lowercase to distinguish them from regular biome ids.

For example rather than distributing actual biomes within a :doc:`/config/documentation/objects/Source`\, 
more general 'land' and 'ocean' placeholders can be used:

.. code:: yaml

    source:
      type: SAMPLER
      biomes:
        - land: 1 
        - ocean: 1
      sampler:
        type: OPEN_SIMPLEX_2

For a pipeline to be valid, **it must not be possible for a placeholder biome to be found in the final biome distribution**. This
means that any placeholder biomes introduced into the pipeline must eventually be replaced by pipeline biomes that represent
real biomes.

A placeholder biome ending up in the final distribution is called a 'pipeline leak'.

The above source by itself would not load unless both ``land`` and ``ocean`` are eventually replaced with pipeline
biomes representing regular biomes.

Self Syntax
===========

Pipeline biomes being 'replaced to' may be defined as ``SELF``, which acts as a placeholder for the pipeline biome being replaced.
This is useful when you want to replace pipeline biomes containing a :doc:`/config/documentation/objects/Tag` with themselves in
addition to other biomes.


Uses
====

Used by 7 parameters:

- :ref:`In BORDER_LIST in Stage <object-stage-template-biome-provider-pipeline-v2-border_list-parameter-replace>`:

  :bdg-ref-primary:`replace <object-stage-template-biome-provider-pipeline-v2-border_list-parameter-replace>` :doc:`/config/documentation/objects/Map`\<:doc:`/config/documentation/objects/PipelineBiome`\, :doc:`/config/documentation/objects/WeightedList`\<:doc:`/config/documentation/objects/PipelineBiome`\>> - An additional set of mappings from pipeline biomes to weighted lists of pipeline biomes.

- :ref:`In BORDER_LIST in Stage <object-stage-template-biome-provider-pipeline-v2-border_list-parameter-default-to>`:

  :bdg-ref-primary:`default-to <object-stage-template-biome-provider-pipeline-v2-border_list-parameter-default-to>` :doc:`/config/documentation/objects/WeightedList`\<:doc:`/config/documentation/objects/PipelineBiome`\> - The default list of pipeline biomes to replace pipeline biomes containing the default replace tag with.

- :ref:`In REPLACE_LIST in Stage <object-stage-template-biome-provider-pipeline-v2-replace_list-parameter-to>`:

  :bdg-ref-primary:`to <object-stage-template-biome-provider-pipeline-v2-replace_list-parameter-to>` :doc:`/config/documentation/objects/Map`\<:doc:`/config/documentation/objects/PipelineBiome`\, :doc:`/config/documentation/objects/WeightedList`\<:doc:`/config/documentation/objects/PipelineBiome`\>> - An additional set of mappings from pipeline biomes to weighted lists of pipeline biomes.

- :ref:`In REPLACE in Stage <object-stage-template-biome-provider-pipeline-v2-replace-parameter-to>`:

  :bdg-ref-primary:`to <object-stage-template-biome-provider-pipeline-v2-replace-parameter-to>` :doc:`/config/documentation/objects/WeightedList`\<:doc:`/config/documentation/objects/PipelineBiome`\> - The pipeline biomes that the ``from`` tag will be replaced with.

- :ref:`In BORDER in Stage <object-stage-template-biome-provider-pipeline-v2-border-parameter-to>`:

  :bdg-ref-primary:`to <object-stage-template-biome-provider-pipeline-v2-border-parameter-to>` :doc:`/config/documentation/objects/WeightedList`\<:doc:`/config/documentation/objects/PipelineBiome`\> - The list of pipeline biomes to replace with.

- :ref:`In REPLACE_LIST in Stage <object-stage-template-biome-provider-pipeline-v2-replace_list-parameter-default-to>`:

  :bdg-ref-primary:`default-to <object-stage-template-biome-provider-pipeline-v2-replace_list-parameter-default-to>` :doc:`/config/documentation/objects/WeightedList`\<:doc:`/config/documentation/objects/PipelineBiome`\> - The list of pipeline biomes to replace any matches of the default tag with.

- :ref:`In SAMPLER in Source <object-source-template-biome-provider-pipeline-v2-sampler-parameter-biomes>`:

  :bdg-ref-primary:`biomes <object-source-template-biome-provider-pipeline-v2-sampler-parameter-biomes>` :doc:`/config/documentation/objects/WeightedList`\<:doc:`/config/documentation/objects/PipelineBiome`\>