Brian Neumann-Fopiano
12 KiB
02 - Getting Started
This page walks through creating an Iris world, teleporting into it, running a short pregeneration, and opening a studio pack workspace. Command argument style differs by platform: Bukkit uses Director keyed optional parameters; modded uses Brigadier positional arguments and flag literals.
Full command trees and permissions: 04 - Commands & Permissions.md. World lifecycle detail: 06 - Worlds & Lifecycle.md. Studio detail: 10 - Studio & VSCode Schemas.md.
Outcome
At the end you will have one disposable Iris world created from the overworld pack, you will have entered it, generated a small known area, and opened a separate Studio authoring session. Use the fixed seed 1337 until the workflow is proven; changing seeds while diagnosing a pack makes comparisons ambiguous.
Treat each numbered section as a gate. Confirm the world is loaded before teleporting, confirm ordinary chunks generate before starting pregen, and confirm the Studio world is separate from the production snapshot before editing files.
Prerequisites
- Iris installed per
01 - Installation & Platforms.md - Java 25 server or mod instance running
- Operator / gamemaster access (
iriscommands; modded mutating commands require permission level 2 / gamemasters) - Managed Overworld and Underworld packs present (auto-downloaded on first boot) or the required project pack installed under the platform packs directory
Argument style
| Platform | Required args | Optional args | Example |
|---|---|---|---|
| Plugin (Bukkit) | Positional in declaration order | Must be key=value |
/iris create myworld type=overworld seed=1337 |
| Mod (Fabric / Forge / NeoForge) | Positional | Further positional tokens or literal flags | /iris create myworld overworld 1337 |
On Bukkit, a bare extra token that is not a known key is a hard error. On modded, pregen flags are combinable literals (gui, sync, nocache) after the radius / dimension / center.
1. Create a world
Plugin
/iris create <name> [type=…] [seed=…] [main=true|false]
| Parameter | Aliases | Default | Meaning |
|---|---|---|---|
name |
world-name |
(required) | World name |
type |
dimension, pack |
default → generator.defaultWorldType (overworld) |
Pack/dimension load key |
seed |
— | 1337 |
World seed |
main |
main-world |
false |
If true, register a shutdown hook to promote this world as level-name in server.properties |
Aliases for the create command itself: c.
Reserved names (plugin): iris and benchmark are rejected (case-insensitive). Iris suggests using another name (for example irisworld).
Already exists: if the managed dimension root already exists, create aborts.
Folia: runtime create is disabled. Iris stages world files, installs the pack snapshot, registers bukkit.yml, and tells you to restart the server. After restart the world can load. See 01 - Installation & Platforms.md.
Non-Folia: create builds the world immediately via IrisToolbelt.createWorld() (production, not studio).
/iris create myworld type=overworld seed=1337
Run /iris worlds after the command. On non-Folia servers, myworld must appear as a loaded Iris world. On Folia, success is the staging-and-restart message; restart before continuing.
Mod
/iris create <name> [pack] [seed]
| Parameter | Default | Meaning |
|---|---|---|
name |
(required) | Dimension id fragment; normalized under namespace irisworldgen when not fully qualified |
pack |
overworld |
Pack key (optional pack:dimension form when the pack’s dimension key differs) |
seed |
1337 |
Long seed |
Aliases: c. Equivalent world management lives under /iris world create|enable with the same enable path.
If the pack is not installed, create starts an async download of IrisDimensions/<pack> then injects the dimension. On success the dimension is live and re-injected on later startups.
/iris create myworld overworld 1337
There is no separate “load” step on modded after a successful create.
Run /iris world status and confirm the new dimension uses pack overworld. Then run /iris info irisworldgen:myworld as a gamemaster and verify seed 1337 before teleporting.
2. Load a world (plugin only)
/iris load <world>
Aliases: import. Requires an existing managed dimension directory on disk. Origin: player (Director PLAYER). Loads through BukkitWorldReconciler and registers the world with the server.
Modded worlds created with /iris create or /iris world enable are already injected; use teleport instead of load.
3. Teleport
Plugin
/iris teleport <world> [player=…]
Aliases: tp. Teleports the target (or the executing player) to the world spawn asynchronously when possible.
/iris tp myworld
Success is a completed teleport followed by normal chunk generation around spawn. If the teleport target is missing, return to the create/load gate instead of retrying pregen.
Mod
/iris teleport <dimension> [player]
/iris tp <dimension> [player]
Dimension is a loaded level argument (tab-completes Iris dimensions). Console must name a player. Teleport target is a fixed spawn-like position in the Iris dimension (engine-managed placement).
/iris tp irisworldgen:myworld
Success is entry into irisworldgen:myworld with /iris info irisworldgen:myworld still reporting the expected pack and seed.
4. Pregenerate
Radius is in blocks. One pregeneration job runs server-wide.
Plugin
/iris pregen start <radius> [world=…] [center=x,z|me] [gui=true|false] [serial=true|false]
| Parameter | Default | Notes |
|---|---|---|
radius |
(required) | Blocks; must be > 0 |
world |
contextual (sender’s world) | Target world |
center |
0,0 |
Or me for player position; aliases middle |
gui |
true |
Open pregen GUI when available |
serial |
false |
One chunk at a time; requires Paper-compatible server |
Control:
/iris pregen stop
/iris pregen pause
/iris pregen status
Example:
/iris pregen start 352 world=myworld center=0,0 gui=false
Immediately run /iris pregen status. A 352-block radius centered at 0,0 should report a 2,025-chunk job and advance without a growing failed count.
Mod
/iris pregen start <radius> [dimension] [at <x> <z>] [gui] [sync] [nocache]
| Piece | Meaning |
|---|---|
radius |
1–100000 blocks |
dimension |
Optional level; defaults to current dimension |
at x z |
Optional center (default 0, 0) |
gui |
Request progress map window on the server display when GUI is launchable |
sync |
Synchronous chunk writes |
nocache |
Disable resumable checkpoint cache (default is cached / resumable) |
Flags are optional and combinable in any order after the radius/dimension/center prefix.
/iris pregen start 352 irisworldgen:myworld at 0 0 sync
Immediately run /iris pregen status and confirm the target dimension, total, and generated count. Use /iris pregen stop before retrying with different flags.
Control: /iris pregen stop, pause / resume, status. Progress: client mod HUD when present, otherwise boss bar / console.
5. Studio (first authoring steps)
Studio worlds are transient: closed on command, purged at startup. They read the live pack and hotload JSON/object edits into newly generated chunks. Production worlds do not (see pitfalls below).
Plugin
/iris studio create [name=studio] [template=…]
/iris studio open <dimension> [seed=1337]
/iris studio vscode [dimension=default]
/iris studio close
| Command | Aliases | Notes |
|---|---|---|
create |
+ |
Omitting template scaffolds a starter pack (minimal dimension/region/biome/generator). Providing a template copies an existing packs entry (or downloads it) |
open |
o |
Temporary studio world for the pack |
vscode |
vsc |
Write / open a .code-workspace with live registry schemas |
close |
x |
Discard studio world |
Default create name is studio; if that folder already exists, Iris picks the next free name.
Mod
/iris studio create [name] [template]
/iris studio open <pack> [seed]
/iris studio vscode [pack]
/iris studio update [pack]
/iris studio close
| Command | Notes |
|---|---|
create / + |
Defaults: name studio, template example (differs from Bukkit starter-pack path when template omitted) |
open / o |
Pack required; seed default 1337 |
vscode / vsc |
Generate workspace |
update |
Regenerate schemas only |
close / x |
Discard studio |
Some Bukkit studio tools (importvanilla feature capture, loot GUI, profile, etc.) refuse or redirect on modded with an explicit message; capture vanilla features on Bukkit and copy the pack folder if needed.
Plugin example:
/iris studio open overworld seed=1337
/iris studio vscode dimension=overworld
Modded example:
/iris studio open overworld 1337
/iris studio vscode overworld
The Studio gate passes when the transient Studio world opens, the workspace points at the live packs/overworld/ tree, and a saved valid JSON change produces a hotload result. Close it with /iris studio close; production myworld must remain separate.
Suggested first-session flow
- Confirm pack: ensure
overworld(or your pack) exists under the platform packs directory. - Create world (plugin or mod forms above).
- On Folia plugin: restart after staging, then load if needed.
- Teleport into the world.
- Optional:
/iris pregen start 352 …for a small square (~704×704 blocks). - Optional:
/iris studio open <pack>to edit live; use VSCode schemas for autocomplete of blocks/items/entities (mod content included on mod loaders).
The session passes when the production world loads again after a clean restart and generates new chunks from its copied pack snapshot. Remove a disposable world only through the lifecycle command after evacuating players; see 06 - Worlds & Lifecycle.md.
Common pitfalls
| Pitfall | What happens | What to do |
|---|---|---|
World name iris or benchmark (plugin) |
Create rejected | Use another name |
Editing packs/<pack> after production create |
No effect on existing worlds | Production engines read <world>/iris/pack snapshot. Push with /iris developer update-world world=<world> pack=<dimension> confirm=true (Bukkit, all keyed) and restart; or only new chunks after update. Studio reads live packs |
| Expecting pack edits in old chunks | Only new chunks use new config | Fly to unexplored terrain, pregen fresh radius, or use studio |
| Folia: create then teleport immediately | World not live yet | Restart after staging message, then load/teleport |
| Mod: new pack heights/biomes missing | Forced datapack not yet applied | Restart after installing pack |
/iris load on modded |
No equivalent subcommand | Use create/enable + teleport |
Bukkit optional args without key= |
Parse error | Use seed=1337, not a bare second number for optional params |
| Mod pregen while another job runs | Start fails | /iris pregen stop then start again |
| Studio closed mid-edit | World discarded | Edits on disk in packs/ remain; reopen studio |
| Managed pack download blocked | Startup or create/open fails with a missing pack | Allow HTTPS or install with /iris download overworld and /iris download underworld; an offline install must contain each complete pack tree |
type=default vs pack key |
Resolves via generator.defaultWorldType |
Prefer explicit type=overworld or your pack key |
Quick reference
Plugin
/iris create myworld type=overworld seed=1337
/iris tp myworld
/iris pregen start 352 world=myworld center=0,0 gui=false
/iris studio open overworld seed=1337
/iris studio close
Mod
/iris create myworld overworld 1337
/iris tp irisworldgen:myworld
/iris pregen start 352 irisworldgen:myworld at 0 0
/iris studio open overworld 1337
/iris studio close
Next: pack structure in 05 - Concepts & Pack Layout.md, configuration in 03 - Configuration.md.