From 26aac82c1b1aca437e20a91e9b56356e4b3dffa2 Mon Sep 17 00:00:00 2001
From: TelepathicGrunt <40846040+TelepathicGrunt@users.noreply.github.com>
Date: Sat, 16 Nov 2024 11:28:59 -0500
Subject: [PATCH] Mention how to target unregistered biomes (#189)

Co-authored-by: IchHabeHunger54 <52419336+IchHabeHunger54@users.noreply.github.com>
---
 docs/worldgen/biomemodifier.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/docs/worldgen/biomemodifier.md b/docs/worldgen/biomemodifier.md
index d197ad69..e4aa98d5 100644
--- a/docs/worldgen/biomemodifier.md
+++ b/docs/worldgen/biomemodifier.md
@@ -16,12 +16,14 @@ Biome Modifiers are a data-driven system that allows for changing many aspects o
     - [Applying Biome Modifiers](#applying-biome-modifiers)
     - [Built-in Neoforge Biome Modifiers](#built-in-biome-modifiers)
     - [Datagenning Biome Modifiers](#datagenning-biome-modifiers)
+    - [Targeting Biomes That May Not Exist](#targeting-biomes-that-may-not-exist)
 
 
 - Modders who want to do custom or complex biome modifications:
     - [Applying Biome Modifiers](#applying-biome-modifiers)
     - [Creating Custom Biome Modifiers](#creating-custom-biome-modifiers)
     - [Datagenning Biome Modifiers](#datagenning-biome-modifiers)
+    - [Targeting Biomes That May Not Exist](#targeting-biomes-that-may-not-exist)
 
 
 ## Applying Biome Modifiers
@@ -677,6 +679,37 @@ This will then result in the following JSON being created:
 }
 ```
 
+## Targeting Biomes That May Not Exist
+
+There may be times when a biome modifier needs to target a biome that is not always present in the game. If a biome modifier targets the unregistered biome directly, it will crash on world loading. The way to work around this is to create a biome tag and add the target biome as an optional tag entry by setting required to false for the entry. An example is below:
+
+```json5
+{
+  "replace": false,
+  "values": [
+    {
+      "id": "minecraft:pale_garden",
+      "required": false
+    }
+  ]
+}
+```
+
+Using that biome tag for a biome modifier will now not crash if the biome is not registered. A use case for this is the Pale Garden biome in 1.21.3. That biome is only created when you turn on the Winter Drop datapack in-game. Otherwise, the biome does not exist in the biome registry at all. Another use case can be to target modded biomes while still functioning when the mods adding these biomes are not present.
+
+To datagen optional entries for biome tags, the datagen code would look something along these lines:
+
+```json5
+// In a TagsProvider<Biome> subclass
+// Assume we have some example TagKey<Biome> OPTIONAL_BIOMES_TAG
+@Override
+protected void addTags(HolderLookup.Provider registries) {
+    this.tag(OPTIONAL_BIOMES_TAG)
+        // Must be a ResourceLocation representing the registry object
+        .addOptional(WinterDropBiomes.PALE_GARDEN.location());
+}
+```
+
 [datareg]: ../concepts/registries.md#datapack-registries
 [staticreg]: ../concepts/registries.md#methods-for-registering
 [datapacks]: ../resources/index.md#data