Skip to main content

​
Prerequisites

Before installing Iris, ensure your server meets these requirements:
Java 21 Required: Iris requires Java 21 or newer to run. Using an older version of Java will prevent the plugin from loading.
1

Verify Java Version

Iris requires Java 21 or higher. Check your Java version:
java -version
You should see output showing Java 21 or higher:
openjdk version "21.0.1" 2023-10-17
OpenJDK Runtime Environment (build 21.0.1+12-29)
OpenJDK 64-Bit Server VM (build 21.0.1+12-29, mixed mode, sharing)
If you need to install Java 21:Download Java 21:Set JAVA_HOME (if needed):
# Press Win + R, type: SystemPropertiesAdvanced
# Click "Environment Variables"
# Under System Variables, click "New"
# Variable Name: JAVA_HOME
# Variable Value: C:\Program Files\Java\jdk-21.0.1
2

Verify Server Platform

Iris supports these server platforms:
  • Paper (recommended for best performance)
  • Spigot
  • Bukkit (derivatives)
Supported Minecraft Versions: 1.20.1 - 1.21.11
Paper is recommended for optimal performance with Iris. Download from PaperMC.io

​
Installation Methods

1

Purchase & Download

Support the developers by purchasing Iris from SpigotMC:
  1. Visit the Iris resource page on SpigotMC
  2. Purchase and download the latest version
  3. You’ll receive Iris-[version].jar
2

Install the Plugin

Copy the JAR file to your server’s plugins folder:
# Navigate to your server directory
cd /path/to/your/server

# Copy Iris to plugins folder
cp ~/Downloads/Iris-*.jar plugins/
3

Start Your Server

Start or restart your server:
java -jar paper.jar
Look for Iris startup messages in the console:
[Iris] Iris v3.9.1-1.20.1-1.21.11 by Volmit Software
[Iris] Server type & version: Paper v1.21.11
[Iris] Custom Biomes: ...

​
Method 2: Build from Source

Building from source requires Java 21 and Git:
1

Clone the Repository

git clone https://github.com/VolmitSoftware/Iris.git
cd Iris
2

Build with Gradle

# Unix/macOS
./gradlew iris

# Windows
gradlew.bat iris
The build process uses Java 21 toolchain as configured in build.gradle.kts:191-195
3

Locate the JAR

After building, find the JAR at:
build/Iris-[version].jar
Copy it to your server’s plugins/ folder.

​
First Launch

After installing Iris, the first server start will:
1

Initialize Plugin

Iris creates its data folder structure:
plugins/Iris/
├── settings.json       # Configuration file
├── packs/              # Dimension packs folder
├── cache/              # Generation cache
└── compat.json         # Compatibility settings
2

Auto-Configuration

Iris automatically configures server settings if enabled:
# Iris adjusts timeout settings in spigot.yml
settings:
  timeout-time: 120  # Increased for world generation
Auto-configuration can be disabled in settings.json under autoConfiguration
3

Download Default Dimension Pack

On first world creation, Iris downloads the “overworld” dimension pack:
[Iris] Downloading pack: overworld
[Iris] Installing into packs/overworld/

​
Verify Installation

Confirm Iris is running correctly: 
# Run this command as operator
/iris version

# Expected output:
# Iris v3.9.1-1.20.1-1.21.11 by Volmit Software
Use /iris help to see all available commands

​
Troubleshooting

Error: You must run gradle on Java 21 or newerSolution:
  1. Install Java 21 or higher
  2. Set JAVA_HOME environment variable
  3. Restart your server with Java 21
Verify with: java -version
Symptoms: Commands like /iris return “Unknown command”Solutions:
  1. Ensure Iris loaded successfully (check startup logs)
  2. Verify you have operator permissions
  3. Check for plugin conflicts in plugins/ folder
  4. Look for errors in logs/latest.log
Symptoms: Chunks take a long time to generateSolutions:
  1. Allocate more RAM to your server (recommended: 4GB minimum)
  2. Adjust thread settings in settings.json: 
    "concurrency": {
  "parallelism": -1,
  "worldGenParallelism": -1
}
  3. Enable pregeneration for your world (see quickstart)
See Configuration for performance tuning.
Error: Custom Biomes: 0 in startup logsCauses:
  • NMS (Native Minecraft Server) bindings failed
  • Server version not supported
  • Dimension pack missing or corrupted
Solution:
  1. Verify Minecraft version is 1.20.1-1.21.11
  2. Re-download dimension pack: /iris download overworld
  3. Check settings.json - ensure disableNMS: false

​
Next Steps

Now that Iris is installed:

Create Your First World

Follow the quickstart guide to create an Iris world

Configure Settings

Optimize performance and customize behavior

Download Dimension Packs

Browse available packs at IrisDimensions

Studio Mode

Learn to create custom dimensions with Studio

Build docs developers (and LLMs) love

Get started for freeTalk to us