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:

{
"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):

{
  "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