Iris/docs/26 - Example - Minimal Dimension.md

26 - Example - Minimal Dimension

This walkthrough builds a loadable pack with one dimension, one region, one biome, and one generator using real field names from IrisDimension, IrisRegion, IrisBiome, and IrisGenerator. The skeleton matches StudioSVC.createStarterProject and is expanded with required mode and fluid height for explicit authoring.

Related: 05 - Concepts & Pack Layout.md, 02 - Getting Started.md, 10 - Studio & VSCode Schemas.md, 11 - Dimensions.md, 12 - Regions.md, 13 - Biomes.md, 14 - Generators & Noise.md, 25 - Pack Management.md, 04 - Commands & Permissions.md.

Tutorial result

You will create four files under packs/minimal/, validate them, open them in Studio on seed 1337, and create a disposable production world. Do not add objects, caves, structures, custom biomes, or datapacks until this exact baseline generates and reloads.

Prerequisites:

• Iris is running and its default data folders exist.
• You have operator access on Bukkit or gamemaster access on a mod loader.
• No pack or world already uses the keys minimal or minimal-test.
• You can inspect the server console while validation, Studio open, world create, and restart run.

1. Create the pack root

Create this tree relative to the platform packs root:

minimal/
  dimensions/minimal.json
  regions/starter.json
  biomes/starter.json
  generators/flat.json

The pack folder name is the pack key. The dimension file name without .json is the dimension load key (minimal).

Creation methods

Platform / method	Command or action
Bukkit Studio starter	/iris studio create name=minimal
Modded default-template copy	/iris studio create minimal — copies the example template
Bukkit template copy	/iris studio create name=minimal template=overworld
Modded template copy	/iris studio create minimal overworld
Manual	Create the four folders and JSON files under the platform packs root

On Bukkit, Studio create without a template writes a starter project with the same four resource types. Modded Studio create defaults to the installed or downloadable example template. Create the tree manually when you need the exact four-file baseline on every platform; use the create commands when extra template content is acceptable.

Platform packs roots (same layout):

• Bukkit-family: plugins/Iris/packs/
• Fabric / Forge / NeoForge: config/irisworldgen/packs/

2. Write the four resources

dimensions/minimal.json

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

Required / load-bearing fields:

Field	Why
name	Human-readable name (@Required, min length 2)
regions	At least one region load key
mode	IrisDimensionMode (type: OVERWORLD, SUPERFLAT, ENCLOSURE, ISLANDS)
fluidHeight	Sea level relative to dimension min (default 63 if omitted)
dimensionHeight	World Y bounds; default -64..320 if omitted
version	Pack version stamp; change to discourage accidental upgrades

Optional but useful for testing: "focus": "starter" forces a single biome; "focusRegion": "starter" forces one region.

regions/starter.json

{
  "name": "Starter",
  "landBiomes": ["starter"],
  "seaBiomes": ["starter"],
  "shoreBiomes": ["starter"]
}

Field	Why
name	Required region name
landBiomes	Required root land biome keys
seaBiomes / shoreBiomes	Optional for land-only packs; starter includes them for full land/sea/shore coverage
caveBiomes	Optional list for cave biomes

Do not list child biomes here — only root parents.

biomes/starter.json

{
  "name": "Starter Plains",
  "derivative": "minecraft:plains",
  "vanillaDerivative": "minecraft:plains",
  "layers": [
    {
      "palette": [{ "block": "minecraft:grass_block" }]
    }
  ],
  "generators": [
    {
      "generator": "flat",
      "min": 96,
      "max": 96
    }
  ]
}

Field	Why
name	Required display name
derivative	Required vanilla biome key for coloring / vanilla structure eligibility
vanillaDerivative	Structure selection derivative; falls back to derivative when null
layers	Surface material stack; remaining depth fills with stone
generators	Links to generators/<key>.json with height relative to fluid height

min/max of 96 with fluid height 63 produce high flat land. For near-sea plains use smaller values (overworld plains use roughly min 4 / max 10 on generator plain).

generators/flat.json

{
  "interpolator": { "function": "NONE", "horizontalScale": 1 },
  "seed": 310,
  "composite": [
    {
      "seed": 310,
      "style": { "style": "FLAT" }
    }
  ]
}

Field	Why
seed	Required generator seed
interpolator	Cross-biome height blend; NONE for hard flat
composite	Noise layers; FLAT style yields constant mid-value height

This matches shipping overworld generators/flat.json and the studio starter.

Studio create vs this skeleton

StudioSVC.createStarterProject writes the same four files with pack name substituted for the dimension file/name. It omits explicit mode and fluidHeight (code defaults: mode OVERWORLD, fluid height 63). The JSON above adds those fields so authors see the required contract.

3. Validate and open Studio

1. Ensure the pack sits under minimal/ in the platform packs root with dimensions/minimal.json.
2. Validate with Bukkit /iris pack validate pack=minimal or modded /iris pack validate minimal. Do not open the pack while validation reports a blocking error.
3. Open Studio with Bukkit /iris studio open minimal seed=1337 or modded /iris studio open minimal 1337.
4. Generate fresh chunks and run /iris what region and /iris what biome. The expected result is the starter region and biome over a uniform grass surface, with no missing-resource or parse errors in the console.
5. Close Studio, reopen it with the same seed, and generate another new area. The terrain height and surface must reproduce.

World create copies the pack into the world folder at iris/pack/ (see 06 - Worlds & Lifecycle.md). Studio worlds hotload the live pack under packs/ — prefer studio for authoring.

4. Create and restart-test a disposable world

1. Create the world with Bukkit /iris create minimal-test type=minimal seed=1337 or modded /iris create minimal-test minimal 1337. On Folia, creation stages the world and requires the instructed server restart before it can be entered.
2. Teleport with Bukkit /iris tp minimal-test or modded /iris tp irisworldgen:minimal-test.
3. Generate ordinary new chunks and confirm the same flat grass result seen in Studio.
4. Stop the server cleanly, start it again, teleport back, and generate another new area.
5. Confirm <world>/iris/pack/ contains the four-file snapshot. Production generation reads this copy, so later authoring changes under packs/minimal/ do not change the existing world automatically.

The tutorial passes only when validation, Studio reopen, production create, teleport, and server restart all succeed. Keep this four-file version as a rollback checkpoint before extending the pack.

5. Extend without breaking the minimal set

Add	Where
Second biome	New biomes/*.json, append key to regions/starter.json landBiomes
Sea variety	Distinct biome keys on seaBiomes / shoreBiomes
Loot	loot/*.json + dimension/region/biome loot reference (23 - Loot, Entities, Spawners, Markers.md)
Decorators	Biome decorators array (inline or snippet/decorator/...)
Objects	Biome/region objects placements + objects/*.iob (19 - Objects.md, 20 - Object Placement.md)
Entity spawn	entities/, spawners/, then entitySpawners on dim/region/biome

Troubleshooting and recovery

Symptom	Check / recovery
Pack is not listed	Confirm the platform packs root, minimal/ folder, and dimensions/minimal.json
Validation reports a missing region	dimensions/minimal.json must reference starter, and regions/starter.json must exist
Validation reports a missing biome	Every region list entry must match a file under biomes/ without .json
Terrain is empty or at the wrong height	Confirm the biome generator key is flat, the generator parses, and biome min / max remain 96
Studio shows old terrain	Generate untouched chunks; close and reopen Studio after contract changes
Production world ignores edits	It uses <world>/iris/pack/; create a new world or follow the backed-up update procedure in 25 - Pack Management.md
Baseline no longer works	Restore the four exact files in this guide and validate before reintroducing extensions

Validation invariants:

• Dimension load key must match a file under dimensions/.
• Every region key in regions must load.
• Every biome key listed on a region must load.
• Every generators[].generator key must load or the engine falls back to an empty default generator.
• derivative must be a known biome registry key such as minecraft:plains.

Cross-links for next steps

• Full dimension options: 11 - Dimensions.md
• Region zooms, deposits, caves: 12 - Regions.md
• Layers, decorators, structures: 13 - Biomes.md
• Noise composite detail: 14 - Generators & Noise.md
• Editing the full overworld pack: 27 - Example - Configuring Overworld.md