Minecraft Worldedit Ops

---
name: minecraft-worldedit-ops
description: "Operate WorldEdit safely for Minecraft 26.x and 1.21.x selections, region edits, masks, schematics, brushes, terrain shaping, and rollback. Use for command-driven world editing, not plugin development or general server administration."
---

# Minecraft WorldEdit Operations Skill

## Scope and Positioning

This skill is for **operating** WorldEdit on live or staging servers.  
It is not for writing plugin code that integrates with WorldEdit APIs.

### Routing Boundaries
- `Use when`: the task is command-driven in-world editing with WorldEdit (selections, transforms, schematics, terrain shaping, rollback-safe workflows).
- `Do not use when`: the task is Java plugin implementation (`minecraft-plugin-dev`).
- `Do not use when`: the task is broad server deployment/tuning/proxy/backup strategy (`minecraft-server-admin`).
- `Do not use when`: the task is EssentialsX command/economy/moderation workflows (`minecraft-essentials-ops`).

---

## Platform and Setup Notes

WorldEdit is commonly used on:
- Paper/Purpur/Folia servers via WorldEdit plugin
- Fabric/NeoForge via mod variants

Operational best practice:
1. Apply large edits on staging or during maintenance windows.
2. Keep automatic backups before major region operations.
3. Use conservative selection + mask constraints before destructive commands.

Compatibility note: WorldEdit 7.4.x has builds for 1.21.x, 26.1, and 26.2.
Select the build listed for the exact server version and stage-test it before
using it on production worlds.

## References

- Read `references/safety-checklists.md` before large pastes, destructive replacements, or any edit where rollback discipline matters more than speed.

---

## Core Selection Workflow

### Selection modes

Most common cuboid flow:

```text
//wand
//pos1
//pos2
//size
```

Fast alternatives:

```text
//hpos1
//hpos2
//chunk
//expand 20 up
//expand 20 down
```

Selection safety checks:
- always run `//size` before `//set` or `//replace`
- before `//paste`, preview its destination with `//paste -n` using the same
  placement flags planned for the real paste (for example, `//paste -n -a` or
  `//paste -n -o`), then run `//size` and inspect the selected destination
- use `//distr` to preview block composition before replacement

---

## Region Operations

### High-frequency operations

```text
//set stone
//replace stone andesite
//replace water air
//walls stone_bricks
//overlay grass_block
//smooth 3
```

### Masks and filtered replacements

Use masks to constrain scope:

```text
//gmask #existing
//replace grass_block dirt
//gmask
```

Single-command mask approach:

```text
//replace stone,andesite,diorite,granite smooth_stone
//replace ##leaves air
```

Pattern examples:

```text
//set 70%stone,20%andesite,10%cobblestone
//replace dirt 60%coarse_dirt,40%podzol
```

---

## Clipboard and Schematic Workflows

### Clipboard basics

```text
//copy
//rotate 90
//flip east
//paste -a
```

Use `-a` when you want to skip air blocks during paste.

### Schematic workflow

```text
//schem save spawn-hub-v3
//schem list
//schem load spawn-hub-v3
//paste -n -a
//size
//paste -a
```

Operational guidance:
- use versioned names (`arena-mid-2026-03-27`)
- keep read-only archive copies for rollback
- `-n` changes the selection to the planned destination without placing blocks;
  keep `-a`, `-o`, and any other placement flags aligned between preview and
  actual paste
- pair each major paste with an immediate backup checkpoint

---

## Brushes and Terraforming

### Practical brush setup

```text
//brush sphere stone 4
//brush smooth 3
//brush raise sphere 2
//brush lower sphere 2
//mask #existing
```

Reset brush:

```text
//none
```

Terraforming safety:
- start with small radius (3-5) and iterate
- keep masks active to avoid damaging structures
- save periodic schematic or backup checkpoints; `//undo` reverts an edit

---

## Undo, History, and Safety

### History commands

```text
//undo
//undo 5
//redo
```

Safety policy for production operations:
1. Create backup checkpoint.
2. Perform one logical batch of edits.
3. Validate with visual walkthrough.
4. Continue or `//undo` immediately.

Do not chain many destructive edits without intermediate verification.
Run `//clearhistory` only after the edit is accepted, a backup or schematic
checkpoint exists, and the rollback window is closed.

---

## Practical Runbooks

## Runbook: Spawn Editing Refresh

- Select spawn zone and run `//size`.
- Snapshot:

```text
//copy
//schem save spawn-before-refresh
```

- Apply constrained replacements and overlays.
- Smooth terrain edges:

```text
//smooth 2
```

- Validate spawn safety (voids, lighting, navigation).
- Reselect the edited area if needed, then copy its final state before saving:

```text
//copy
//schem save spawn-after-refresh
```

## Runbook: Arena Reset Between Matches

- Keep a pristine arena schematic with its original placement recorded.
- After each match:

```text
//schem load arena-pristine
//paste -n -o
//size
//paste -o
```

- Inspect the selected destination after the preview, then paste with the same
  `-o` origin flag. Include air to remove player-added blocks; `-a` would leave
  those blocks behind. Entity and biome restoration require intentional
  copy/paste flags and separate verification.
- Validate command blocks/signals associated with arena logic.

## Runbook: Block Cleanup (Lag and Visual Noise)

Typical cleanup targets:
- dropped scaffolding builds
- accidental fluid spread
- excessive leaf/log leftovers

Example cleanup sequence:

```text
//replace lava air
//replace water air
//replace ##leaves air
```

Always scope with selection/mask first to avoid map-wide accidental edits.

## Runbook: Path Shaping and Terrain Blend

- Select corridor/path footprint.
- Build mixed surface:

```text
//set 50%dirt_path,30%coarse_dirt,20%gravel
```

- Blend edges with low-radius smooth brush.
- Add retaining borders (`stone_bricks`, `andesite`) where elevation changes.

---

## Operational Guardrails

- Never run broad replacements from global/world scope.
- Confirm selection size before every destructive command.
- Keep a restoration schematic for each major build zone.
- Coordinate edits with other staff to avoid overlapping operations.
- Validate WorldEdit limits/permissions by role to prevent accidental mass edits.

---

## References

- https://worldedit.enginehub.org/en/latest/
- https://worldedit.enginehub.org/en/latest/usage/
- https://worldedit.enginehub.org/en/latest/usage/regions/selections/
- https://worldedit.enginehub.org/en/latest/usage/general/masks/
- https://worldedit.enginehub.org/en/latest/usage/clipboard/
- https://worldedit.enginehub.org/en/latest/usage/tools/brushes/