Iris/docs/11 - Dimensions.md

# 11 - Dimensions

A dimension is the root pack object for a world type. File location is `dimensions/<loadKey>.json` (folder name from `IrisDimension.getFolderName()`). Regions, height, fluid, noise zooms, ores, caves, structures, and engine mode all hang off this object.

Related: see `05 - Concepts & Pack Layout.md`, `10 - Studio & VSCode Schemas.md`, `12 - Regions.md`, `14 - Generators & Noise.md`, `15 - Caves & Carving.md`, `22 - Native Structures & Datapacks.md`, `26 - Example - Minimal Dimension.md`.

## Role in the Pack Graph

```
Dimension → regions[] → Region → land/sea/shore/cave biomes[] → Biome
         → generators (via biomes)
         → objects / structures / ores / deposits / caves
```

World create/open selects a pack dimension load key. Studio and production both load `IrisDimension` from that file.

## Load Key and File Name

| Rule | Detail |
|------|--------|
| Load key | Path relative to `dimensions/` without `.json` |
| Typical | `dimensions/overworld.json` → key `overworld` |
| Nested | `dimensions/foo/bar.json` → key `foo/bar` if used (shipping overworld uses a single top-level file matching the pack name) |
| Starter create | Writes `dimensions/<projectName>.json` with matching `name` |

## Engine Modes (`mode`)

Object type: `IrisDimensionMode` (`@Snippet("dimension-mode")`).

| JSON path | Type | Default | Meaning |
|-----------|------|---------|---------|
| `mode.type` | `IrisDimensionModeType` | `OVERWORLD` | Selects the engine mode factory |

Enum `IrisDimensionModeType`:

| Type | Annotation summary | Runtime stages (code) |
|------|--------------------|------------------------|
| `OVERWORLD` | Full biome world with fluid height | Biomes, mantle matter, terrain, carving, post, floating child biomes, deposits, matter insert, decoration, perfection, custom modifiers (`ModeOverworld`) |
| `SUPERFLAT` | Ultra fast; terrain & biomes only | Terrain + biome actuators only (`ModeSuperFlat`); no decoration/mantle/carve/deposit stages registered |
| `ENCLOSURE` | Ceiling & floor carved style (nether-like intent) | Same stage registration as SuperFlat today (`ModeEnclosure`): terrain + biome only |
| `ISLANDS` | Floating islands intent | Same stage registration as SuperFlat today (`ModeIslands`): terrain + biome only |

JSON shape:

```json
{
"mode": {
  "type": "OVERWORLD"
}
}
```

The field is annotated `@Required`. Gson still applies the default `IrisDimensionMode` when omitted. The shipping overworld pack does not set `mode` and therefore runs as `OVERWORLD`.

If mode construction fails, the engine logs a warning and falls back to `OVERWORLD`.

## Height, Fluid, and Environment

| Field | Type | Default | Constraints / notes |
|-------|------|---------|---------------------|
| `name` | string | `"A Dimension"` | Required human-readable name (`@MinNumber(2)` on length via annotation min) |
| `version` | int | `1` | Bump to discourage accidental pack upgrades on existing worlds |
| `logicalHeight` | int | `256` | 1–2032; player teleport height budget; part of hotload contract |
| `dimensionHeight` | `IrisRange` | min `-64`, max `320` | World min/max Y. Iris generates internal height `max - min`, then shifts by min on output |
| `fluidHeight` | int | `63` | Required; 0–1024. Fluid column top in **internal** Y (0 = bottom of dimension height). World Y ≈ `fluidHeight + dimensionHeight.min` |
| `environment` | `IrisEnvironment` | `NORMAL` | `NORMAL`, `NETHER`, `THE_END`, `CUSTOM` — selects base datapack dimension template (overworld/nether/end) |
| `fullbright` | boolean | `false` | Forces maximum ambient lighting when true |
| `bedrock` | boolean | `true` | Places bedrock at internal Y 0 when true |
| `caveLavaHeight` | int | `8` | Subterrain fluid layer height (0–318) |

### Environment enum

| Value | Base dimension type mapping |
|-------|-----------------------------|
| `NORMAL` | Overworld-style |
| `NETHER` | Nether-style |
| `THE_END` | End-style |
| `CUSTOM` | Treated as overworld base in `getBaseDimension()` default branch |

### Height contract (hotload / world bind)

`IrisDimensionRuntimeContract` locks: namespaced type key, min height, total height (`max - min`), and `logicalHeight`. Changing these on a running world requires restart, not hotload.

## Regions and Spatial Zoom

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `regions` | string[] | empty | **Required.** Region load keys under `regions/` |
| `regionStyle` | `IrisGeneratorStyle` | `CELLULAR_IRIS_DOUBLE` | Region placement noise |
| `continentalStyle` | `IrisGeneratorStyle` | `CELLULAR_IRIS_DOUBLE` | Land/sea placement |
| `landBiomeStyle` | `IrisGeneratorStyle` | `CELLULAR_IRIS_DOUBLE` | Land biome placement |
| `shoreBiomeStyle` | `IrisGeneratorStyle` | `CELLULAR_IRIS_DOUBLE` | Shore biome placement |
| `seaBiomeStyle` | `IrisGeneratorStyle` | `CELLULAR_IRIS_DOUBLE` | Sea biome placement |
| `caveBiomeStyle` | `IrisGeneratorStyle` | `CELLULAR_IRIS_DOUBLE` | Cave biome placement |
| `landChance` | double | `0.625` | 0–1 land vs sea chance |
| `regionZoom` | double | `1` | Region size multiplier |
| `landZoom` | double | `1` | Land space zoom |
| `seaZoom` | double | `1` | Ocean biome zoom |
| `continentZoom` | double | `1` | Continent zoom |
| `biomeZoom` | double | `1` | Global biome size (higher = bigger) |
| `coordFractureDistance` | double | `20` | Coordinate warping distance (blocks) |
| `coordFractureZoom` | double | `8` | Coordinate warping frequency |
| `dimensionAngleDeg` | double | `0` | Rotate entire dimension input coordinates (degrees) |
| `focus` | string | `""` | Force a single biome load key (testing) |
| `focusRegion` | string | `""` | Force a single region load key (testing) |

## Materials, Ores, Deposits

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `rockPalette` | `IrisMaterialPalette` | stone | Subsurface “stone” fill palette |
| `fluidPalette` | `IrisMaterialPalette` | water | Fluid block palette |
| `rockZoom` | double | `5` | Rock palette noise zoom |
| `ores` | `IrisOreGenerator[]` | empty | Dimension-wide ore generators (surface vs underground via generator flags) |
| `deposits` | `IrisDepositGenerator[]` | empty | Global deposit blobs |
| `depositVariants` | `IrisDepositVariant[]` | empty | Source→replacement ore remaps; applied after biome/region rules |
| `overlayNoise` | `IrisShapedGeneratorStyle[]` | empty | Extra height overlay noise |
| `hideOresForHiddenOre` | boolean | `false` | Replace ore placements with base rock for drop-control plugins |

## Caves, Carving, Mantle, Decoration

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `carvingEnabled` | boolean | `true` | Master carving toggle |
| `carving` | `IrisDimensionCarvingEntry[]` | empty | Absolute-Y cave biome carving overrides |
| `caveProfile` | `IrisCaveProfile` | default object | Profile-driven 3D caves (see `15 - Caves & Carving.md`) |
| `requireObjectSurfaceSupport` | boolean | `true` | Refuse surface objects over carved openings |
| `objectSurfaceSupportBuffer` | int | `2` | Min surface-support buffer (0–16) |
| `useMantle` | boolean | `true` | Objects, entities, features, updates |
| `decorate` | boolean | `true` | Decorators |
| `postProcessing` | boolean | `true` | Post-process pass |
| `postProcessingSlabs` | boolean | `true` | Slab painting |
| `postProcessingWalls` | boolean | `true` | Wall painting |
| `preventLeafDecay` | boolean | `true`/`false` default `false` | Creative-like leaf persistence |
| `treeSettings` | `IrisTreeSettings` | default | Tree growth overrides |
| `disabledComponents` | mantle flag strings | empty | Disable mantle components by flag |

## Upper Dimension (canopy)

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `upperDimension` | string | `"none"` | Dimension load key for inverted ceiling terrain; `"none"` or empty disables |
| `upperDimensionGap` | int | `32` | Min air gap between lower and upper surfaces (0–256) |
| `upperDimensionCarving` | boolean | `false` | Allow carving through upper terrain |
| `upperDimensionObjects` | boolean | `false` | Allow mantle objects in upper zone |
| `upperObjectsForcePlace` | boolean | `false` | Force-place upper objects ignoring normal restrictions |

## Structures, Features, Datapacks

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `structures` | `IrisStructurePlacement[]` | empty | Dimension-level Iris structure placements |
| `importedStructures` | `IrisImportedStructureControl` | default | Vanilla/mod/datapack structure allow/deny and adjustments |
| `importedFeatures` | `IrisImportedFeatureControl` | default off | Optional vanilla feature decoration pass |
| `datapackImports` | string[] | empty | External datapack URLs requested by this pack |

Structure placement and native control details: see `18 - Structures Overview.md`, `22 - Native Structures & Datapacks.md`.

## Loot, Spawns, Drops, Studio Debug

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `loot` | `IrisLootReference` | empty | Dimension loot tables |
| `entitySpawners` | string[] | empty | `IrisSpawner` load keys |
| `blockDrops` | `IrisBlockDrops[]` | empty | Custom block drops |
| `studioMode` | `StudioMode` | `NORMAL` | Studio-only generator overrides |
| `debugChunkCrossSections` | boolean | `false` | Cut chunks for cross-section viewing |
| `debugCrossSectionsMod` | int | `3` | X/Z modulus for cross-section cuts |
| `explodeBiomePalettes` | boolean | `false` | Vertical palette visualization |
| `explodeBiomePaletteSize` | int | `3` | Palette explosion spacing |
| `debugSmartBore` | boolean | `false` | Fill object voids with cobweb |
| `forceConvertTo320Height` | boolean | `false` | Height conversion flag |
| `disableExplorerMaps` | boolean | `false` | Disable cartographer explorer maps |
| `dimensionOptions` | `IrisDimensionTypeOptions` | defaults | Minecraft dimension-type datapack options (ultrawarm, natural, skylight, coordinate scale, …) |

### `dimensionOptions` fields (`IrisDimensionTypeOptions`)

Tri-state fields use `DEFAULT` | `TRUE` | `FALSE` (follow base dimension when `DEFAULT`):

| Field | Default | Role |
|-------|---------|------|
| `ultrawarm` | `DEFAULT` | Nether-like water/lava behavior |
| `natural` | `DEFAULT` | Beds/compasses/portal piglins |
| `piglinSafe` | `DEFAULT` | Piglin zombification |
| `respawnAnchorWorks` | `DEFAULT` | Respawn anchor |
| `bedWorks` | `DEFAULT` | Beds |
| `raids` | `DEFAULT` | Bad Omen raids |
| `skylight` | `DEFAULT` | Has skylight |
| `ceiling` | `DEFAULT` | Logical bedrock ceiling |
| `coordinateScale` | `-1` (unset) | Portal scale |
| `ambientLight` | `-1` (unset) | 0–1 ambient |
| `fixedTime` | `-1` sentinel | Fixed day time when set |
| `cloudHeight` | `-1` sentinel | Cloud Y or null to disable |
| `monsterSpawnBlockLightLimit` | `-1` (unset) | 0–15 |

## Overworld Pack Sample

Path: `adapters/fabric/run/config/irisworldgen/packs/overworld/dimensions/overworld.json` (also present under forge/neoforge run configs).

Selected values from that file:

| Field | Overworld value |
|-------|-----------------|
| `name` | `"Overworld"` |
| `version` | `4000` |
| `environment` | `"NORMAL"` |
| `fluidHeight` | `50` |
| `logicalHeight` | `512` |
| `dimensionHeight` | `{ "min": -256, "max": 512 }` |
| `landChance` | `0.69` |
| `regionZoom` | `16.15` |
| `dimensionAngleDeg` | `69` |
| `regions` | `frozen`, `hot`, `terralost`, `mushroom`, `forests`, `tundra`, `magnetics`, `temperate`, `estranged`, `tropical`, `swamp`, `prismatics` |
| `mode` | omitted → `OVERWORLD` |
| `ores` | bedrock + deepslate band generators |
| `deposits` | granite/andesite/diorite/gravel + ore deposits |
| `importedStructures` | adjustments for stronghold, trial chambers, mineshaft, villages |
| `structures` | e.g. ancient city native placement with `REPLACE_SOURCE` |
| `caveProfile` | enabled 3D cave profile |

## Minimal Dimension JSON

Matches studio starter plus an explicit mode (recommended):

```json
{
  "name": "mypack",
  "version": 1,
  "mode": { "type": "OVERWORLD" },
  "regions": ["starter"],
  "fluidHeight": 63,
  "logicalHeight": 384,
  "dimensionHeight": { "min": -64, "max": 320 },
  "environment": "NORMAL"
}
```

## How To: Make a Dimension

1. Create a pack (`/iris studio create name=mypack`) or copy a template.
2. Edit `dimensions/<key>.json`: set `name`, `regions`, `dimensionHeight`, `fluidHeight`, `mode.type`.
3. Ensure every region key exists under `regions/` (see `12 - Regions.md`).
4. Set land/sea styles and zooms only after basic terrain generates.
5. Add `ores` / `deposits` / `caveProfile` / structures after biomes render correctly.
6. Open studio: `/iris studio open mypack`. Iterate with hotload.
7. For isolation: set `"focusRegion": "starter"` or `"focus": "starter"` while authoring one biome.
8. When ready for a permanent world, create a world from the pack key (`06 - Worlds & Lifecycle.md`). Do not change height/logicalHeight without recreating the world dimension type.

## Common Author Mistakes

| Mistake | Result |
|---------|--------|
| Empty `regions` | Dimension cannot place content |
| Region keys that do not resolve | Missing regions at runtime |
| Changing `dimensionHeight` / `logicalHeight` mid-studio | Hotload rejected; restart studio |
| Expecting SuperFlat/Islands/Enclosure decoration | Those modes currently register only terrain+biome stages |
| Treating `fluidHeight` as world Y | It is internal Y; world Y = fluidHeight + min height |
| Forgetting to reference regions listed in dimension | Orphan region files never spawn |