Iris configuration files

This configuration is small because all world configuration is done in Packs.

    "general": {
        "commandSounds": true,
        "debug": false,
        "disableNMS": false,
        "pluginMetrics": true,
        "splashLogoStartup": true,
        "useConsoleCustomColors": true,
        "useCustomColorsIngame": true,
        "forceMainWorld": "",
        "spinh": -20,
        "spins": 7,
        "spinb": 8
    "world": {
        "asyncTeleport": {
            "enabled": false,
            "loadViewDistance": 2,
            "urgent": false
        "postLoadBlockUpdates": true,
        "forcePersistEntities": true,
        "anbientEntitySpawningSystem": true,
        "asyncTickIntervalMS": 700,
        "targetSpawnEntitiesPerChunk": 0.95,
        "markerEntitySpawningSystem": true,
        "effectSystem": true
    "gui": {
        "useServerLaunchedGuis": true,
        "maximumPregenGuiFPS": false
    "autoConfiguration": {
        "configureSpigotTimeoutTime": true,
        "configurePaperWatchdogDelay": true,
        "autoRestartOnCustomBiomeInstall": true
    "generator": {
        "defaultWorldType": "overworld",
        "headlessPregeneration": false,
        "maxBiomeChildDepth": 4,
        "preventLeafDecay": true
    "concurrency": {
        "parallelism": -1
    "studio": {
        "studio": true,
        "openVSCode": true,
        "disableTimeAndWeather": true,
        "autoStartDefaultStudio": false
    "performance": {
        "trimMantleInStudio": false,
        "mantleKeepAlive": 30,
        "cacheSize": 4096,
        "resourceLoaderCacheSize": 1024,
        "objectLoaderCacheSize": 4096,
        "scriptLoaderCacheSize": 512

We have introduced a hot-loading feature for these settings, meaning they should automatically update in the server.

Updating settings related to Pregeneration are not hot-loaded during pregeneration!


These are the general settings that you would need to change for changing core functionalities of the software.

  • commandSounds: When enabled, plays sounds when using commands.

  • debug: When true, enables an extreme dump of information about Iris' internals working. Great for debugging a specific problem, terrible to read.

  • disableNMS: When enabled, turns NMS usage off. We use NMS (Minecraft's raw source code) for getting biome details, registering custom biome names, registering tile entities and more. Turning this setting to true will disable all these systems but may cause a lot of issues. Better not to touch.

  • pluginMetrics: This toggles plugin metrics for bstats. It helps us know what people are using so we can improve the plugin. All information is anonymous. Please leave this on :)

  • splashLogoStartup: Prints the fancy Iris logo on startup, if enabled.

  • useConsoleCustomColors: Use custom colors in the console.

  • useCustomColorsIngame: Use custom colors in game.

  • forceMainWorld: Force Datapacks to be in another folder. Best to leave empty.

  • spinh & spins & spinb: These dictate the gradients of the colors in the console and in-game.


Settings for generating worlds, among others.

  • asyncTeleport can be enabled and modifies the way players are teleported to (new) Iris worlds. If this is set to true, requests are handled asynchronously and chunks are generated async as well. The loadViewDistance is the distance (radius) in which chunks are prepared. The request can also be marked urgent which makes the server handle it more quickly.

  • postLoadBlockUpdates toggles whether Iris schedules block updates, or immediately runs them upon generation. This means that any block that is updated (such as the walls of caves, areas near water, etc) will be done while generating. This makes pregeneration much slower, but will have a decent performance improvement when the world is being used.

  • forcePersistEntities makes persistent in chunks, meaning mob spawns will be stored in the metadata Iris stores for each chunk, instead of it being queried from the pack.

  • anbientEntitySpawningSystem automatically spawns mobs in the area near the player as configured.

  • asyncTickIntervalMS is the delay beween entity spawn checks (higher = more performant, lower = more accurate mob counts)

  • targetSpawnEntitiesPerChunk modifies the amount of entities that Iris tries to spawn per chunk on a global level. If it is configured that 10 zombies should be spawned at any time, while this is on 0.9, there will be 9 zombies at any time.

  • markerEntitySpawningSystem toggles whether markers (specific locations in buildings) will be used to spawn entities at those locations.

  • effectSystem toggles whether particle effects are used in the world (such as little smoke clouds in the desert, pixie particles in the jungle, etc)


This is just a simple settings for toggling Iris' GUIs that pop up. If you have a hosted server you may want to disable them as you cant see them anyways.

  • useServerLaunchedGuis: When true, launches a GUI on Pregeneration start.

  • maximumPregenGuiFPS: When true, makes the FPS of the pregeneration GUI a lot higher but will also increase CPU usage, decreasing pregeneration speed. If you want to enjoy watching the GUI for a while, turn this to true, but keep it false if you are looking for maximum performance.


These are the Generator settings, they allow you to modify key elements of the Engines core functionality.

  • defaultWorldType: This changes the default pack Iris uses when any command that uses the default pack.

  • maxBiomeChildDepth: Iris supports cyclic biome references. I.e. desert could have a child biome savanna and savanna could in turn have child biome desert if you design it that way. This parameter stops biomes from infinitely generating children. Unless your biomes really take advantage of more than 5 layers of biome children (depth), there is usually no need to increase this.

  • preventLeafDecay: When true, prevents the active decay of leaves by setting them all to persistent.


  • parallelism: This setting dictates how many threads iris is allowed to use/make set it to -1 allows iris to dictate what its using leave this at -1 if you don't know how threads work. -2 sets the amount of threads to half the available, -4 to a fourth. You can also set this to 6, for example, which allows Iris to use 6 threads.


Studio mode allows you to design worlds with projects. This feature is used when designing worlds with a local server.

  • studio: When true, studio mode is activated and can be used.

  • openVSCode: When true, Iris automatically opens VSCode when you open a studio world.

  • disableTimeAndWeather: When true, time & weather changes do not happen in studio worlds.

  • autoStartDefaultStudio: When starting the server, this will start a studio world immediately.


Pregeneration settings for caching, specifically within Mantle. Don't modify unless you have some idea of what you're doing. These affect the caches and mantle, two integral parts of the engine & generator.

  • trimMantleInStudio toggles whether a truncated, more performant, mantle is used for studio worlds. Set this to true if you are not editing entities, interested in finding objects, or knowing which biome you are in, while in studio worlds, but want better performance.

  • mantleKeepAliveSeconds: The number of seconds after which cached mantle data is invalidated and saved. The higher this is, the more RAM you need during pregen. The default is suitable for pregen. Increasing this number further will not help much, compared to how much extra RAM it costs, unless you have really slow drive.

  • cacheSize: Iris caches a lot of data during generation. This saves a lot of time during generation but takes some extra memory. This cache is the cache each individual stream of data can use at most. This number was generated with an optimization function, changing it is not advisable.

  • resourceLoaderCacheSize modifies the cache size for any non-script and non-object configuration file. Increasing this increases the RAM requirement of your server, for a small performance boost to pregeneration.

  • objectLoaderCacheSize modifies the cache size for objects. Higher requires more RAM, but increases performance.

  • scriptLoaderCacheSize modifies the cache size for scripts. Higher requires more RAM, but increases performance.

Last updated