A pack is a folder of JSON files, binary objects, and images that describes one or more worlds. Edit the authoring folder in Studio, then stage a pack update to apply those changes to new chunks in a production world.

There is no manifest file, no registry, and no build step. A pack is a directory whose subfolder names tell Iris what type each file is. biomes/plains.json is a biome because it sits in biomes/. Move that same file to regions/ and Iris will try to parse it as a region.

The pack folder's own name is the pack key. A folder called packs/myworld/ is the pack myworld. Rename the folder and you have renamed the pack.

The only hard requirement is at least one .json file directly inside dimensions/. Everything else is optional. A folder you never create simply has no resources of that type.

packs/myworld/
  dimensions/
    myworld.json        -> key "myworld"
  regions/
    main.json           -> key "main"
  biomes/
    plains.json         -> key "plains"
    hills/
      rolling.json      -> key "hills/rolling"
  generators/
    plain.json          -> key "plain"

Five files. dimensions/myworld.json lists "main" in its regions array. regions/main.json lists "plains" and "hills/rolling" in landBiomes. Each biome names "plain" as a generator. That chain is the whole pack.

Note hills/rolling. Subfolders are yours to organize however you like. They become part of the key, and nothing else changes.

A key is the file's path under its type folder, with only the final extension removed. Dots in directory names and earlier parts of the filename remain in the key. For example, objects/trees.v2/oak.iob.iob uses trees.v2/oak.iob.

There is no namespace and no type prefix. You never write biomes/plains or iris:plains. The field you fill in already knows it wants a biome, so it searches biomes/ for you. Cross-references everywhere (region biome lists, object placements, spawner entity ids, structure piece pools) use exactly these keys.

Use exact filenames, including for nested resources. At the type-folder root, a file such as plains.disabled.json can still match the key plains; adding .disabled does not disable it. Keep one canonical filename per key and avoid null.json.

The dimension selected during world creation connects the pack resources:

dimension  ->  regions  ->  biomes  ->  generators   (terrain height/noise)
                                    ->  objects      (.iob models)
                                    ->  decorators   (surface clutter)
                                    ->  structures   (jigsaw / native)
                                    ->  spawners     -> entities
                                    ->  loot

• Dimension — the root. Sets world height, environment, seed behavior, and which regions exist. One dimension equals one world type.
• Region — a spatial zone. Regions decide which biomes can appear where, and can carry their own objects and structures that span biome edges.
• Biome — the workhorse. Block layers, surface treatment, decorations, object placements, structures, and mob spawns.
• Generator — noise and height math. Biomes reference generators to get terrain shape. Several biomes can share one.
• Object — a .iob block model with its own placement rules.
• Structure / jigsaw pool / jigsaw piece — multi-piece assemblies, either Iris-native or bridged to vanilla structures.

A resource must be referenced by the selected dimension, directly or through its regions and biomes, to generate.

A snippet is a JSON fragment you write once and reference from many places. Fields that support snippets accept an inline object or a string pointing at a snippet file. Studio schemas show which fields support them.

"style": "snippet/style/soft-hills"

resolves to <packRoot>/snippet/style/soft-hills.json.

The bundled overworld uses snippet/decorator/* and snippet/style/*.

Edit the source pack under packs/<key>/. Studio applies valid edits to new chunks. Production worlds use their saved pack until you stage an update and restart.

Include the complete iris/generation directory in world backups. Do not edit its saved pack files.

Invalid Studio edits leave the current pack active.

Existing chunks keep their saved terrain. New chunks use the updated pack, with a transition beside existing terrain.

See 10 - Studio & VSCode Schemas for the edit loop and 25 - Pack Management for production updates. Physical height, dimension type, and coordinate-scale changes require a new world. Generation modes, fluid baselines, and upper-terrain content can change within that fixed layout.

On mod loaders the pack root and the platform data dir are two different folders. Packs go under config/irisworldgen/. Everything else goes under config/iris/. If you are hand-placing a pack on a modded server, config/irisworldgen/packs/ is the one that matters.

Folders whose names start with . are skipped when Iris lists packs, which is why .iris/ inside a pack is invisible to the listing. Listing follows symbolic links, but installing a pack into a world uses a stricter check that refuses a symlinked root, any symlink in the tree, and any non-regular file. It also skips hidden subtrees.

Use these folders and file extensions for pack resources.

A pack needs all three of the following:

1. A pack directory.
2. A dimensions/ subdirectory.
3. At least one *.json file directly inside dimensions/. Nested dimension files do not meet this requirement.

Run /iris pack validate before creating a world. The pack must have zero blocking errors. See 25 - Pack Management for validation commands and content requirements.

Downloaded pack keys must match [a-z0-9_-]+. The check applies both to a caller-supplied expected key and to the key Iris derives from the archive.

An archive installed through link= has no expected key. Iris uses its shortest dimension key, then alphabetical order, as the install folder name while preserving every dimension in the pack. The built-in overworld and underworld downloads carry their exact expected key. That key picks the folder name. The whole pack is validated before publication.

After adding resources, refresh Studio completions with /iris studio update dimension=<pack> on Bukkit or /iris studio update <pack> on modded.

For orientation when reading packs/overworld/:

Feature-level detail: 12 - Regions, 13 - Biomes, 14 - Generators & Noise, 18 - Structures Overview, 19 - Objects, 21 - Jigsaw Structures, 23 - Loot, 23b - Entities & Spawners.

See also: 00 - Overview, 01 - Installation & Platforms, 10 - Studio & VSCode Schemas, 11 - Dimensions, 24 - Snippets, 25 - Pack Management.