Iris/docs/12 - Regions.md

# 12 - Regions

A region is a mid-level spatial unit inside a dimension. File location is `regions/<loadKey>.json`. Each region lists root biomes for land, sea, shore, and optional cave roles, plus regional rarity, zooms, shores, ores, objects, and caves.

Related: see `05 - Concepts & Pack Layout.md`, `11 - Dimensions.md`, `13 - Biomes.md`, `16 - Surfaces, Decorators & Deposits.md`, `20 - Object Placement.md`, `15 - Caves & Carving.md`.

## Role

Dimensions pick regions by noise (`regionStyle` / `regionZoom` / region `rarity`). Within a region, land/sea/shore/cave biome lists pick biomes (also rarity-weighted). Child biomes are **not** listed on the region; only root parents go in the region arrays. Children are declared on the parent biome (`children` field).

Inferred surface roles (`InferredType`): `LAND`, `SEA`, `SHORE`, `CAVE`.

## Load Key

| Rule | Detail |
|------|--------|
| Folder | `regions/` |
| Key | Path relative to `regions/` without `.json` |
| Shipping overworld | Flat files: `temperate.json` → key `temperate` |
| Dimension reference | Dimension `regions` array uses those keys |

## Field Reference (`IrisRegion`)

### Identity and rarity

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `name` | string | `"A Region"` | Required display name |
| `rarity` | int | `1` | 1–128; higher = rarer when competing among dimension regions |
| `color` | string | `null` | Map visualization color, e.g. `#9BEE61` |

### Biome lists

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `landBiomes` | string[] | **Yes** | Root land biome load keys |
| `seaBiomes` | string[] | No | Root sea biomes; empty allowed for land-only worlds |
| `shoreBiomes` | string[] | No | Root shore biomes; empty allowed for land-only worlds |
| `caveBiomes` | string[] | No (array type allows empty) | Root cave biomes for carving/cave selection |

Keys are biome load keys under `biomes/` (e.g. `temperate/plains`, `carving/drip`).

### Biome and shore zooms

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `landBiomeZoom` | double | `1` | Land biome size in this region |
| `shoreBiomeZoom` | double | `1` | Shore biome size |
| `seaBiomeZoom` | double | `1` | Sea biome size |
| `caveBiomeZoom` | double | `1` | Cave biome size |
| `shoreHeightMin` | double | `1.2` | Min shore height contribution |
| `shoreHeightMax` | double | `3.2` | Max shore height contribution |
| `shoreHeightZoom` | double | `3.14` | Shore height noise zoom |

### Rivers and lakes (style)

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `riverStyle` | `IrisGeneratorStyle` | `VASCULAR_THIN` zoomed `7.77` | River placement style |
| `lakeStyle` | `IrisGeneratorStyle` | `CELLULAR_IRIS_THICK` | Lake placement style |

### Content attachments

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `objects` | `IrisObjectPlacement[]` | empty | Region-wide `.iob` placements |
| `proceduralObjects` | `IrisProceduralObjects` | empty | Trees/ruins/formations/coral/fungi/crystals generated procedurally |
| `structures` | `IrisStructurePlacement[]` | empty | Jigsaw / native structure placements |
| `entitySpawners` | string[] | empty | `IrisSpawner` load keys |
| `effects` | `IrisEffect[]` | empty | Packet ambient effects (potions, sounds, particles) |
| `loot` | `IrisLootReference` | empty | Region loot |
| `blockDrops` | `IrisBlockDrops[]` | empty | Custom drops |
| `deposits` | `IrisDepositGenerator[]` | empty | Regional deposits added to global |
| `depositVariants` | `IrisDepositVariant[]` | empty | Ore remaps after biome, before dimension |
| `ores` | `IrisOreGenerator[]` | empty | Regional ores (surface vs underground flags) |
| `caveProfile` | `IrisCaveProfile` | default | Region cave profile |

Deposit precedence (documented on fields): biome variants → region variants → dimension variants; first match wins at each tier.

## Overworld Sample: Temperate

Path: `…/packs/overworld/regions/temperate.json`

| Field | Value |
|-------|-------|
| `name` | `Temperate` |
| `color` | `#9BEE61` |
| `rarity` | `1` |
| `landBiomes` | Many temperate + mountain + vanilla roots (e.g. `temperate/plains`, `vanilla/cherry_grove`) |
| `shoreBiomes` | Beaches including `vanilla/stony_shore` |
| `seaBiomes` | Oceans/rivers (`ocean/deep`, `temperate/sea/river`, …) |
| `caveBiomes` | `carving/rocky-cavebiome`, `carving/deep`, `carving/drip`, … |
| `landBiomeZoom` | `3.5` |
| `seaBiomeZoom` | `6` |
| `shoreBiomeZoom` | `0.15` |
| `caveBiomeZoom` | `3.3` |
| `shoreHeightMin` / `Max` / `Zoom` | `1` / `5.2` / `1.14` |
| `deposits` | Iron/coal band example |
| `loot` | `FALLBACK` mode, temperate tables |
| `caveProfile` | Enabled with density/threshold/surface settings |

Shipping overworld region keys (from dimension `regions` list): `frozen`, `hot`, `terralost`, `mushroom`, `forests`, `tundra`, `magnetics`, `temperate`, `estranged`, `tropical`, `swamp`, `prismatics`.

## Minimal Region JSON

```json
{
  "name": "Starter",
  "rarity": 1,
  "landBiomes": ["starter"],
  "seaBiomes": ["starter"],
  "shoreBiomes": ["starter"]
}
```

Land-only dimension (no ocean shoreline generated):

```json
{
  "name": "Highlands",
  "rarity": 2,
  "landBiomes": ["highlands/plateau"],
  "seaBiomes": [],
  "shoreBiomes": []
}
```

## How To: Make a Region

1. Create `regions/<key>.json`.
2. Set `name` and `rarity`.
3. List **root** biomes only under `landBiomes` (and sea/shore/cave as needed). Keys must match files under `biomes/` (subfolders become path segments in the key).
4. Add the region key to the dimension’s `regions` array.
5. Tune `landBiomeZoom` / `seaBiomeZoom` / `shoreBiomeZoom` after biomes look right.
6. Optionally add regional `deposits`, `ores`, `objects`, `structures`, `caveProfile`.
7. Studio: set dimension `"focusRegion": "<key>"` to generate only that region while authoring.

## Resolution Notes

- `getAllBiomeIds()` unions land, cave, sea, and shore lists.
- Child expansion walks each biome’s `children` and `carvingBiome` through the pack loader (cyclic graphs stop after depth limit on biomes; region walks keep collecting until the name set empties).
- Shore height at a column uses noise fitted between `shoreHeightMin` and `shoreHeightMax` with `shoreHeightZoom`.
- Object lists are filtered into surface vs carving support by placement `carvingSupport`.

## Common Author Mistakes

| Mistake | Result |
|---------|--------|
| Listing child biomes on the region | Children should be on the parent biome; listing children as roots duplicates or skips intended nesting |
| Region not listed on dimension | Never selected |
| Empty `landBiomes` | Invalid region for normal overworld generation |
| Wrong biome key path | `temperate/plains` must match `biomes/temperate/plains.json` |
| Relying on region rarity alone | Dimension also uses noise style/zoom; sample with `/iris studio regions` |