Files
Iris/docs/04 - Commands & Permissions.md
T
Brian Neumann-Fopiano 623a02025c content
2026-08-11 20:35:27 -04:00

30 KiB
Raw Blame History

04 - Commands & Permissions

Iris exposes one root command, /iris (aliases /ir, /irs), with Bukkit using VolmLib Director for named parameters and optional key=value arguments. Fabric, Forge, and NeoForge register a Brigadier tree with the same root aliases. This is the complete command reference; platform gaps are marked Bukkit-only or modded-only. See 30 - Platform Differences.md for a matrix and 03 - Configuration.md for /iris reload targets.

Common command recipes

Use these as entry points; follow the linked guide before running destructive or long-running forms.

Goal Bukkit-family Fabric / Forge / NeoForge Success check Detailed guide
Create and enter a disposable world /iris create tutorial type=overworld seed=1337, then /iris tp tutorial /iris create tutorial overworld 1337, then /iris tp irisworldgen:tutorial World/dimension appears in /iris worlds or /iris world status; ordinary chunks generate 02 - Getting Started.md
Replace the vanilla Nether slot /iris create world_nether type=underworld seed=1337 overwrite=true, then restart Not available minecraft:the_nether loads through Iris and the retained old Nether is removed only after verification 06 - Worlds & Lifecycle.md
Validate a pack before world creation /iris pack validate pack=overworld /iris pack validate overworld No blocking validation errors 25 - Pack Management.md
Open the live authoring pack /iris studio open overworld seed=1337 /iris studio open overworld 1337 Transient Studio world opens and a valid save hotloads 10 - Studio & VSCode Schemas.md
Create an in-game jigsaw project /iris jigsaw create overworld village/demo Not available; author on Bukkit and copy the saved pack Owned planar, Iris-native graph is created atomically with six 15×15×15 workcells, one variant per archetype, and seed 1337; edits then autosave 21 - Jigsaw Structures.md
Inspect an Iris jigsaw graph /iris structure info overworld <structure> /iris structure info <structure> while in its Iris dimension Resolved graph reports pieces and bounds 21 - Jigsaw Structures.md
Pregenerate a small test area /iris pregen start 352 world=<world> center=0,0 gui=false /iris pregen start 352 <dimension> at 0 0 /iris pregen status advances with no accumulating failures 07 - Pregeneration.md
Remove a disposable Iris world Evacuate players, unload, then /iris remove <world> /iris world delete <dimension> Target is absent from world status and its managed data is removed 06 - Worlds & Lifecycle.md

Do not translate Bukkit key=value examples token-for-token to a mod loader. Use the Brigadier forms in the matching command sections.

If a command fails before doing work, check in this order: platform syntax, permission level, sender requirements (player versus console), exact pack/world key, then lifecycle busy state. A parse error is not evidence that the underlying feature failed.

Syntax

Bukkit (Director)

  • Root: /iris / /ir / /irs.
  • Subcommands and nested groups use method names (or @Director(name=...)) and aliases.
  • Required parameters appear as positionals; optional parameters with defaults accept name=value (or short aliases from @Param).
  • Help uses Director mini-menu: required shown as <name>, optional with default as [name=default].
  • Example: /iris create myworld type=overworld seed=42 main=false overwrite=false
  • Example: /iris pregen start 5000 world=world center=me gui=true serial=false
  • Contextual params (world, dimension, location) often resolve from the senders current world or look target when omitted.

Modded (Brigadier)

  • Same root and most names; arguments are ordered literals/arguments, not free-form key=value.
  • /iris and /iris help [section] print the help browser (player paginated UI; console text list).
  • Flags are literals where used (e.g. pregen gui, sync, nocache; download force).

Permissions

Bukkit

Permission Declared in plugin.yml / paper-plugin.yml Default Gate
iris.all Declared in plugin.yml / paper-plugin.yml (default: op) Operators receive it by default; otherwise grant explicitly CommandSVC rejects every /iris execution without iris.all
iris.treefeller Yes op Survival tree feller only (TreeFellerSVC); requires treeFeller.enabled in settings

iris.all is code-gated as ROOT_PERMISSION in CommandSVC and declared on the plugin with default: op. Without it, the sender gets a permission-denied message and no subcommand runs.

Custom-biome restart warnings also notify online players who are op or hold iris.all.

Modded

Gate Brigadier level Applies to
Gamemaster Commands.LEVEL_GAMEMASTERS Mutating commands: create/world, studio, object tools, pregen, download, debug, reload, evacuate, seed, structure place, edit, developer, etc.
Read-only Commands.LEVEL_ALL version, info/worlds (seed field omitted unless gamemaster), height, metrics, what (relaxed at root), help

Tree feller on mod loaders uses platform permission APIs (irisworldgen:treefeller on Fabric; PermissionAPI nodes on Forge/NeoForge), not Bukkit permission strings.


Root: /iris

Command Aliases Platforms Params (Bukkit-style) Description
(empty) / help Both [section] (modded) Open help; modded supports section path
version Both Print Iris/platform/Minecraft version and engine count
info Modded (see worlds) [dimension] List Iris dimensions and pack details; seed only for gamemasters
create c Both Bukkit: <name> [type=default] [seed=1337] [main=false] [overwrite=false] (type aliases dimension,pack; overwrite alias force). Modded: <name> [pack=overworld] [seed=1337] Create an Iris world/dimension; Bukkit overwrite=true stages an exact slot replacement for restart
teleport tp Both Bukkit: <world> [player=<name>]. Modded: <dimension> [player] Teleport self or named player into Iris world/dimension
evacuate Both Bukkit: <world> (player origin). Modded: [dimension] Move players out of Iris world to fallback/primary
height Both Print world height (player on Bukkit)
worlds accesslist Both Bukkit: access list of worlds. Modded: same as info (read-only); accesslist requires gamemaster
remove rm Bukkit <world> [delete=true] Remove managed Iris world; disk deletion defaults to true
load import Bukkit <world> Load managed Iris world
unload Bukkit <world> Unload Iris world
debug Both Toggle general.debug and save settings
download dl Both <pack> [branch=stable] [overwrite=false] (overwrite alias force) Download pack project
metrics measure Both Generation metrics (player / current Iris level)
reload Both Reload settings.json and locale; modded also schedules forced datapack regeneration
seed Modded Print world/engine seeds (gamemaster)
regen rg Modded root; Bukkit under developer [radius] Delete/regenerate nearby chunks
goldenhash gold Modded root; Bukkit under developer [radius] [threads] [capture|verify] Deterministic buffer hashes
wand Modded root (+ object) Give object wand
dust d Modded root (+ object) Give reveal dust
find goto Both see Find Locate biome/region/object/structure/POI
what Both see What Inspect context
edit Both see Edit Open JSON in desktop editor
pregen pregenerate Both see Pregen Pregeneration control
object o Both see Object Object tools
studio std, s Both see Studio Studio / pack authoring
jigsaw jig, jgs Bukkit see Jigsaw Transaction-owned planar/spatial Jigsaw Studio
pack pk Both see Pack Validate/cleanup/restore/status
structure struct, str Both see Structure Structure index/import/place
datapack datapacks, dp Both see Datapack Datapack helpers
developer dev Both see Developer Diagnostics
world w Modded see World Runtime dimension enable/disable

On Bukkit, overwrite=true is deliberately restart-only. The name may resolve to a safe iris:* world or exactly the configured main, _nether, or _the_end alias; arbitrary minecraft:* and foreign namespaces are rejected. Iris stages and validates a fresh pack snapshot, compare-and-swaps only that world's bukkit.yml generator and seed, and retains the existing dimension folder as a rollback backup until the restarted world proves its Iris identity, pack, dimension, environment, and seed. Multiple distinct slots may be staged before one restart. main=true is valid with overwrite only when the name is the configured main-world name. Exact vanilla slots preserve the authoritative seed shared by the existing level, regardless of the supplied seed; this keeps Overworld/Nether/End coordinate generation aligned. Use ordinary new-main promotion when a new level seed is required.


Find: /iris find (goto)

Origin: player (Bukkit). Modded: gamemaster gate.

Command Params Description
biome Bukkit: <biome> [teleport=true]. Modded: <key> Find Iris biome; teleport default true on Bukkit
region Bukkit: <region> [teleport=true]. Modded: <key> Find Iris region
object Bukkit: <object> [teleport=true]. Modded: <key> Find object placement (Bukkit may teleport to object studio first)
structure Bukkit: <structure> (sync). Modded: <key> Find vanilla/datapack/Iris structure
poi Bukkit: <type> [teleport=true]. Modded: <type> Find supported point of interest
unregistered Print structures excluded from goto completion and rejection reasons to console

What: /iris what

Bukkit origin: player only. No bare here command on Bukkit.

Command Platforms Params Description
(empty) / here Modded Full inspect at player position
biome Both Current Iris biome
region Both Current Iris region
block Both Target block
hand Both Held item
markers Both <marker> Reveal nearby markers (e.g. cave_floor, cave_ceiling, object)

Edit: /iris edit

Bukkit origin: player. Opens pack JSON in the desktop editor.

Command Aliases Params Description
biome b Bukkit: <biome>. Modded: [key] Open biome JSON (modded: omit key for current)
region r Bukkit: <region>. Modded: [key] Open region JSON
dimension d Bukkit: <dimension>. Modded: Open dimension JSON (modded: current pack)

Pregen: /iris pregen (pregenerate)

Command Aliases Params Description
start Bukkit: <radius> [world=<world>] [center=0,0] [gui=true] [serial=false] (radius alias size, center alias middle, use me for player). Modded: <radius> [dimension] [at <x> <z>] [gui] [sync] [nocache] Start pregen; radius in blocks; resumable checkpoint cache on by default on modded unless nocache
stop x Stop active pregen
pause resume Toggle pause/resume
status Progress, CPS, ETA, method, failures

Bukkit: serial=true requires a Paper-compatible server (strict serial chunk generation). Modded: sync is the serial-like flag; gui opens boss-bar/GUI path when available.

See 07 - Pregeneration.md.


Object: /iris object (o)

Bukkit: group origin player. Root wand/dust also exist on modded.

Command Aliases Platforms Params Description
wand Both Give Iris object wand
dust d Both Give reveal dust
save Both Bukkit: [dimension=<key>] <name> [overwrite=false] [legacy=true]. Modded: [overwrite] <name> Save wand selection as .iob
paste Both Bukkit: <object> [edit=false] [rotate=0] [scale=1]. Modded: [at x y z] [rotate degrees] <key> Paste object
expand Modded [amount] (default 1) Expand selection along look
contract - Both [amount=1] Contract selection along look
shift Both [amount=1] Shift selection along look
position1 p1 Both Bukkit: [here=true] (look vs feet). Modded: [look] Set selection point 1
position2 p2 Both same Set selection point 2
x+y xpy (modded) Both Autoselect up and out
x&y xay (modded) Both Autoselect up, down, and out
analyze Both <object|key> Composition stats
shrink Both <object|key> Shrink object to minimum bounds
plausibilize Both Bukkit: <key|prefix/> [dryrun=false] [reach=12]. Modded: greedy args key [dryrun=true] [reach=N] Grow branches so leaves survive vanilla decay
undo u Both [amount=1] Undo pastes
we Bukkit; modded stub Wand + import WorldEdit selection
studio Bukkit; modded stub [dimension=null] [seed=1337] Object studio grid world
convert Bukkit; modded stub Convert convert/ folder .schem.iob

Studio: /iris studio (std, s)

Command Aliases Platforms Params Description
open o Both Bukkit: <dimension> [seed=1337]. Modded: <pack> [seed] Open temporary studio dimension; the owning player may replace an active Jigsaw Studio, and Iris waits for its autosave and active operation barriers before closing it
close x Both Close studio and discard world; Bukkit requires /iris jigsaw close for an active Jigsaw Studio
tpstudio stp Both Teleport into open studio
status Modded (Bukkit uses other paths) Show open studio and pack
create + Both Bukkit: [name=studio] [template=<dimension>]. Modded: [name] [template=example] Create pack project
package pkg (Bukkit method pkg, alias package) Both Bukkit: [dimension=default] [obfuscate=false] [minify=true]. Modded: [pack] Zip/package pack
version Both Bukkit: [dimension=default]. Modded: [pack] Pack version
regions Both Bukkit: [radius=500] (player). Modded: [radius] default 500 Nearby region distribution
noise nmap Both Bukkit: [generator=<key>] [seed=12345]. Modded: [generator] [seed] Noise explorer GUI
map render Both Bukkit: [world=<world>]. Modded: Vision map GUI
vscode vsc Both Bukkit: [dimension=default]. Modded: [pack] Generate/open code workspace
update Both same as vscode pack Regenerate workspace only
importvanilla importv, iv Bukkit functional; modded message <dimension> [variants=3] [structures=true] Import vanilla trees/objects/structures into pack
scoreboard board, sidebar, sb Bukkit Toggle studio debug scoreboard
loot Bukkit; modded stub [fast=false] [add=true] Simulate chest loot GUI
profile Bukkit; modded stub [dimension=default] Pack performance profile
spawn summon Bukkit; modded stub <entity> [location=<x,y,z>] Spawn Iris entity
objects find-objects Bukkit; modded stub IGenData chunk report for nearby chunks

See 10 - Studio & VSCode Schemas.md.


Jigsaw: /iris jigsaw (jig, jgs)

Bukkit-only; player origin. This opens a transient Jigsaw Studio through the same single active Studio lifecycle. Saved Iris jigsaw resources run through the shared core on every platform, but Fabric/Forge/NeoForge do not register this authoring command tree.

Command Params Description
create <dimension> <key> [mode=planar] [compatibility=iris] [width=15] [height=15] [depth=15] [seed=1337] Add-only atomic graph creation followed by open; named structure= and name= alias key=; mode completes planar/spatial, compatibility completes iris/vanilla; planar X/Z 3..128, spatial X/Z 1..128, Y 1..192, volume <=2,097,152
convert <dimension> <source> [target=auto] [seed=1337] Add-only conversion of one live registered vanilla/datapack jigsaw into an owned Iris graph, then open it; aliases import, import-vanilla
adopt inspect <dimension> <source> [target=auto] [strategy=auto] Asynchronously inspect an existing Iris closure and issue a hash-pinned IN_PLACE, CLONE_REQUIRED, or BLOCKED plan; strategy completes auto, in-place, clone
adopt apply <planId> Revalidate and atomically apply that player's unexpired plan, then open the target at seed 1337; active/opening Jigsaw Studio is rejected
open <dimension> <key> [seed=1337] Open an existing graph in compact workcells; aliases edit, reopen; existing Iris structure keys tab-complete; owner, autosave, and operation barriers protect replacement
close [discard=false] Close Studio; refuse active autosave/load/graph work or a pending dirty capture unless deliberately discarded
status Show project/workcell state and the current automatic seed-1337 evaluation, theme, piece count, and diagnostic
menu Open the six-row controls also opened by the generated chest or three sneaks within 1.5 seconds
select Select the workcell containing the player
goto <workcell> Select and teleport above a stable workcell ID; alias teleport
particles <visible> Toggle player-local workcell-bound, connector, and temporary assembly-preview particle trails
save [bay=selected] Flush the selected dirty workcell's automatic capture now; normal block and container updates already autosave
connector channel <channel|none> Look at a saved marker in the active owned workcell within 8 blocks and set/clear its Iris-only channel at the inverse-mapped source position
bounds <width> <height> <depth> Set the selected workcell capacity without resizing any variant object; every existing variant must fit, and the compact Studio layout regenerates in place; aliases cell, resize
workcell capacity <width> <height> <depth> Explicit nested form of bounds; planar capacities are per canonical archetype and spatial capacity is the shared envelope for its one-row variant cells
workcell label <displayName> Set the selected planar or spatial workcell's author label; quote spaces; solver identity remains canonical
workcell label-reset Reset the selected workcell to its canonical solver label; alias reset-label
pool create <poolKey> [fallbackPoolKey=none] Atomically create an empty owned pool, optionally using an existing owned direct fallback
piece create <poolKey> <pieceKey> [weight=1] Create and load an owned variant; planar derives connectors from the contextual canonical workcell
piece add <poolKey> <pieceKey> [weight=1] Re-add and load an existing piece/object already owned by this project
piece remove <poolKey> Remove the active variant from a pool without deleting its owned resources
piece rotatable <true|false> Persist cardinal rotation for the active variant; portable sessions reject false
piece expand Resize the active planar or spatial owned variant exactly to workcell capacity; planar canonical sockets move to the new faces
variant weight <poolKey> <weight> Set the active variant's positive weight in an owned pool
variant resize <width> <height> <depth> Resize only the active owned variant within its workcell capacity; safe shrink rejects cropped content and the active cell reloads in place
variant label <displayName> Set the active variant's author label; quote spaces
variant label-reset Reset the active variant to its resource-key fallback; alias reset-label
variant duplicate Copy the active variant's object, metadata, and exact pool memberships into one new variant in this workcell
variant duplicate-family [themeKey=next] Atomically clone every enabled workcell's active owned variant into one coherent Iris family and load the whole family; alias family
rules limits <maxDepth> <maxSizeChunks> Set depth 1..30 and radius 1..32; VANILLA_PORTABLE is restricted to <=20 and <=8
rules fallback <poolKey> <fallbackPoolKey|none> Set or clear one owned pool's direct fallback after compiling the complete graph
preview goto Teleport above the permanent seed-1337 block preview; alias teleport
preview assemble [seed=1337] Compute a deterministic read-only assembly at the player, report its complete piece count, and show in-range bounds as purple particle boxes for 10 seconds within the shared particle budget; places no blocks
export [namespace=iris] [output=jigsaw-export] [format=zip] [replace=false] Start a background strict Minecraft 26.2 vanilla datapack export as one direct artifact under the Studio packs exports/ folder
delete [confirm=false] With confirm=true, scan reverse references, close Studio, and hash-pinned-delete the complete owned project; alias remove

There is no Jigsaw Studio undo command, adoption rollback command, or mod-loader authoring command. Undo Last Autosave in Workcell Settings restores the newest of five previous saved graph iterations retained in one .iris/jigsaw-history/key-<sha256>.json file. Reset Connector Blocks restores the selected workcell's saved connector blocks without replacing its other edited blocks. Planar Studio always has six independently capacitated/enabled canonical workcells. Spatial Studio places every variant in a dedicated one-row cell; a new project seeds seven 15×15×15 variants with 0 through 6 cumulative face-center connectors. All cells retain one clear block of separation and use physical white-concrete edge cages with player-local particle trails inside them; Jigsaw Studio spawns no display entities for workcell bounds. Every variant retains its own exact dimensions and optional display label. Workcell and variant rename tools are renamed in an anvil, right-clicked to apply, and sneak-right-clicked to reset. A catalog may contain at most 512 variants. Natural creature spawning is disabled in the transient Studio world. The seed-1337 assembly is evaluated automatically and rendered as a permanent protected block preview; spatial previews form an elevated connected assembly, while preview assemble remains the separate temporary arbitrary-seed particle diagnostic. See 21 - Jigsaw Structures.md for GUI/toolbox controls, whole-assembly theme chances, independent pool-entry chances, rules/caps, markers, ownership, placement, export, and recovery.

Bukkit has one global Studio project/world and the Jigsaw session belongs to one owning player. Only that owner can control, load, or mutate it; entering a workcell makes that physical cell the owner's next menu selection. Non-owner edits are cancelled and non-owner commands use a strict informational/communication allowlist. Block and inventory changes in loaded owned workcells autosave after a 40-tick quiet period. Duplicate-one and duplicate-family actions queue once behind pending autosave, expedite it, and continue automatically against the same request and source variants. The chest and live preview are protected; schema-1 or otherwise stale toolbox sticks are rejected. A later mutation after capture starts remains dirty for another capture. Plugins that bypass covered events must call JigsawStudioService.markDirty(...) or markAllDirty(...).


Pack: /iris pack (pk)

Command Aliases Params Description
validate v Bukkit: [pack=<key>]. Modded: [pack]; empty = all Validate pack(s) and publish results
cleanup c Bukkit: <pack> [mode=preview]. Modded: <pack> [apply] Preview/quarantine unused resources
restore r same pattern Preview/restore latest quarantine
status s Bukkit: [pack=<key>]. Modded: [pack] Startup-published validation status, including persisted unchanged results

See 25 - Pack Management.md.


Structure: /iris structure (struct, str)

Command Aliases Platforms Params Description
list ls Both Bukkit: <dimension>. Modded: current engine pack Write structure-index.json
info Both Bukkit: <dimension> <structure>. Modded: <key> Resolve jigsaw graph bounds
place p Both Bukkit: <dimension> <structure> (player). Modded: <key> Assemble and place at the player; Bukkit reports the exact changed-block count and rejects air-only or already-identical no-op results
import import-all, reimport, imp, all Bukkit; modded message <dimension> Import all vanilla/datapack structures as editable Iris resources (overwrites)
capture cap Bukkit; modded message <dimension> Capture code-only structures via scratch world
verify locateall Both Bukkit: <dimension> [radius=48]. Modded: [key] Native/Iris structure reachability report

See 18 - Structures Overview.md, 21 - Jigsaw Structures.md, 22 - Native Structures & Datapacks.md.


Datapack: /iris datapack (datapacks, dp)

Command Aliases Platforms Params Description
ingest pull Bukkit; modded message [restart=false] Download/install Modrinth datapackImports into world datapacks
list ls Both Bukkit: configured imports + installed. Modded: configured/installed world datapacks
remove rm Bukkit; modded message <id> Remove installed datapack by id
status Modded Check Iris dimension-type overrides vs pack heights
install Modded Install dimension-type override datapack for loaded Iris dimensions

See 22 - Native Structures & Datapacks.md.


World (modded-only group): /iris world (w)

Bukkit uses root create / load / unload / remove / evacuate instead.

Command Aliases Params Description
enable create <dimension> <pack|pack:dimensionKey> [seed|random] Create/inject persistent Iris dimension (downloads pack if missing)
replace-overworld <pack|pack:dimensionKey> [seed|random] Inject primary world routing
mainworld <pack|pack:dimensionKey|off> [seed|random] Configure main-world preset in modded.json
disable <dimension> Evacuate and unload; keep disk data
delete remove, rm <dimension> Disable and wipe chunk/mantle data
list ls List loaded Iris dimensions
status Loaded dimensions + primary world config

Developer: /iris developer (dev)

Command Aliases Platforms Params Description
EngineStatus Bukkit Loaded tectonic plate count
Sentry sentry (modded) Both Send test exception to error reporter
genhash Bukkit [world] [radius=4] [center-x=0] [center-z=0] Hash generated blocks in fixed area
update-world ^world Bukkit [world=<world>] [pack=<dimension>] [confirm=false] [fresh-download=false] Unsafe pack swap into world
mantle Bukkit [plate=false] [name=…] Dump mantle section/plate under dump folder
packBenchmark Bukkit [pack=overworld] [radius=2048] [gui=false] Pack benchmark
upgrade Bukkit [version=latest] Data version upgrade helper
mca Bukkit <world folder> Scan MCA region files
delete-chunk dc Bukkit [radius=0] Delete nearby chunk blocks (regen testing)
network ip Both List network interfaces
regen rg Bukkit (modded root) [radius=5] Delete and regenerate nearby chunks
goldenhash gold Bukkit (modded root) [world] [radius=8] [center-x=0] [center-z=0] [reset-mantle=true] [threads=8] [deep=false] Buffer golden hash capture/verify

Modded developer group currently implements only sentry and network/ip.


Platform gap summary

Feature Bukkit Modded
Root permission node iris.all (code) Gamemaster / all levels
World lifecycle create, load, unload, remove world enable/disable/delete, create, mainworld
Seed print /iris seed
Object expand /iris object expand
Object WE / studio / convert yes help stubs only
Studio loot/profile/spawn/objects/scoreboard/importvanilla yes stubs or messages
Jigsaw Studio create/edit/autosave/export commands and GUI yes no; copy a Bukkit-authored Iris pack
Structure import/capture yes messages (run on Bukkit, copy pack)
Datapack Modrinth ingest/remove yes messages
Datapack status/install (dimension types) yes
regen / goldenhash under developer root
Pregen flags serial, gui, center string sync, gui, nocache, at x z
Tree feller permission iris.treefeller loader-specific node

  • 03 - Configuration.md
  • 02 - Getting Started.md
  • 06 - Worlds & Lifecycle.md
  • 07 - Pregeneration.md
  • 10 - Studio & VSCode Schemas.md
  • 21 - Jigsaw Structures.md
  • 25 - Pack Management.md
  • 28 - Integrations.md
  • 30 - Platform Differences.md
  • 32 - Determinism & Goldenhash.md