Updated Docs, and Cortections

2026-08-27 12:41:43 +00:00 · 2026-08-08 00:29:48 -06:00
parent c40e1cf152
commit 506787f51a
70 changed files with 9485 additions and 3050 deletions
@@ -0,0 +1,416 @@
+# 13 - Biomes
+
+A biome is the primary surface/authoring unit for terrain height, block layers, decorations, objects, and Minecraft biome derivatives. Files live under `biomes/<loadKey>.json`. Regions reference root biomes; biomes may nest children and optional custom datapack biomes.
+
+Related: see `12 - Regions.md`, `14 - Generators & Noise.md`, `16 - Surfaces, Decorators & Deposits.md`, `17 - Trees, Fungi, Coral, Crystals, Formations, Ruins.md`, `19 - Objects.md`, `20 - Object Placement.md`, `23 - Loot, Entities, Spawners, Markers.md`.
+
+## Role
+
+| Layer | Responsibility |
+|-------|----------------|
+| Region lists | Choose which root biomes can appear |
+| Biome `generators` | Height relative to dimension `fluidHeight` |
+| Biome `layers` | Surface and subsurface material stacks |
+| `derivative` / `vanillaDerivative` | Minecraft biome for colors and structure eligibility |
+| `customDerivitives` | Optional custom datapack biomes (field spelling is intentional in code) |
+| Objects / structures / decorators | Placement and decoration on this biome |
+
+`InferredType` (`LAND`, `SEA`, `SHORE`, `CAVE`) is assigned from which region list selected the biome, not from a JSON field on the biome itself.
+
+## Load Key
+
+| Rule | Detail |
+|------|--------|
+| Folder | `biomes/` |
+| Key | Relative path without `.json` |
+| Examples | `starter` → `biomes/starter.json`; `temperate/plains` → `biomes/temperate/plains.json`; `carving/drip` → `biomes/carving/drip.json` |
+
+## Core Fields (`IrisBiome`)
+
+### Identity
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `name` | string | `"Subterranean Land"` | Required human-readable name (not the load key) |
+| `rarity` | int | `1` | 1–512; rarity among sibling biomes in a region list |
+| `color` | string | `null` | Map color, e.g. `#42A616` |
+
+### Minecraft derivatives (required for generation)
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `derivative` | string (biome key) | `"minecraft:the_void"` | **Required.** Vanilla/mod biome used for Iris terrain/color resolution |
+| `vanillaDerivative` | string | `null` → falls back to `derivative` | Structure selection derivative; land/sea/shore eligibility rules apply for vanilla namespaces |
+| `biomeScatter` | string[] | empty | Extra derivatives for color scatter |
+| `biomeSkyScatter` | string[] | empty | Derivatives above terrain (3D biome colors) |
+| `biomeStyle` | `IrisGeneratorStyle` | `SIMPLEX` | Scatter dispersion when multiple derivatives |
+
+Use namespaced keys (`minecraft:plains`) or bare vanilla paths accepted by `NamespacedKey` resolution.
+
+### Children and carving
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `children` | string[] | empty | Child biome load keys; portions of this biome morph into children |
+| `childShrinkFactor` | double | `1.5` | Child size vs parent (docs suggest ~1–3) |
+| `childStyle` | `IrisGeneratorStyle` | `CELLULAR_IRIS_DOUBLE` | Child shape noise |
+| `carvingBiome` | string | `""` | Biome used under carving instead of this one when set |
+| `caveMinDepthBelowSurface` | int | `0` | Min depth below surface before this cave biome can be picked |
+
+Cyclic child graphs are supported; Iris stops walking children after a depth limit (annotation: nine biomes down the tree).
+
+### Generators (height)
+
+Type: `IrisBiomeGeneratorLink` (`@Snippet("generator-layer")`).
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `generator` | string | `"default"` | Load key under `generators/` |
+| `min` | int | `0` | Height offset min relative to fluid height (−2032…2032) |
+| `max` | int | `0` | Height offset max relative to fluid height |
+
+Height is lerped from generator noise in \[0,1\] into \[min, max\], then added relative to fluid height. Negative min/max produce ocean floors.
+
+Multiple generator links mix with other biomes’ generators as expected when interpolation sizes differ.
+
+### Layers (block palettes)
+
+Type: `IrisBiomePaletteLayer` (`@Snippet("biome-palette")`).
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `palette` | `IrisBlockData[]` | grass_block | **Required.** Weighted blocks |
+| `minHeight` | int | `1` | Min layer thickness (0–2032) |
+| `maxHeight` | int | `1` | Max layer thickness (1–2032) |
+| `style` | `IrisGeneratorStyle` | `STATIC` | Multi-block palette noise |
+| `zoom` | double | `5` | Palette noise zoom |
+| `slopeCondition` | `IrisSlopeClip` | empty | Optional slope gate/growth |
+
+`IrisBlockData` entries:
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `block` | string | `"air"` | Block id, e.g. `minecraft:grass_block` |
+| `weight` | int | `1` | Relative pick weight |
+| `data` | map | empty | Block state properties |
+| `backup` | block data | optional | Fallback if block missing |
+| `debug` | boolean | false | Console debug when Iris debug enabled |
+
+Biome layer stacks:
+
+| Field | Role |
+|-------|------|
+| `layers` | Surface-down stack (required; default one empty grass layer) |
+| `seaLayers` | Underwater surface layers |
+| `caveCeilingLayers` | Cave ceiling material stack |
+| `slab` | Default slab layer for post slabs (default empty/zero palette) |
+| `wall` | Steep-face wall palette (default empty/zero) |
+| `lockLayers` | When true, layers descend from max biome height (mesa style) |
+| `lockLayersMax` | Max layers when locked (default `7`) |
+
+Below authored layers, Iris fills with the dimension rock palette.
+
+### Custom biomes (`customDerivitives`)
+
+**JSON field name is `customDerivitives`** (misspelling of “derivatives” preserved in `IrisBiome`).
+
+Type: `IrisBiomeCustom` (`@Snippet("custom-biome")`). Installed via datapack compilation.
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `id` | string | `""` | **Required.** Resource path id (lowercased), e.g. `oak_forest` |
+| `category` | `IrisBiomeCustomCategory` | `plains` | **Required.** Vanilla category enum |
+| `temperature` | double | `0.8` | −3…3 |
+| `humidity` | double | `0.4` | −3…3 (downfall amount) |
+| `downfallType` | `IrisBiomeCustomPrecipType` | `rain` | `none`, `rain`, `snow` |
+| `spawnRarity` | int | `0` | 0–20 creature spawn probability |
+| `spawns` | `IrisBiomeCustomSpawn[]` | empty | Custom mob spawns |
+| `tags` | string[] | empty | Explicit biome tags |
+| `ambientParticle` | `IrisBiomeCustomParticle` | null | Client particle |
+| `skyColor` | hex string | `#79a8e1` | |
+| `fogColor` | hex string | `#c0d8e1` | |
+| `waterColor` | hex string | `#3f76e4` | |
+| `waterFogColor` | hex string | `#050533` | |
+| `grassColor` | hex string | `""` (omit if empty) | |
+| `foliageColor` | hex string | `""` | |
+
+Tag inheritance: effective tags = authored `tags` plus non-structure tags of the vanilla derivative. Structure tags (`has_structure/*`) are **not** inherited so native structures are not double-placed.
+
+#### Custom spawn entry (`IrisBiomeCustomSpawn`)
+
+| Field | Type | Default |
+|-------|------|---------|
+| `type` | entity key | `minecraft:cow` |
+| `minCount` | int | `2` |
+| `maxCount` | int | `5` |
+| `weight` | int | `1` |
+| `group` | `IrisBiomeCustomSpawnType` | `MISC` |
+
+Spawn groups: `MONSTER`, `CREATURE`, `AMBIENT`, `AXOLOTLS`, `UNDERGROUND_WATER_CREATURE`, `WATER_CREATURE`, `WATER_AMBIENT`, `MISC`.
+
+#### Custom categories (`IrisBiomeCustomCategory`)
+
+`beach`, `desert`, `extreme_hills`, `forest`, `icy`, `jungle`, `mesa`, `mushroom`, `nether`, `none`, `ocean`, `plains`, `river`, `savanna`, `swamp`, `taiga`, `the_end`.
+
+#### Ambient particle (`IrisBiomeCustomParticle`)
+
+| Field | Default |
+|-------|---------|
+| `particle` | `minecraft:flash` |
+| `rarity` | `35` (higher = rarer; probability `1/rarity` in datapack JSON) |
+
+### Decorators, objects, structures, ores
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `decorators` | `IrisDecorator[]` | Tall grass, cactus, kelp-style placements (see `16 - Surfaces, Decorators & Deposits.md`) |
+| `objects` | `IrisObjectPlacement[]` | `.iob` placements |
+| `proceduralObjects` | `IrisProceduralObjects` | Procedural trees/coral/etc. |
+| `structures` | `IrisStructurePlacement[]` | Jigsaw / native structures |
+| `floatingChildBiomes` | `IrisFloatingChildBiomes[]` | Floating islands using another biome’s visuals |
+| `mergeFloatingChildBiomes` | boolean | When true, all floating entries sample independently |
+| `deposits` | `IrisDepositGenerator[]` | Biome deposits |
+| `depositVariants` | `IrisDepositVariant[]` | Ore remaps (first of biome tier) |
+| `oreDepositFrequencyMultiplier` | double | 0–1 scale ore vein frequency (default `1`) |
+| `oreDepositSizeMultiplier` | double | 0.01–16 scale ore size (default `1`) |
+| `ores` | `IrisOreGenerator[]` | Biome ores |
+| `entitySpawners` | string[] | Spawner keys |
+| `effects` | `IrisEffect[]` | Ambient effects |
+| `loot` | `IrisLootReference` | Biome loot |
+| `blockDrops` | `IrisBlockDrops[]` | Custom drops |
+| `caveProfile` | `IrisCaveProfile` | Biome cave profile override |
+
+## Floating child biomes (`IrisFloatingChildBiomes`)
+
+`floatingChildBiomes` builds floating terrain above columns owned by the parent biome. Each entry can reuse the parent or reference another biome for its generators, layers, derivative, decorators, and surface objects. With `mergeFloatingChildBiomes: false` (default), `pickerStyle` and `rarity` select one entry per column; with it true, every entry samples independently and islands may overlap.
+
+### Target, footprint, and altitude
+
+| Field | Default / range | Behavior |
+|-------|-----------------|----------|
+| `biome` | `""` | Target biome key; empty, missing, or the parent key falls back to the parent biome |
+| `rarity` | `1` (1–512) | Relative selection rarity; lower values are more common |
+| `footprintStyle` | `SIMPLEX` | 2D island-outline noise; style zoom and fracture control scale and warping |
+| `footprintThreshold` | `0.5` (0–1) | Minimum footprint sample; higher values produce less coverage |
+| `pickerStyle` | `SIMPLEX` | Coherent per-column entry selection when entries are not merged |
+| `altitudeStyle` | `SIMPLEX` | Varies the island base between the configured heights |
+| `minHeightAboveSurface` / `maxHeightAboveSurface` | `160` / `210` (0–2032) | Absolute world-Y range for the base despite the historical field names |
+| `minAbsoluteY` | `null` | Optional lower clamp for the base/tail |
+| `maxAbsoluteY` | `null` | Optional upper clamp for the island top |
+
+### Edge, top, and underside shape
+
+| Field | Default / range | Behavior |
+|-------|-----------------|----------|
+| `edgeTaperWidth` | runtime default (2–32) | Width of the rounded contour-to-full-thickness transition |
+| `edgeTaperExponent` | runtime default (0.25–4) | Below 1 makes a fuller edge; above 1 keeps the rim thinner |
+| `edgeTaperVariationStyle` | broad `SIMPLEX` | Coherently varies taper width without changing the footprint |
+| `edgeTaperVariationAmplitude` | `0` (0–8) | Local widening/narrowing; runtime clamps the resulting width to 2–32 |
+| `topShapeMode` | `BIOME` | `BIOME` uses target generators; `NOISE` uses `topShapeStyle`; `FLAT` uses a fixed top |
+| `maxTopHeight` | `40` (0–512) | Maximum height above the island base |
+| `topShapeStyle` | `SIMPLEX` | Top heightmap when mode is `NOISE` |
+| `topShapeAmp` | `1` (0–1) | Multiplier for the noise-driven top profile |
+| `bottomStyle` | `SIMPLEX` | 2D noise for the hanging underside/tail |
+| `bottomDepthMin` / `bottomDepthMax` | `4` / `20` (0–512) | Tail depth range below the base |
+| `bottomExponent` | `1` (0.1–8) | Power curve for tail depth; above 1 makes deep tails sparser |
+| `maxThickness` | `96` (1–512) | Hard cap on top-to-bottom column thickness |
+| `wallWarpStyle` | `null` | Optional 3D noise that shifts X/Z footprint samples by Y layer |
+| `wallWarpAmplitude` | `6` (0–64) | Maximum wall-warp displacement; ignored without `wallWarpStyle` |
+
+### Materials, fluids, and carving
+
+| Field | Default | Behavior |
+|-------|---------|----------|
+| `bottomPaletteMode` | `DEPTH` | `DEPTH` uses normal top-down layers; `MIRROR_TOP` mirrors the shallow palette; `CUSTOM` uses `bottomPalette` near the underside |
+| `bottomPalette` | `[]` | `IrisBiomePaletteLayer[]` used only by `CUSTOM` |
+| `localFluidHeight` | `null` | Fluid surface relative to the island base; null disables internal pools |
+| `fluidBlock` | `minecraft:water` | Block used for internal pools |
+| `carveStyle` | `null` | Optional direct 3D pocket noise |
+| `carving` | `""` | Optional dimension carving-entry id or biome key; dimension entries resolve first and their cave profile overrides `carveStyle` |
+| `carveThreshold` | `1` (0–1) | Direct noise above this value becomes air; with `carving`, tunes the referenced cave profile |
+
+### Decoration and objects
+
+| Field | Default | Behavior |
+|-------|---------|----------|
+| `inheritDecorators` | `true` | Apply target-biome decorators to the island top |
+| `inheritObjects` | `true` | Allow target-biome surface objects on the island top |
+| `objectShrinkFactor` | `1` (0.01–1) | Uniform scale for inherited, extra, and free-floating objects |
+| `extraObjects` | `[]` | Additional `IrisObjectPlacement` entries anchored to the island top |
+| `floatingObjects` | `[]` | Additional placements generated independently in air with floating placement mode |
+| `topObjectMode` | `INHERIT_ONLY` | `INHERIT_ONLY`, `MERGE`, or `REPLACE` for inherited top objects versus overrides |
+| `topObjectOverrides` | `[]` | Top placements consumed according to `topObjectMode` |
+| `bottomObjectMode` | `INHERIT_ONLY` | Enables `bottomObjectOverrides`; `MERGE` and `REPLACE` are equivalent because there is no inherited bottom set |
+| `bottomObjectOverrides` | `[]` | Placements attached upside-down to the lowest solid face; directional blocks may not survive the flip correctly |
+| `color` | `null` | Iris Studio visualization color |
+
+Example:
+
+```json
+{
+  "floatingChildBiomes": [{
+    "biome": "temperate/plains",
+    "rarity": 2,
+    "footprintStyle": { "style": "SIMPLEX", "zoom": 0.8 },
+    "footprintThreshold": 0.7,
+    "minHeightAboveSurface": 160,
+    "maxHeightAboveSurface": 210,
+    "topShapeMode": "BIOME",
+    "bottomDepthMin": 6,
+    "bottomDepthMax": 28,
+    "inheritDecorators": true,
+    "inheritObjects": true
+  }]
+}
+```
+
+## Overworld Samples
+
+### Land plains — `biomes/temperate/plains.json`
+
+```json
+{
+  "name": "Plains",
+  "color": "#42A616",
+  "rarity": 2,
+  "derivative": "minecraft:plains",
+  "vanillaDerivative": "minecraft:plains",
+  "generators": [{ "min": 4, "max": 10, "generator": "plain" }],
+  "biomeStyle": { "style": "SIMPLEX" },
+  "wall": { "palette": [{ "block": "minecraft:stone" }, { "block": "minecraft:andesite" }] },
+  "layers": [
+    { "palette": [{ "block": "minecraft:grass_block" }] },
+    { "minHeight": 2, "maxHeight": 2, "palette": [{ "block": "minecraft:dirt" }] }
+  ]
+}
+```
+
+(File continues with more layers, objects, and placements.)
+
+### Parent with children and custom biome — `biomes/temperate/oak-forest.json`
+
+```json
+{
+  "name": "Oak Forest",
+  "derivative": "minecraft:forest",
+  "vanillaDerivative": "minecraft:forest",
+  "customDerivitives": [{
+    "id": "oak_forest",
+    "foliageColor": "#64B233",
+    "grassColor": "#77A620",
+    "category": "forest"
+  }],
+  "children": ["temperate/oak-forest-extended"],
+  "generators": [
+    { "generator": "smooth-dunes", "max": 12, "min": 5 },
+    { "generator": "rare-hills", "max": 40, "min": 0 }
+  ]
+}
+```
+
+### Sea biome heights — `biomes/temperate/sea/ocean.json` (excerpt)
+
+```json
+{
+  "name": "Temperate Ocean",
+  "derivative": "minecraft:lukewarm_ocean",
+  "vanillaDerivative": "minecraft:ocean",
+  "generators": [{ "min": -32, "max": -10, "generator": "mountain" }]
+}
+```
+
+Negative generator min/max place the surface below fluid height.
+
+### Custom-only colors — `biomes/vanilla/sunflower_plains.json` (excerpt)
+
+```json
+{
+"customDerivitives": [{
+  "category": "plains",
+  "id": "sunflower_plains",
+  "grassColor": "#91BD59",
+  "foliageColor": "#77AB2F",
+  "waterColor": "#44AFF5",
+  "downfallType": "none"
+}]
+}
+```
+
+## Minimal Biome JSON
+
+Studio starter:
+
+```json
+{
+  "name": "Starter Plains",
+  "layers": [{ "palette": [{ "block": "minecraft:grass_block" }] }],
+  "generators": [{ "generator": "flat", "min": 96, "max": 96 }],
+  "derivative": "minecraft:plains",
+  "vanillaDerivative": "minecraft:plains"
+}
+```
+
+Requires a matching generator file under `generators/` (starter uses `generators/flat.json`).
+
+## How To: Make a Biome
+
+1. Add `biomes/<path>/<name>.json`. Choose load key path carefully; regions will reference it exactly.
+2. Set `name`, `derivative`, `vanillaDerivative`.
+3. Add at least one `generators` link and a generator JSON under `generators/`.
+4. Define `layers` from topsoil down (grass → dirt → stone blend).
+5. Optionally set `wall` for cliffs, `decorators` for grass, `objects` for trees/clutter.
+6. For variants inside a parent, create a child biome file and list its key in the parent’s `children`.
+7. For custom colors/tags/mobs, add `customDerivitives` with a unique `id` and `category`.
+8. Attach the biome to a region: land → `landBiomes`, ocean floor → `seaBiomes`, beach → `shoreBiomes`, cave → `caveBiomes`.
+9. Studio test: dimension `"focus": "temperate/plains"` forces only that biome.
+
+## Generator Link How-To
+
+1. Create or reuse `generators/<id>.json` (noise composite + interpolator; see `14 - Generators & Noise.md`).
+2. On the biome:
+
+```json
+{
+"generators": [
+  { "generator": "plain", "min": 4, "max": 10 }
+]
+}
+```
+
+3. Land: positive min/max above fluid. Sea: negative min/max. Flat plateaus: min == max.
+
+## Custom Biome How-To
+
+1. Add:
+
+```json
+{
+"customDerivitives": [
+  {
+    "id": "my_plains",
+    "category": "plains",
+    "temperature": 0.8,
+    "humidity": 0.4,
+    "downfallType": "rain",
+    "grassColor": "#91BD59",
+    "foliageColor": "#77AB2F"
+  }
+]
+}
+```
+
+2. Keep `derivative` / `vanillaDerivative` set to a close vanilla biome for structure eligibility and tag inheritance.
+3. Open studio or recreate the world so datapack custom biomes install (create/open may require restart when datapacks change).
+4. Do not invent field names like `customDerivatives` — the engine field is `customDerivitives`.
+
+## Common Author Mistakes
+
+| Mistake | Result |
+|---------|--------|
+| Missing `derivative` | Terrain/biome resolution fails or voids |
+| Wrong generator key | Falls back to empty default generator behavior |
+| Listing child biomes on the region | Breaks parent/child hierarchy intent |
+| `customDerivatives` spelling | Field ignored; use `customDerivitives` |
+| Sea biome with positive generators | “Ocean” generates as land relative to fluid |
+| Empty `layers` palette | Missing surface blocks |
+| Expecting biome `type` field | Role comes from region list membership (`InferredType`) |