ChunkCleaners

A performance focused, highly optimized, chunk cleaner plugin for Paper 1.21+ that allows players to remove all blocks and entities within a chunk. This is a well sought after feature for Factions and Survival servers.

Support for FactionsUUID, MassiveCore Factions, WorldGuard, GriefPrevention and CoreProtect! Key features

Placeable chunk-cleaner items (configurable types: small, medium, large).
Top-down cleaning (surface first) to avoid underground holes while working.
Multi-chunk support (1x1, 2x2, 4x4, etc.) with size-aware throughput scaling.
TPS-adaptive throttling — reduces workload automatically when server TPS drops.
Holograms and ActionBars!
Integrations:
    WorldGuard (region build flag checks)
    GriefPrevention (claim checks)
    Factions
    CoreProtect (batch-per-chunk summaries, throttled enqueue + periodic flush)
Persistence with autosave and per-task progress saving (reduces lost progress after a restart).

Commands

Primary command: /chunkcleaners (alias /cc)

Player commands

/chunkcleaners give <player> <type> [amount] — give a cleaner item to a player (permission: chunkcleaners.give).
/chunkcleaners list — show active cleaner count or a brief list.
/chunkcleaners reload — reload plugin config (admin permission required).

Admin subcommands (permission: chunkcleaners.admin)

/chunkcleaners admin save — force-save all active tasks to disk.
/chunkcleaners admin savetask <uuid> — save progress for a single task immediately.
/chunkcleaners admin list — list all active tasks with percent progress.
/chunkcleaners admin status <uuid> — show detailed status (ETA, chunk pointer, progress).

Holograms and Visuals

Configurable under hologram.*:

hologram.lines — a list of lines (preferred) for multi-line holograms (supports placeholders).
hologram.text — fallback single-line text with \n support.
hologram.offset — vertical offset above the placed block. Placeholders available: {remaining}, {progress}, {coords}, {type}, {amount}, {player}.

Performance tuning & options

All tuning options live under performance.* in config.yml.

Important knobs

performance.max_chunks_per_interval — baseline number of chunks prepared per scheduler run.
performance.y_batch_size — baseline vertical layers processed per chunk job.
performance.ticks_per_chunk_interval — scheduling interval (ticks).
performance.size_scale_enabled — whether larger cleaners automatically do more work.
performance.size_scale_multiplier — multiplier used with cleaner size to compute scale factor.
performance.size_scale_cap — upper cap for scale factor (safe default = 8).
performance.aggressive_interval_divisor — (advanced) allow smaller schedule interval for large cleaners.
performance.tps_threshold & performance.tps_smoothing — used to detect low TPS and smoothly reduce workload.
performance.eta_window_seconds — window for the moving-average ETA estimator.

CoreProtect safety

coreprotect.log_chunk_summary (recommended) — log one summary entry per finished chunk instead of each block.
coreprotect.flush_interval_ticks & coreprotect.max_entries_per_flush — control the CoreProtect logging throughput.
coreprotect.queue_max_size — prevents memory blowup by bounding queued entries.

Persistence

persistence-file — path to saved active tasks (default data/active-cleaners.yml).
persistence.autosave_enabled & persistence.autosave_interval_seconds — periodic autosave settings.
The plugin also saves per-task progress when a chunk completes.

Recommended production tuning

Start with defaults in config.yml.
Test on a new world with multiple cleaner types.
Monitor server TPS and tick times. If TPS remains stable (≥ ~19), gradually:
    increase size_scale_multiplier or size_scale_cap, or
    increase max_chunks_per_interval and y_batch_size.
Keep CoreProtect batch logging enabled and monitor CoreProtect performance/IO.
Use persistence.autosave_interval_seconds (default 60s) to balance resilience vs disk writes.

Safety and integration behavior

If protection integrations are enabled, the plugin will refuse to edit a chunk on behalf of an offline player (conservative default).
WorldGuard/GriefPrevention/Factions checks are performed via reflection due to missing API's in recent versions.

Development & testing

Test the plugin out!
    /chunkcleaners give <player> small 1
    Player places the item — hologram and actionbar should appear.
    Use /chunkcleaners admin list and /chunkcleaners admin status <uuid> for debugging.

Configuration

# ChunkCleaners
# Version 1.0.0 by d15c07d
#
# Supported placeholders (used in messages/holograms/actionbar):
#   {remaining}  - seconds remaining (ETA)
#   {progress}   - percent complete 0-100
#   {coords}     - world:chunkX,chunkZ (or world:x,z)
#   {type}       - cleaner type key
#   {amount}     - numeric amount
#   {player}     - player name
#   {id}         - task UUID
#   {count}      - number of active cleaners
# ----------------------------------------------------------------
types:
  small:
    display-name: "<green>Small Cleaner</green>"
    description: "Clears a 1x1 chunk area quickly.\nTip: place on flat ground."
    size: 1
    block: END_PORTAL_FRAME
    duration: 10

  medium:
    display-name: "<yellow>Medium Cleaner</yellow>"
    description: "Clears a 2x2 chunk area over time."
    size: 2
    block: END_PORTAL_FRAME
    duration: 30

  large:
    display-name: "<red>Large Cleaner</red>"
    description: "Clears a 4x4 chunk area. Use with caution."
    size: 4
    block: END_PORTAL_FRAME
    duration: 90

# ----------------------------------------------------------------
# Hologram and visuals
# - You can configure either a single string (hologram.text) or multiple
#   lines (hologram.lines) — lines are preferred for multi-line holograms.
# - hologram.offset moves the hologram vertically above the placed block.
# - line spacing and other advanced behavior can be added later.
# ----------------------------------------------------------------
hologram:
  enabled: true
  # Vertical offset above the placed block (in blocks)
  offset: 0.6
  lines:
    - "<gold>Cleaning: <yellow>{remaining}s</yellow>"
    - "<gray>{progress}% complete</gray>"
  # Fallback single-line text if 'lines' is not defined or empty.
  text: "<gold>Cleaning: <yellow>{remaining}s</yellow>"

----------------------------------------------------------------

Actionbar display shown periodically to the player while cleaner runs.

Use {remaining} and {progress} placeholders.

----------------------------------------------------------------

actionbar: enabled: true message: "&aChunk Cleaner &7- &e{remaining}s &8[&e{progress}%&8]"

----------------------------------------------------------------

Messages (general, admin and main). All are editable for localization.

Use MiniMessage or legacy '&' codes. Several placeholders supported.

----------------------------------------------------------------

messages:

General (non-admin) messages

no_permission: "You don't have permission to do that." invalid_type: "That chunk cleaner type doesn't exist." gave_cleaner: "Gave {amount}x {type} to {player}." placed_denied_same_chunk: "There is already an active chunk cleaner in this chunk." placed_denied_protected: "You cannot place a chunk cleaner in a protected region." start_cleaning: "Started cleaning chunk area {coords} (type {type})." cancel_no_nearby: "You are not near an active chunk cleaner you own." cancel_success: "Cancelled the chunk cleaner at {coords}." reload_success: "Reloaded config and plugin data." list_header: "Active Chunk Cleaners (page {page}/{max})" list_entry: "{index}. {owner} ({coords}) {type} age={age}s" cannot_place_in_same_chunk: "A chunk cleaner is already active in this chunk." cannot_place_in_protected: "Cannot place chunk cleaners in protected regions."

Admin command messages (used by /chunkcleaners admin ...)

admin: help_header: "ChunkCleaners Admin Commands" help_lines: - "/chunkcleaners admin save - Save all active cleaners to disk" - "/chunkcleaners admin savetask - Save progress for a specific task" - "/chunkcleaners admin list - List active tasks" - "/chunkcleaners admin status - Show detailed status for a task" save_success: "Saved all active cleaners to disk." save_fail: "Failed to save: {error}" savetask_success: "Saved progress for task {id}" savetask_no_task: "No active task with that UUID." savetask_invalid_uuid: "Invalid UUID: {id}" help_no_permission: "You don't have permission to use admin commands." list_header: "Active Chunk Cleaners: ({count})" list_empty: "No active chunk cleaners." status_not_found: "No active task with that UUID." status_world_unloaded: "World not loaded: {world}" status_progress_line: "Progress: {percent}% ({processed}/{total} levels)" status_eta_line: "ETA (est): {seconds}s" status_pointers: "Chunk index: {idx} Y pointer: {y}"

Main command messages and usage (used by /chunkcleaners and alias /cc)

main: usage_header: "ChunkCleaners commands:" usage_lines: - "/chunkcleaners give [amount] - Give a cleaner to a player" - "/chunkcleaners list - List active cleaners" - "/chunkcleaners reload - Reload plugin config" - "/chunkcleaners admin _{- Admin utilities (requires permission)" reload_success: "Configuration reloaded." reload_fail: "Failed to reload: {error}" give_no_permission: "You don't have permission to give cleaners." give_success: "Gave {amount}x {type} to {player}."}

----------------------------------------------------------------

Behaviour toggles & persistence

----------------------------------------------------------------

prevent_same_chunk: true # if true, plugin prevents two cleaners in same chunk save_on_shutdown: true # save active cleaners to persistence-file on shutdown persistence-file: data/active-cleaners.yml

persistence: autosave_enabled: true autosave_interval_seconds: 60 # save every N seconds to reduce lost progress

Hot reload (watch config.yml and reload automatically)

hot_reload: enabled: true file: config.yml poll_interval_ms: 1000

----------------------------------------------------------------

Integrations: enable only the plugins you run on the server

- WorldGuard: region/build flag checks

- GriefPrevention: claim checks

- Factions: FactionsUUID or MassiveCore Factions detection

- CoreProtect: batch-per-chunk logging

----------------------------------------------------------------

integrations: worldguard: true griefprevention: true factions: true coreprotect: true

----------------------------------------------------------------

Performance tuning and adaptive throttling

Notes:

- Start conservative. Increase slowly while monitoring TPS.

- size-aware scaling makes larger cleaners do more work per tick.

----------------------------------------------------------------

performance:

Baseline knobs

max_chunks_per_interval: 1 # baseline number of chunks to attempt per scheduler interval y_batch_size: 1 # baseline number of vertical layers per chunk job ticks_per_chunk_interval: 2 # scheduler repeat interval (ticks)

Adaptive throttling

tps_threshold: 18.0 tps_min_chunks_per_interval: 1 tps_min_y_batch_size: 1 tps_smoothing: 0.75 tps_check_interval_ticks: 1

ETA smoothing window in seconds used to compute a smoothed processing rate

eta_window_seconds: 8

Size-aware scaling (make larger cleaners process proportionally more work)

size_scale_enabled: true

scaleFactor = min(size_scale_cap, size * size_scale_multiplier)

size_scale_multiplier: 1 size_scale_cap: 8

If >1, scheduler interval can be divided for larger cleaners (use with caution)

aggressive_interval_divisor: 1

----------------------------------------------------------------

CoreProtect logging (batch-per-chunk) — avoids overwhelming CoreProtect

- log_chunk_summary: send single summary per completed chunk (recommended)

- flush_interval_ticks / max_entries_per_flush control throughput

----------------------------------------------------------------

coreprotect: enabled: true log_chunk_summary: true flush_interval_ticks: 20 max_entries_per_flush: 50 queue_max_size: 5000 queue_trim_to: 4000

legacy fallback (not used when log_chunk_summary=true)

log_every_n: 10

----------------------------------------------------------------

Safety & operational notes

----------------------------------------------------------------

- If you enable integrations, the plugin will refuse to edit protected chunks on behalf of offline owners.

This prevents accidental modification of other players' claims/regions.

- Monitor server TPS when running large cleaners. The plugin adjusts its throughput based on TPS.

- If you use CoreProtect logging in high-scale environments, ensure CoreProtect and disk IO can handle the load.

- For quick recovery, persistence.autosave_interval_seconds default = 60s. You may lower for more frequent saves

at the cost of increased disk writes.

Support

    In need of support for this plugin, or need support for another plugin added? Contact me on Discord @d15co7d!