Iris/docs/27 - Example - Configuring Overworld.md

27 - Example - Configuring Overworld

The shipping overworld pack is what Iris downloads on first boot and what most servers generate from. This is a guided build: you will fork it, add one visible biome, prove the biome in Studio and in a disposable world, and leave the original pack untouched. It exercises the parts of the workflow that actually bite — references, hotload, world snapshots, and rollback — without touching height or registries.

Related: 05 - Concepts & Pack Layout.md, 06 - Worlds & Lifecycle.md, 10 - Studio & VSCode Schemas.md, 11 - Dimensions.md, 12 - Regions.md, 13 - Biomes.md, 14 - Generators & Noise.md, 23 - Loot, Entities, Spawners, Markers.md, 24 - Pack Mods & Snippets.md, 25 - Pack Management.md, 04 - Commands & Permissions.md, 02 - Getting Started.md.

Prerequisites:

• The overworld pack is installed and validates.
• Operator access on Bukkit, or gamemaster access on a mod loader.
• The keys my-overworld, overworld-test, and tutorial/meadow are unused.
• The fork is in source control or has a filesystem backup before you rely on it.

Where everything lives before you start

Platform	Authoritative packs root
Bukkit / Paper / Folia / Purpur	plugins/Iris/packs/overworld/
Fabric / Forge / NeoForge	config/irisworldgen/packs/overworld/

A world created from a pack stores its own copy at <world>/iris/pack/. StudioSVC.installIntoWorld and replaceIntoWorld write that copy; normal world generation reads it and never looks at the global packs/ tree again. Studio worlds are the exception — they run directly off packs/<key>/, which is why Studio is where authoring happens.

On first install Iris downloads the managed Overworld and Underworld beta releases into packs/. /iris download overworld pulls the same Overworld asset (see 02 - Getting Started.md, 25 - Pack Management.md).

The pack's shape:

overworld/
  dimensions/overworld.json      # root dimension, load key: overworld
  regions/*.json                 # frozen, hot, temperate, tropical, ...
  biomes/<folder>/*.json         # temperate/, hot/, carving/, vanilla/, ...
  generators/*.json              # plain, mountain, ocean, flat, ...
  loot/...                       # global-clutter, temperate/food, ...
  entities/standard/...
  spawners/<climate>/...
  objects/...                    # .iob schematics
  structures/, jigsaw-*, ...
  snippet/decorator/, snippet/style/

1. Fork the pack

What you do.

• Bukkit: /iris studio create name=my-overworld template=overworld
• Modded: /iris studio create my-overworld overworld

Wait for the command to report the completed project path — pack creation runs asynchronously and may report that a restart is required before the new pack can be opened.

Then validate and open:

• Bukkit: /iris pack validate pack=my-overworld, then /iris studio open my-overworld seed=1337
• Modded: /iris pack validate my-overworld, then /iris studio open my-overworld 1337

Why. Forking copies the whole tree under a new pack key so upstream Overworld updates cannot clobber your work, and so a mistake is one folder deletion away from being undone. Create your worlds from the fork, not from overworld.

What you should see. A my-overworld folder next to overworld with the same structure, a loadable validation result, and a Studio world that looks exactly like the shipping overworld.

2. Add the biome file

What you do. Save this complete biome as packs/my-overworld/biomes/tutorial/meadow.json:

{
  "name": "Tutorial Meadow",
  "rarity": 1,
  "derivative": "minecraft:plains",
  "vanillaDerivative": "minecraft:plains",
  "layers": [
    {
      "minHeight": 1,
      "maxHeight": 1,
      "palette": [{ "block": "minecraft:grass_block" }]
    },
    {
      "minHeight": 3,
      "maxHeight": 3,
      "palette": [{ "block": "minecraft:dirt" }]
    }
  ],
  "generators": [
    { "generator": "plain", "min": 18, "max": 24 }
  ],
  "decorators": ["snippet/decorator/wildflowers"]
}

Why. Every piece of this is chosen so the result is unmistakable in game:

• generators reuses the fork's existing generators/plain.json (an IRIS_DOUBLE composite behind a BILINEAR_STARCAST_9 interpolator) but at min 18 / max 24 instead of the 4-to-10 band the shipping plains uses. Those numbers are offsets from fluidHeight, which the overworld sets to 50, so this meadow sits roughly 68 to 74 blocks up while ordinary plains sit around 54 to 60. The height difference is what makes it visible from a distance.
• layers are thicknesses, not Y coordinates: one block of grass over three blocks of dirt, with the dimension's rock palette filling everything below.
• decorators uses a snippet reference. Any field whose type is a snippet type accepts the string form snippet/<type>/<name>, and Iris loads snippet/decorator/wildflowers.json in its place at parse time. The fork already contains that file.
• rarity 1 makes it as common as the region's other biomes so you do not have to search for it later.

Do not copy this file into the original overworld folder.

What you should see. With the workspace open, the editor should autocomplete generator values against the fork's real generator keys and flag a typo in derivative immediately. If it does not, run /iris studio update dimension=my-overworld (see 10 - Studio & VSCode Schemas.md).

3. Attach it and focus on it

What you do. Append "tutorial/meadow" to landBiomes in regions/temperate.json, then merge these two fields into the existing object in dimensions/my-overworld.json:

{
  "focusRegion": "temperate",
  "focus": "tutorial/meadow"
}

These are field excerpts. Merge them into the existing files; do not replace either file with the fragment. Validate again after both edits.

Why. A biome file that no region lists never generates — nothing warns you about it, it just never gets picked. regions/temperate.json already carries 28 land biomes, so a new one would be rare enough to be annoying to find; the two focus fields force the entire world to that region and biome so you can confirm the biome itself is correct before worrying about selection frequency.

What you should see. Validation still loadable. If it cannot resolve the biome, compare tutorial/meadow against the actual path and the region entry character for character — the folder prefix is part of the key.

4. Prove the authoring result

What you do. Generate untouched Studio chunks and run /iris what region and /iris what biome.

What you should see. Region Temperate, biome Tutorial Meadow, a grass-over-dirt surface, terrain visibly higher than the surrounding shipping plains, wildflower decoration, and no missing-key errors in console.

If terrain is empty, confirm generators/plain.json still exists in the fork. If flowers are missing, confirm snippet/decorator/wildflowers.json exists and remove the decorator reference until the terrain baseline passes — one variable at a time.

5. Prove natural selection and restart behavior

What you do.

1. Remove focus and focusRegion, close Studio, and reopen on seed 1337.
2. Locate the biome naturally: /iris find biome tutorial/meadow (available on Bukkit and on mod loaders; /iris goto biome <key> is the same command on modded).
3. Create a disposable world: Bukkit /iris create overworld-test type=my-overworld seed=1337, modded /iris create overworld-test my-overworld 1337.
4. Teleport: Bukkit /iris tp overworld-test, modded /iris tp irisworldgen:overworld-test. On Folia, honor the required restart immediately after the create command before teleporting.
5. Generate new chunks, stop the server cleanly, restart, and verify another new area.

Why. Focus mode proves the biome renders; only unfocused generation proves it is actually reachable through region selection. The disposable world proves the pack snapshot works outside Studio, and the restart proves the generated dimension type and custom biomes survive a registry reload.

What you should see. The meadow appearing naturally in temperate regions, <world>/iris/pack/ present in the world folder, and a clean restart with no pack or registry errors.

6. Package or recover

What you do. Package with Bukkit /iris studio package dimension=my-overworld or modded /iris studio package my-overworld.

Why. The validated fork under packs/ is the source of truth. The .iris export and the world snapshot are outputs, and both are reproducible from it.

Failure	Recovery
Fork creation fails or is partial	Move only the newly created incomplete my-overworld folder aside, confirm the source pack validates, then rerun
Studio still shows old content	Generate untouched chunks; close and reopen after a dimension-contract or registry change
Natural selection cannot find the biome	Confirm it is still in regions/temperate.json, that both focus fields are gone, and sample a broader new area
Disposable world differs from Studio	Inspect <world>/iris/pack/; recreate the world from the current validated fork
A production update would change height, registries, or large terrain systems	Do not update in place; create a new world and migrate deliberately

What the shipping dimension actually sets

From dimensions/overworld.json:

Field	Shipping value	Why it matters when you edit
name / version	"Overworld" / 4000	Bump version on your fork so pack generations stay distinguishable
dimensionHeight	min -256, max 512	768 blocks tall. Contract field — do not change it on a fork that already has worlds
logicalHeight	512	Contract field
fluidHeight	50	World Y of sea level, and the baseline every biome generator band is measured from. Change it and every biome's apparent height moves
environment	NORMAL	Contract field
landChance	0.69	Land-heavy world
regionZoom	16.15	Continent-sized climate regions
coordFractureZoom	0.15	Aggressive coordinate warping; this is the source of the swirled borders
dimensionAngleDeg	69	Off-axis rotation that hides grid artifacts
regions	frozen, hot, terralost, mushroom, forests, tundra, magnetics, temperate, estranged, tropical, swamp, prismatics	The twelve climate regions your biome must be attached to one of
loot	mode FALLBACK, tables ["global-clutter"]	Fallback only — objects that declare their own loot keep it
preventLeafDecay	true	Custom trees keep their canopies
useMantle / carvingEnabled / decorate	true	All content passes on
caveProfile	enabled	Dimension-wide 3D caves, overridden per region
carving	one deep-dark band at world Y -250 to -175	Depth-banded cave biome
mode	omitted	Runs OVERWORLD

Also present: region/continental/biome noise styles, 11 ore generators, 20 deposits, one deposit variant that remaps ores to their deepslate forms below Y 0, imported-structure adjustments for stronghold, trial chambers, mineshaft and village, and one ancient-city structure placement with nativeSuppression: REPLACE_SOURCE. Field-by-field meanings are in 11 - Dimensions.md.

Do not invent region or biome keys. List the directories under regions/ and biomes/ and use what is actually there.

Reading the region and biome graph

regions/temperate.json is a representative region:

• landBiomes — 28 keys including temperate/plains, temperate/oak-forest, mountain/plains, vanilla/cherry_grove
• shoreBiomes — temperate/shore/beach, ocean/shore/beach, vanilla/stony_shore, others
• seaBiomes — ocean/deep, temperate/sea/ocean, temperate/sea/river, others
• caveBiomes — carving/rocky-cavebiome, carving/drip, carving/deep, others
• loot — mode FALLBACK, multiplier 0.5, tables temperate/clutter and temperate/food
• Per-category zooms (landBiomeZoom 3.5, seaBiomeZoom 6, shoreBiomeZoom 0.15, caveBiomeZoom 3.3) and its own enabled caveProfile

biomes/temperate/plains.json is a representative biome:

• derivative and vanillaDerivative are both minecraft:plains
• generators is [{ "generator": "plain", "min": 4, "max": 10 }] — 4 to 10 blocks above sea level
• layers is one block of grass over two blocks of dirt; the dimension's rock palette fills below
• objects places clutter/... keys in PAINT mode at fractions of a percent per column
• decorators place flowers with a TRIOCTAVE_SIMPLEX variance and a fractured STATIC style

generators/plain.json is the height source both that biome and your meadow use: a single IRIS_DOUBLE composite layer behind a BILINEAR_STARCAST_9 interpolator at horizontal scale 12.

Editing safely

Author in Studio, on a fork

1. Confirm overworld exists under packs/overworld/.
2. Fork it: /iris studio create name=my-overworld template=overworld.
3. Open Studio: /iris studio open my-overworld seed=1337.
4. Edit under packs/my-overworld/ with the generated VSCode workspace and schemas (10 - Studio & VSCode Schemas.md).
5. Save; hotload picks the change up. Generate new chunks to see it — existing blocks are never rewritten.
6. Isolate with "focus": "temperate/plains" or "focusRegion": "temperate" while testing, and remove both afterwards.
7. Make one small change at a time — nudge biomes/temperate/plains.json generator min/max by a few blocks, validate, and compare the same seed in fresh chunks.
8. Close Studio, create a disposable world from the fork, and restart-test it before touching anything real.

Do not treat the world copy as the source

Editing <world>/iris/pack/ changes only that world and is overwritten by the next pack install or update. Author under packs/.

Practical recipes

Change sea level

Set fluidHeight in dimensions/my-overworld.json — shipping value 50. It is world Y, and every biome generator band is measured from it, so lowering it lowers the sea while leaving relative terrain heights intact and raising it drowns low biomes. Only newly generated chunks change, so expect a visible shoreline seam on an existing world.

Add a biome to a region

1. Create biomes/temperate/my-biome.json with at least name, derivative, layers, and generators (26 - Example - Minimal Dimension.md, 13 - Biomes.md).
2. Append "temperate/my-biome" to the appropriate list in regions/temperate.json — landBiomes, seaBiomes, shoreBiomes, or caveBiomes.
3. Hotload, then sample with /iris what biome and /iris find biome.

Region lists must match real biome load keys. A key that does not resolve is a blocking validation error; a biome file that no region lists is silently dead.

Change plains height

Edit generators min/max on biomes/temperate/plains.json to affect only that biome, or edit generators/plain.json to affect every biome that references plain — which is a lot of them. Prefer the biome-level change unless you mean the global one.

Loot

• Dimension fallback: dimensions/overworld.json → loot.tables
• Region: regions/temperate.json → loot
• Tables live under loot/ (global-clutter, global-treasure, temperate/food, …)

Mode FALLBACK only supplies tables when the object itself declared none; ADD stacks onto the parent scopes; CLEAR and REPLACE drop them.

Decorators via snippets

Reuse snippet/decorator/* and snippet/style/* by string reference as in 24 - Pack Mods & Snippets.md. Existing examples: biomes/vanilla/old_growth_birch_forest.json and the dimension's ore chanceStyle fields.

Entities and spawners

The pack ships entities/standard/** and spawners/**. Ambient Iris spawning requires listing spawner keys on entitySpawners at dimension, region or biome scope. Marker-based spawning needs markers plus a markers array on an object placement. See 23 - Loot, Entities, Spawners, Markers.md.

Pushing changes into an existing world

World creation installs the pack copy once. Changing packs/ does not update existing worlds.

/iris dev update-world (Bukkit)

/iris dev update-world world=<world> pack=my-overworld confirm=true

Optional fresh-download=true re-downloads the pack first. Behavior (CommandDeveloper.updateWorld → StudioSVC.replaceIntoWorld):

1. Without confirm=true it prints the warning and does nothing.
2. Optionally re-downloads the pack.
3. Replaces <world>/iris/pack/ with a fresh copy of the source pack.
4. It is described as UNSAFE in the command itself. Already-generated chunks keep their old terrain; for most features only newly generated chunks use the new content. Back the world up first.

Choosing between update-world and a new world

Goal	Approach
Live design iteration	Studio open on packs/
Ship pack changes into an existing survival world	Back up, then update-world … confirm=true
Guaranteed consistent terrain	New world from the updated pack
Experimental or partial changes	Fork the pack with studio create

Never use update-world for a change to dimensionHeight, logicalHeight, environment, or the dimension file name. Those are the world contract; the world will not load against a different one.

Validation and packaging

Task	Command
Validate	Bukkit /iris pack validate pack=my-overworld; modded /iris pack validate my-overworld
Preview unused-resource cleanup	Bukkit /iris pack cleanup my-overworld mode=preview, then mode=apply; modded uses the same preview/apply literals
Package for distribution	Bukkit /iris studio package dimension=my-overworld; modded /iris studio package my-overworld
Version stamp	The dimension version field; the shipping pack uses large integers such as 4000

Checklist before a production update

1. Verify in Studio, not by reading JSON.
2. Run pack validate and fix every broken key.
3. Back up the target world folder.
4. Run update-world with confirm=true, plus fresh-download=true if the source should be re-pulled.
5. Explore new chunks; do not expect existing terrain to change.
6. Record operator-facing changes in the workspace changelog when releasing.

Cross-links

• Minimal greenfield pack: 26 - Example - Minimal Dimension.md
• Dimension field reference: 11 - Dimensions.md
• Commands and permissions: 04 - Commands & Permissions.md
• Download, validate, package: 25 - Pack Management.md