Skip to main content

​
Configuration File

Iris stores all configuration in plugins/Iris/settings.json. This file is automatically created on first launch with default values.
Configuration changes are hot-reloaded automatically. Iris checks for file modifications every 60 seconds and applies changes without requiring a restart.

​
Accessing Configuration

# Edit settings via command
/iris settings

# Reload configuration manually
/iris reload

​
Configuration Structure

The settings.json file is organized into sections based on functionality: 
{
  "general": { ... },
  "world": { ... },
  "gui": { ... },
  "autoConfiguration": { ... },
  "generator": { ... },
  "concurrency": { ... },
  "studio": { ... },
  "performance": { ... },
  "updater": { ... },
  "pregen": { ... },
  "sentry": { ... }
}

​
General Settings

From IrisSettings.java:209-231, general plugin behavior: 
"general": {
  "commandSounds": true,
  "debug": false,
  "dumpMantleOnError": false,
  "disableNMS": false,
  "pluginMetrics": true,
  "splashLogoStartup": true,
  "useConsoleCustomColors": true,
  "useCustomColorsIngame": true,
  "adjustVanillaHeight": false,
  "forceMainWorld": "",
  "spinh": -20,
  "spins": 7,
  "spinb": 8
}
Type: boolean
Default: truePlay sounds when executing Iris commands.
Type: boolean
Default: falseEnable debug logging. Logs detailed information to console and plugins/Iris/debug/.
Debug mode significantly increases log output and file I/O. Only enable when troubleshooting.
Toggle via command:
/iris debug on
/iris debug off
Type: boolean
Default: falseDisable Native Minecraft Server (NMS) bindings.
NMS enables custom biomes. Only disable if experiencing compatibility issues.
Type: boolean
Default: trueEnable anonymous usage statistics via bStats. Helps developers understand plugin usage.
Type: boolean
Default: trueUse colored output in server console (requires Adventure API support).

​
World Settings

From IrisSettings.java:124-135, world behavior configuration: 
"world": {
  "asyncTeleport": {
    "enabled": false,
    "loadViewDistance": 2,
    "urgent": false
  },
  "postLoadBlockUpdates": true,
  "forcePersistEntities": true,
  "anbientEntitySpawningSystem": true,
  "asyncTickIntervalMS": 700,
  "targetSpawnEntitiesPerChunk": 0.95,
  "markerEntitySpawningSystem": true,
  "effectSystem": true,
  "worldEditWandCUI": true,
  "globalPregenCache": false
}
Type: objectConfigure asynchronous teleportation:
  • enabled: Enable async teleport (default: false)
  • loadViewDistance: Chunks to load before teleport (default: 2)
  • urgent: High-priority chunk loading (default: false)
From IrisSettings.java:117-121, async teleport loads chunks before moving the player for smoother transitions.
Type: boolean
Default: trueUse marker entities for custom spawning systems in dimension packs.
Type: boolean
Default: falseShare pregeneration cache between worlds. Useful for multiple worlds with the same dimension.
Only enable if you understand the implications. Different seeds with same dimension may cause issues.

​
Concurrency Settings

From IrisSettings.java:138-146, thread pool configuration: 
"concurrency": {
  "parallelism": -1,
  "ioParallelism": -2,
  "worldGenParallelism": -1
}
Negative values are interpreted as multiples of CPU cores:
  • -1 = Number of CPU cores
  • -2 = Half the number of CPU cores
  • -4 = Quarter of CPU cores
  • Positive values = Exact thread count
Type: integer
Default: -1General parallelism for non-world-gen tasks.From IrisSettings.java:51-56:
public static int getThreadCount(int c) {
    return Math.max(switch (c) {
        case -1, -2, -4 -> Runtime.getRuntime().availableProcessors() / -c;
        default -> Math.max(c, 2);
    }, 1);
}
Recommendations:
  • High-end servers (16+ cores): -1 (use all cores)
  • Medium servers (8-16 cores): -1 or -2
  • Low-end servers (4-8 cores): -2 or -4
Type: integer
Default: -2Thread pool for I/O operations (file reading/writing).
I/O operations don’t need as many threads. -2 (half cores) is optimal for most servers.
Type: integer
Default: -1Dedicated threads for world generation.This is the most important performance setting. More threads = faster generation but higher CPU usage.Example configurations:
// Maximum performance (use all cores)
"worldGenParallelism": -1

// Balanced (half cores, leave room for other tasks)
"worldGenParallelism": -2

// Conservative (4 threads exactly)
"worldGenParallelism": 4

​
Performance Settings

From IrisSettings.java:158-175, caching and optimization: 
"performance": {
  "engineSVC": {
    "useVirtualThreads": true,
    "forceMulticoreWrite": false,
    "priority": 5
  },
  "trimMantleInStudio": false,
  "mantleKeepAlive": 30,
  "noiseCacheSize": 1024,
  "resourceLoaderCacheSize": 1024,
  "objectLoaderCacheSize": 4096,
  "scriptLoaderCacheSize": 512,
  "tectonicPlateSize": -1,
  "mantleCleanupDelay": 200
}
Type: boolean
Default: trueUse Java 21 virtual threads for engine operations.
Virtual threads (Project Loom) reduce memory overhead and improve scalability. Requires Java 21+.
Type: integer
Default: 1024Cache size for noise generation. Higher values = more memory, fewer recalculations.Recommendations:
  • 8GB+ RAM: 2048 or higher
  • 4-8GB RAM: 1024 (default)
  • Less than 4GB RAM: 512
Type: integer
Default: 4096Cache size for loaded objects (structures, trees, etc.).This is the largest cache because objects are frequently reused. Increase if using many custom structures.
Type: integer
Default: -1Tectonic plate simulation size. -1 = auto-calculate based on available memory.From IrisSettings.java:169-174:
public int getTectonicPlateSize() {
    if (tectonicPlateSize > 0)
        return tectonicPlateSize;
    
    return (int) (getHardware.getProcessMemory() / 512L);
}

​
Generator Settings

From IrisSettings.java:248-256, world generation behavior: 
"generator": {
  "defaultWorldType": "overworld",
  "maxBiomeChildDepth": 4,
  "preventLeafDecay": true,
  "useMulticore": false,
  "useMulticoreMantle": false,
  "offsetNoiseTypes": false,
  "earlyCustomBlocks": false
}
Type: string
Default: "overworld"Default dimension pack when creating worlds without specifying a dimension.From Iris.java:641:
if (id == null || id.isEmpty()) 
    id = IrisSettings.get().getGenerator().getDefaultWorldType();
Type: integer
Default: 4Maximum depth for nested child biomes. Higher values allow more complex biome variations but increase generation time.
Type: boolean
Default: truePrevent leaves from decaying in generated structures. Recommended for custom trees.

​
Pregeneration Settings

From IrisSettings.java:149-155, pregen configuration: 
"pregen": {
  "useCacheByDefault": true,
  "useHighPriority": false,
  "useVirtualThreads": false,
  "useTicketQueue": true,
  "maxConcurrency": 256
}
Type: boolean
Default: trueCache generated chunks to disk during pregeneration. Significantly faster for large areas.
Type: integer
Default: 256Maximum concurrent chunk generation during pregeneration.
Higher values = faster pregeneration but more memory usage. Don’t exceed your server’s capability.
Recommendations:
  • 16GB+ RAM: 256-512
  • 8GB RAM: 128-256
  • 4GB RAM: 64-128
Type: boolean
Default: falseUse virtual threads for pregeneration (Java 21+ feature).
Currently disabled by default. May improve performance on Java 21+ servers.

​
Studio Settings

From IrisSettings.java:259-264, Studio mode configuration: 
"studio": {
  "studio": true,
  "openVSCode": true,
  "disableTimeAndWeather": true,
  "autoStartDefaultStudio": false
}
Type: boolean
Default: trueEnable Studio mode functionality.
Type: boolean
Default: trueAutomatically open VS Code when starting a studio world (if VS Code is installed).
Type: boolean
Default: trueDisable time progression and weather in studio worlds for easier testing.
Type: boolean
Default: falseAutomatically start a studio world on server startup.
Only enable for dedicated development servers. From Iris.java:515-533, this creates a studio world with the default dimension.

​
Auto-Configuration

From IrisSettings.java:110-114, server auto-configuration: 
"autoConfiguration": {
  "configureSpigotTimeoutTime": true,
  "configurePaperWatchdogDelay": true,
  "autoRestartOnCustomBiomeInstall": true
}
Auto-configuration modifies your server’s configuration files to optimize for Iris. From ServerConfigurator.java, this runs on startup.

​
Performance Tuning Guide

​
High-Performance Configuration

For dedicated servers with 16GB+ RAM: 
{
  "concurrency": {
    "parallelism": -1,
    "ioParallelism": -2,
    "worldGenParallelism": -1
  },
  "performance": {
    "noiseCacheSize": 2048,
    "resourceLoaderCacheSize": 2048,
    "objectLoaderCacheSize": 8192
  },
  "pregen": {
    "maxConcurrency": 512,
    "useVirtualThreads": true
  }
}

​
Balanced Configuration

For shared servers with 8GB RAM: 
{
  "concurrency": {
    "parallelism": -2,
    "ioParallelism": -4,
    "worldGenParallelism": -2
  },
  "performance": {
    "noiseCacheSize": 1024,
    "resourceLoaderCacheSize": 1024,
    "objectLoaderCacheSize": 4096
  },
  "pregen": {
    "maxConcurrency": 128
  }
}

​
Low-Resource Configuration

For budget servers with 4GB RAM: 
{
  "concurrency": {
    "parallelism": -4,
    "ioParallelism": -4,
    "worldGenParallelism": 4
  },
  "performance": {
    "noiseCacheSize": 512,
    "resourceLoaderCacheSize": 512,
    "objectLoaderCacheSize": 2048
  },
  "pregen": {
    "maxConcurrency": 64
  }
}

​
Troubleshooting

Symptoms: Changes to settings.json don’t take effectSolutions:
  1. Verify JSON syntax (use a JSON validator)
  2. Manually reload: /iris reload
  3. Check file permissions (must be writable)
  4. Look for errors in logs/latest.log
Symptoms: Server runs out of memory during generationSolutions:
  1. Reduce cache sizes in performance section
  2. Lower pregen.maxConcurrency
  3. Decrease worldGenParallelism
  4. Allocate more RAM: java -Xmx8G -jar paper.jar
Symptoms: Chunks generate slowlySolutions:
  1. Increase worldGenParallelism to -1
  2. Raise cache sizes if you have spare RAM
  3. Enable performance.engineSVC.useVirtualThreads
  4. Use SSD storage for faster I/O

​
Advanced Configuration

​
Sentry Error Reporting

From IrisSettings.java:234-238: 
"sentry": {
  "includeServerId": true,
  "disableAutoReporting": false,
  "debug": false
}
Control error reporting to Sentry for crash analysis.

​
GUI Settings

From IrisSettings.java:241-245: 
"gui": {
  "useServerLaunchedGuis": true,
  "maximumPregenGuiFPS": false,
  "colorMode": true
}
Configure Iris GUI behavior (pregeneration visualizer, etc.).

​
Next Steps

API Reference

Learn to use Iris programmatically

Dimension Packs

Create custom dimension packs

Commands Reference

Complete command documentation

Discord Support

Get help from the community

Build docs developers (and LLMs) love

Get started for freeTalk to us