Iris/docs/04 - Commands & Permissions.md

04 - Commands & Permissions

Iris exposes one root command: /iris (aliases /ir, /irs). Bukkit uses VolmLib Director (named parameters, optional key=value). 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.

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
• Example: /iris pregen start 5000 world=world center=me gui=true serial=false
• Contextual params (world, dimension, location) often resolve from the sender’s 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] (type aliases dimension,pack). Modded: <name> [pack=overworld] [seed=1337]	Create Iris world/dimension
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
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

---

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
close	x	Both	—	Close studio and discard world
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.

---

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]	Cached validation status

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 structure at player
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
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

---

Related

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