FAWEReplace

Introduction

FAWEReplace is a high-performance Paper plugin designed for large-scale Minecraft world cleanup tasks. Built on FastAsyncWorldEdit (FAWE)'s asynchronous capabilities, it efficiently handles bulk block replacement and entity removal operations.

Prerequisite

FastAsyncWorldEdit (FAWE)

Tutorial

Commands

• start/continue cleaning: /frl start
• start new cleaning task: /frl start --fresh
• stop cleaning: /frl stop
• check cleaning progress: /frl status
• tutorial: /frl help
• reload: /frl reload

Configuration

language: zh_CN # or en_US

# Target region coordinates
world: "world"
target:
  start:
    x: -1000
    z: -1000
    # y: -64  # Optional: auto use full world height if not set
  end:
    x: 1000
    z: 1000
    # y: 320 # Optional: auto use full world height if not set

# Auto-start on plugin enable
# !Warning: Recommend keeping false, manual start is safer
confirm: false

# Performance Configuration

# Number of parallel processing threads
# !Important: Choose value based on your use case
#
# Server with players online:
#   - 2GB RAM: 1-2 threads
#   - 4GB RAM: 2-3 threads
#   - 5GB RAM: 2-3 threads (recommended: 2)
#   - 8GB+ RAM: 3-5 threads
#
# Offline processing (maximum performance):
#   - 4GB RAM: 4-6 threads
#   - 5GB RAM: 6-8 threads
#   - 8GB RAM: 8-12 threads
#   - 16GB+ RAM: 12-16 threads
#
parallel: 2

# Region/Tile size
# Size of region each worker thread processes
# Larger values = fewer tiles but longer processing time per tile
region:
  x: 512
  z: 512
  # y: 256  # Optional: auto-calculated if not set

# Processing Modes
# Tiling mode
# When enabled, splits large regions into smaller tiles for parallel processing
tiling:
  enabled: true

# Fast mode
# Uses FAWE's fast asynchronous processing
fast-mode: true

# Progress log frequency
# Output progress log every N tiles processed
# Tip:
#   - Online server: 50-100 (more detailed progress)
#   - Offline processing: 100-200 (reduce log overhead)
progress-log-every: 100

# Safety Options
# Skip ungenerated chunks
# Highly recommended to keep enabled
#
# Features:
#   - Only process chunks visited by players
#   - Avoid generating new empty chunks
#   - Prevent heightmap warnings
#   - Improve performance
#
skip-ungenerated-chunks: true

# Auto-repair chunk heightmaps
# Recommended to prevent black chunks in MCA Selector
#
# Features:
#   - Auto-refresh heightmap after block replacement
#   - Prevent black chunks in MCA Selector
#   - Minimal performance impact
auto-fix-heightmap: true

# Memory Protection
# Prevent OutOfMemoryError crashes
memory-protection:
  # Enable automatic memory monitoring
  # Recommended: Must enable for online servers
  # Offline processing: Can disable for max speed (with crash risk)
  enabled: true
  
  # Minimum free memory percentage (0.0-1.0)
  # Pause processing when free memory falls below this
  #
  # !Recommended values:
  #   Online server: 0.20-0.25 (20-25%, safer)
  #   Offline processing: 0.10-0.15 (10-15%, aggressive)
  min-free-memory-percent: 0.20
  
  # Wait time when memory is low (milliseconds)
  # !Recommended values:
  #   Online server: 5000 (5 seconds)
  #   Offline processing: 2000-3000 (2-3 seconds)
  wait-on-low-memory-ms: 5000
  
  # Maximum retries when memory is consistently low
  # Set to -1 for unlimited retries (not recommended)
  max-memory-retries: 10

Performance Throttling

Add delays between operations to reduce server load

!IMPORTANT:

Server with players: Use moderate delays

Offline processing: Set all to 0 for maximum speed (10-40% faster!)

performance:

Delay between chunk processing batches (milliseconds)

Recommended values:

Offline: 0 (最大速度 / max speed)

Online-light: 50-100

Online-heavy: 100-200

delay-between-batches-ms: 100

Delay between individual chunk operations (milliseconds)

Recommended values:

Offline: 0 (max speed)

Online: 10-20

delay-between-chunks-ms: 20

Force garbage collection frequency

Execute GC every N chunks processed

Recommended values:

Offline: 0 (let JVM auto-manage, fastest)

Memory issues: 100-200

!Note: 0 is usually best, JVM's GC optimization is more efficient

gc-every-chunks: 50

Resume/Checkpoint System

Save progress to resume after interruption

resume:

Enable resume/checkpoint

Recommended: keep enabled

enabled: true

Progress file name

Saved in plugin data folder

file: "progress.yml"

Save frequency

Save progress every N tiles processed

Recommended values:

- Online server: 25 (save more frequently)

- Offline processing: 100 (reduce I/O overhead)

save-every: 25

Block Replacement Rules

Define which block types to replace

IMPORTANT WARNING:

X Do NOT replace common building blocks (like STONE, DIRT, WOOD, etc.)

O Only replace blocks you want to clean (containers, machines, etc.)

Format:

- origin:

target: <Target block, usually AIR>

Full material list:

https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html

blocks:

• origin: SHULKER_BOX target: AIR
• origin: YELLOW_SHULKER_BOX target: AIR
• origin: GREEN_SHULKER_BOX target: AIR
• origin: PURPLE_SHULKER_BOX target: AIR
• origin: DISPENSER target: AIR
• origin: ORANGE_SHULKER_BOX target: AIR
• origin: FURNACE target: AIR
• origin: BLACK_SHULKER_BOX target: AIR
• origin: LIME_SHULKER_BOX target: AIR
• origin: HOPPER target: AIR
• origin: GRAY_SHULKER_BOX target: AIR
• origin: RED_SHULKER_BOX target: AIR
• origin: LIGHT_BLUE_SHULKER_BOX target: AIR
• origin: BREWING_STAND target: AIR
• origin: BROWN_SHULKER_BOX target: AIR
• origin: BARREL target: AIR
• origin: CAMPFIRE target: AIR
• origin: LIGHT_GRAY_SHULKER_BOX target: AIR
• origin: TRAPPED_CHEST target: AIR
• origin: DROPPER target: AIR
• origin: WHITE_SHULKER_BOX target: AIR
• origin: CHEST target: AIR
• origin: SOUL_CAMPFIRE target: AIR
• origin: BLUE_SHULKER_BOX target: AIR
• origin: MAGENTA_SHULKER_BOX target: AIR
• origin: PINK_SHULKER_BOX target: AIR
• origin: CYAN_SHULKER_BOX target: AIR
• origin: BLAST_FURNACE target: AIR
• origin: SMOKER target: AIR

Entity Cleanup

Remove specified entity types

!Note:

- Use carefully! May remove players' items, mobs, etc.

- Recommend testing on a test server first

entities:

Enable entity cleanup

enabled: false

Full list:

https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/EntityType.html

types: [] # Examples: # - ITEM # Remove dropped items # - ZOMBIE # Remove zombies # - ARMOR_STAND # Remove armor stands