Iris: a world generation engine for Minecraft servers, driven by JSON packs

What Iris is: an engine that reads packs, not a mod that hard-codes a world

Iris is a world generation engine for Minecraft servers and mod loaders. It generates terrain, biomes, caves, structures, objects and entities from editable JSON packs, with a full in-game studio authoring workflow.

That description is worth unpacking because the design choice in it is unusual for this ecosystem. Most Minecraft world generation mods are code: a generator class that decides where a cave goes. Iris is data: a pack of JSON files that describes a world, and an engine that interprets the pack. The pack is the artefact, and it is editable by a person using a studio inside the game rather than by a programmer writing Java.

The other structural decision is that the same engine runs on both sides of the loader divide. It runs as a Bukkit-family plugin and as a Fabric, Forge or NeoForge server mod. Cross-platform generation targets deterministic parity for identical artifacts, pack bytes, seeds and test areas, which is a strong claim: the same pack with the same seed produces the same world whether the server is Paper or NeoForge.

The master branch targets Minecraft 26.3, and the project is from VolmitSoftware with a homepage at volmit.com, GPL-3.0 licensed, the primary language Java, and the last push on 2026-10-19.

The release naming carries a lot of information. The recent versions are 4.3.4-26.1.2-26.3, described as faster biome locate, loot fixes and generation speedups, 4.3.3-26.1.2-26.3 with mining fixes and Docker memory improvements, and 4.3.2-26.1.2-26.3 with reload and world-save fixes. The first number is the Iris version, and the rest is the range of Minecraft versions the build supports, which is why there is a separate Iris version number at all when the Minecraft version is changing so often.

The repository layout backs this up. There is core/, spi/, adapters/, a probe/ directory, a packaging/ directory, a tools/ directory, a buildSrc/ directory, build-all.sh, a jitpack.yml and lombok.config. The spi/ directory is the interesting one, because a stable interface layer between the engine and the platform adapters is what makes the same engine run on Bukkit and on three mod loaders without duplicating it four times.

The platform matrix, and what differs between the plugin and the mod

The platform table in the README is the most useful single piece of information for anyone deciding whether Iris fits their server.

| Platform | Artifact | Minecraft | Notes | |---|---|---|---| | Paper / Purpur / Leaf / Canvas | plugin jar | 26.1.2 - 26.3 | Full feature set | | Folia | plugin jar | 26.1.2 - 26.3 | Region-safe scheduling throughout | | Spigot / CraftBukkit | plugin jar | 26.1.2 - 26.3 | Managed `iris:*` creation and generation; exact vanilla-slot `/iris replace` is unavailable | | Fabric | mod jar | 26.3 | Server worldgen + client HUD; requires Fabric Loader 0.19.5+ | | Forge | mod jar | 26.3 | Server worldgen + client HUD; current target is Forge 26.3-66.0.8 | | NeoForge | mod jar | 26.3 | Server worldgen + client HUD; requires NeoForge 26.3.0.65+; current target is NeoForge 26.3.0.83 |

Java 25 is required on every platform, which is a hard floor and worth checking before anything else.

Three distinctions matter. Folia is region-safe throughout, which is a different threading model from Paper and a common source of plugin incompatibility, so Iris calling it out is a real commitment rather than a checkbox. Spigot and CraftBukkit get managed iris:* creation and generation but not the early-bootstrap /iris replace path for the canonical Overworld, Nether or End slots, which is a real limitation for a server that wants Iris in the vanilla world slots specifically. And the three mod loaders get the server worldgen plus a client HUD, with specific version requirements: Fabric Loader 0.19.5 or later, the current Forge target of 26.3-66.0.8, and NeoForge 26.3.0.65-beta or later with a current target of 26.3.0.83.

The modded feature set is said to match the plugin wherever the operation is not Bukkit-bound, and the list is specific: worldgen from Iris packs, authoring with mod blocks, items and entities with validation suggestions, studio workspaces with schema autocomplete over the server's live registries, entity spawning parity including death loot, pregeneration with a boss bar or client HUD, the /iris command tree, and the goldenhash determinism gate, which is described as interchangeable across all four platforms.

That determinism gate is the interesting one. A hash over the generated output that can be compared across platforms is a testable claim, not a promise, and it is what makes the parity claim checkable in CI rather than a matter of trust.

Native worldgen over Iris terrain, and what Iris refuses to do

The most important section of the README for anyone with mods installed is the one on native worldgen over Iris terrain, and its central fact is that Iris replaces the chunk generator, so vanilla and mod worldgen only runs where Iris runs it. This is identical on every platform.

The table then says what survives and what does not.

Structures from vanilla, datapacks and mods are supported and on by default, and the control is importedStructures.disabled, which denies individual keys. Placed features, covering ores, trees, plants, springs and geodes, are supported but off by default, and the control is importedFeatures.enabled per dimension, with per-step and per-key filters.

Then come the hard limits. Carvers, which means caves, canyons and mod carvers, are never run, and the reason is architectural: Iris has no NoiseGeneratorSettings for a carver to sample, so the answer is to use the pack's caves and carvings. Surface builders and surface rules are never used either, because Iris builds its surface from pack palettes. Mod biomes only appear as a derivative, a vanillaDerivative, a biomeScatter or a biomeSkyScatter target, because Iris chooses biomes from the pack rather than from a biome source. Mob spawning, including mod mobs, is supported, with biome spawn tables merged with the vanilla derivative's.

The last row is the one that explains the rest. With importedFeatures off, which is the default, chunk output is byte-for-byte what Iris has always produced. That sentence tells you what the default is protecting: the ability to say that a given seed gives the same world as a previous version of Iris, which is what a server operator needs before rolling out a worldgen change to a live world.

There is a further consequence that is not in the table. Iris custom biomes now inherit the biome tags of their vanilla derivative on every platform, so the emitted datapack tag files change, and anything driven by biome tags therefore applies to Iris custom biomes, including mob variants, spawn rules, and any vanilla or mod content selecting on tags such as #minecraft:is_overworld. That is a compatibility consequence of moving biomes into the pack, and it is the kind of thing that shows up in a mod that assumed custom biomes were opaque.

Installing the plugin, and the pack download sequence that catches people out

The install section is short but the order of operations matters, and the README is specific about it.

For the plugin, on Paper, Purpur, Leaf, Canvas, Folia or Spigot, you drop the plugin jar into plugins/ and start the server. First boot performs no pack download. Then you run the download commands, waiting for each download to finish before starting another:

/iris download pack=overworld
/iris download pack=underworld
/iris download link=https://host/path/pack.zip

Restart after the download so Minecraft loads their dimension types and biomes. Custom packs that declare datapackImports must complete their external-datapack installation and registry restart first.

The waiting for each download to finish before starting another instruction is the sort of detail that saves an evening, because the commands are in-game chat commands and it is natural to type the next one before the first has finished.

Bukkit accepts Modrinth, direct HTTP(S) and absolute local file: ZIP URLs, and ZIPs under plugins/Iris/datapacks/imports/ are discovered for every Iris dimension. Plain Spigot supports ordinary managed /iris create, but not the early-bootstrap /iris replace path for the canonical Overworld, Nether or End slots.

For the mod, on Fabric, Forge or NeoForge, you drop the mod jar into mods/ and start the server. The jar is self-contained, with core, SPI and the required Fabric API modules bundled. First boot compiles only packs already on disk and never accesses the network, and /iris download installs a pack atomically without stopping the server. Custom packs that declare external datapack imports require compatible archives in that save's datapacks/ directory, and the modded /iris datapack ingest command is an explanatory stub that does not install them.

That asymmetry between plugin and mod is worth naming. The plugin path can pull packs and datapacks from the network, the mod path is offline-only and expects archives to be placed in the save directory. For a server operator, the mod path is easier to reason about because nothing changes on disk without you putting it there.

For singleplayer with modded clients, installed Iris packs appear as selectable World Types on the Create New World screen, and the integrated server runs the same engine, so what you see in singleplayer is what a server produces.

The client mod, the studio, and the language system

Installing the mod jar on a client adds a native pregeneration HUD: a top-left panel with a progress bar, chunks done and total, percent, chunks per second and an ETA, and it turns yellow while the pregeneration is paused. The H key toggles it and is rebindable under the Iris controls category.

That is a small feature and it is the one that tells you the project is aimed at people who generate large worlds. Pregenerating a world is a long operation, and a server admin needs to know it is progressing and how fast, and the pause state needs to be visible because a paused pregeneration looks like a hung one.

The studio is the other half of the workflow, and the README describes it as a full in-game studio authoring workflow, with studio workspaces offering schema autocomplete over the server's live registries. Autocomplete against live registries rather than a static schema is the detail that makes authoring practical, because a pack that references a block or a biome that does not exist on that server is the most common way a pack fails to work.

The language system is described in more detail than most projects give it, and the arrangement is unusual. Canonical English is defined in the typed Java catalogs under core/src/main/java/art/arcane/iris/localization, next to the command, Studio, runtime and UI surfaces that use it. Iris does not ship an English server translation file, and the required Minecraft client asset remains at assets/irisworldgen/lang/en_us.json. Complete server bundles and matching client assets are included for German, Spanish, Finnish, French, Hebrew, Italian, Japanese, Korean, Lithuanian, Dutch, Polish, Portuguese, Russian, Turkish, Vietnamese, Simplified Chinese and Traditional Chinese, and you select one by setting language in the Iris settings.

There is also an override mechanism for partial translations. A JSON file at languages/overrides/<locale>.json can override only selected server messages, and omitted entries resolve from the bundle and then from the code-owned English. So a translator can fix the messages that are wrong in their language without maintaining a full translation file, which is what makes community translation of a project with this many surfaces practical at all.

Editorial conclusion

Adopt Iris if you run a Minecraft server and want world generation you can edit as data rather than as code, and you are willing to accept that Iris owns the chunk generator and therefore owns what vanilla worldgen can and cannot do inside an Iris world. Do not adopt it if you need vanilla cave generation or vanilla surface rules, because Iris never runs carvers or surface builders over its own terrain. Before you build, read the imported features and imported structures controls, because turning imported features on changes chunk output and the default is off precisely so that output stays byte-for-byte what Iris has always produced.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. VolmitSoftware/Iris on GitHub