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: <Bukkit Material name>
#     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