Skip to main content

​
Overview

This guide walks you through creating your first Iris world, from installation to exploring custom terrain. By the end, you’ll have a fully functional Iris-generated world running on your server.
Make sure you’ve completed the Installation steps before proceeding.

​
Create Your First World

1

Choose a Dimension Pack

Iris worlds are created from dimension packs. The “overworld” pack provides vanilla-like generation with enhancements.View available dimensions:
/iris download overworld
Popular dimension packs:
  • overworld - Enhanced vanilla-like generation
  • flat - Flat world generation
  • Custom packs from IrisDimensions
2

Create the World

Use the /iris create command to generate a new world:
/iris create <world-name> dimension=<dimension> seed=<seed>
Example:
/iris create myworld dimension=overworld seed=12345
From CommandIris.java:73-126:
ParameterDescriptionDefaultRequired
world-nameName of the world to create-Yes
dimensionDimension type (e.g., overworld)defaultNo
seedWorld generation seed1337No
main-worldSet as server’s main worldfalseNo
Reserved Names: Cannot use “iris” or “benchmark” as world names.
Create as the main world:
/iris create myworld dimension=overworld main-world=true
This automatically sets your world as the server’s default world on restart.
3

Wait for World Creation

Iris prepares your world:
[Iris] Creating world: myworld
[Iris] Dimension: overworld
[Iris] Installing dimension pack...
[Iris] Preparing spawn area...
[Iris] Successfully created your world!
Initial spawn preparation may take 1-5 minutes depending on your server hardware. This is normal for first-time world creation.
4

Teleport to Your World

Visit your newly created world:
/iris teleport myworld
Or teleport another player:
/iris teleport myworld player=PlayerName
From CommandIris.java:145-168, teleport is executed synchronously on the main thread for safety.

​
Understanding World Generation

​
The IrisToolbelt API

Under the hood, Iris uses the IrisToolbelt API for world creation: 
// From README.md:65-74
IrisAccess access = IrisToolbelt.createWorld()
    .name("myWorld")              // World name
    .dimension("overworld")       // Dimension pack
    .seed(69133742)               // World seed
    .pregen(PregenTask            // Optional pregeneration
        .builder()
        .center(new Position2(0,0))  // Center point (regions)
        .radius(4)                    // 4 region radius
        .build())
    .create();

​
World Structure

When created, Iris worlds have this structure: 
myworld/
├── iris/
│   ├── pack/                 # Dimension pack files
│   │   ├── dimensions/       # Dimension definitions
│   │   ├── biomes/          # Biome configurations  
│   │   ├── objects/         # Structures & objects
│   │   └── regions/         # Region definitions
│   └── engine.json          # Engine configuration
├── region/                   # World chunk data
├── playerdata/              # Player data
└── level.dat                # World metadata
Pregenerate chunks for better performance:
1

Start Pregeneration

Use the /iris pregen command:
/iris pregen start radius=10
This pregenerates chunks in a radius around spawn.
ParameterDescriptionUnit
radiusRadius from centerRegions (1 region = 32×32 chunks)
centerCenter coordinatesRegion coordinates
methodGeneration methodcached, hybrid, or turbo
Example:
/iris pregen start radius=5 method=cached
2

Monitor Progress

Watch pregeneration progress:
/iris pregen status
Output shows:
  • Chunks generated
  • Chunks remaining
  • Generation speed (chunks/sec)
  • Estimated time remaining
3

Pause or Stop

Control pregeneration:
# Pause pregeneration
/iris pregen pause

# Resume pregeneration
/iris pregen resume

# Stop completely
/iris pregen stop
From IrisSettings.java:149-155, default pregeneration settings:
  • Uses cache by default: true
  • Max concurrency: 256 chunks
  • Virtual threads: false (Java 21+ feature)

​
Exploring Your World

​
Check World Information

/iris worlds

# Output:
# Iris Worlds:
# - myworld
# Bukkit Worlds: 
# - world
# - world_nether

​
Using the What Command

Identify biomes and features while exploring: 
/iris what
Shows:
  • Current biome
  • Region information
  • Cave/structure data
  • Terrain height

​
Studio Mode (Advanced)

For dimension pack development, use Studio mode:
1

Open Studio World

Quick studio for overworld:
/iris so
Or specify a dimension:
/iris studio overworld
2

Edit & Hot-Reload

Studio mode features:
  • Real-time dimension editing
  • Instant chunk regeneration
  • VS Code integration (if enabled)
  • Weather/time disabled for testing
Studio settings from IrisSettings.java:259-264:
  • Auto-open VS Code: openVSCode: true
  • Disable time/weather: disableTimeAndWeather: true
  • Auto-start default studio: autoStartDefaultStudio: false
3

Test Changes

After editing dimension files:
/iris studio reload
New chunks generate with your changes!

​
Managing Worlds

​
Loading Existing Worlds

Import an existing Iris world: 
/iris loadWorld <world-name>
This registers the world in bukkit.yml and loads it.

​
Unloading Worlds

/iris unloadWorld <world-name>

​
Removing Worlds

This permanently deletes the world folder!
# Remove world and delete files
/iris remove <world-name>

# Remove but keep files
/iris remove <world-name> delete=false
From CommandIris.java:244-305, this command:
  1. Evacuates all players to another world
  2. Unloads the world
  3. Removes from bukkit.yml
  4. Optionally deletes world folder

​
Common Issues

Error: That folder already exists!Solution: Choose a different world name or delete the existing folder:
# WARNING: This deletes all world data!
rm -rf /path/to/server/worldname
Symptoms: Stuck at “Loading terrain…”Solutions:
  1. Check server console for errors
  2. Verify dimension pack installed: ls plugins/Iris/packs/
  3. Increase server timeout in spigot.yml: 
    settings:
  timeout-time: 120
  4. Allocate more RAM to server
Error: The specified player does not exist or world not foundSolutions:
  1. Verify world loaded: /iris worlds
  2. Check exact world name (case-sensitive)
  3. Ensure you have permission: iris.command.teleport

​
Next Steps

Now that you have a working Iris world:

Optimize Performance

Tune settings.json for your server

Download More Packs

Explore dimension packs at IrisDimensions

Create Custom Dimensions

Learn dimension pack development

Use the API

Integrate Iris into your plugins
Join the Iris Discord to share your worlds and get help from the community!

Build docs developers (and LLMs) love

Get started for freeTalk to us