Hydro Lite Chunks is a lightweight Paper plugin designed to keep your server running smoothly by automatically unloading
inactive and unused chunks. By freeing memory and reducing chunk load overhead, it helps maintain stable TPS even during peak activity.
This plugin is built with safety in mind — respecting
WorldGuard regions, Essentials spawn, and Dynmap markers — ensuring that important areas remain untouched while performance is optimized.
⚡ Key Features
- Automatic Unloading – Frees unused chunks safely in the background.
- TPS-Aware Radius – Dynamically adjusts player chunk radius based on server performance.
- World Control – Whitelist or blacklist worlds where unloading is active.
- Hooks Included – Supports WorldGuard, Essentials, and Dynmap.
- Memory Friendly – Reduces RAM use by unloading chunks not in player range.
- Configurable & Safe – Full YAML configuration with chunk age protection to avoid thrashing.
- bStats Integration – Anonymous usage metrics for tracking performance.
Commands File:
Code (YAML):
Commands
/hydrolite – Shows plugin info and available commands.
/hydrolite status – Displays the latest unload stats and memory saved.
/hydrolite scan – Preview how many chunks would be unloaded.
/hydrolite run – Manually trigger an unload cycle.
/hydrolite reload – Reload the config.
/hydrolite config – Display a snapshot of the current configuration.
(
All commands require hydrolite.admin permission.
)
Permissions:
Code (YAML):
permissions:
hydrolite.admin:
description
: Access to
all HydroLiteChunks commands
default
: op
hydrolite.status:
description
: Allows checking HydroLiteChunks status
(/hydrolite status
)
default
: op
hydrolite.scan:
description
: Allows scanning unload candidates
(/hydrolite scan
)
default
: op
hydrolite.reload:
description
: Allows reloading HydroLiteChunks config
(/hydrolite reload
)
default
: op
hydrolite.run:
description
: Allows forcing an unload cycle
(/hydrolite run
)
default
: op
hydrolite.config:
description
: Allows viewing HydroLiteChunks config snapshot
(/hydrolite config
)
default
: op
Configuration
Hydro Lite Chunks provides a detailed configuration file with options for:
- Interval between unload cycles.
- Base and dynamic player radius.
- Minimum chunk age before unloading.
- Per-world control (whitelist/blacklist).
- Logging and optional broadcast messages.
- Safety caps for max chunks per cycle.
Actual Config Options:
Configuration File:
Code (YAML):
# ==================================================
# HydroLiteChunks Configuration
# Developer: TheMeanOneDevelopments
# Discord: https://discord.gg/SnjXeK7hVz
#
# This plugin optimizes server performance by
# intelligently unloading chunks with safety features.
#
# NOTE: All values can be tweaked live with /hydrolite reload
# ==================================================
# ==================================================
# Interval Settings
# ==================================================
# How often HydroLiteChunks should run a cleanup cycle.
# Measured in TICKS (20 ticks = 1 second).
# Default: 600 (30 seconds).
unload-interval
: 600
# ==================================================
# Player Radius Settings
# ==================================================
# Base chunk radius to keep loaded around each player.
# Example: 6 = 6 chunks * 16 blocks = 96 blocks radius.
base-radius
: 6
# Dynamic scaling of radius based on server TPS.
dynamic-radius:
enabled
: true
# Enable/disable dynamic scaling.
high-tps-threshold
: 19.5
# If TPS is >= this, radius increases.
low-tps-threshold
: 16.0
# If TPS is <= this, radius decreases.
adjustment
: 2
# Number of chunks to add/remove.
# ==================================================
# Chunk Aging
# ==================================================
# Minimum age (in cycles) before a chunk can be unloaded.
# Prevents constant unloading/reloading of "hot" chunks.
# Example: If set to 3, chunk must survive 3 full scans
# before eligible for unload.
min-chunk-age
: 3
# ==================================================
# World Control
# ==================================================
worlds
:
# Mode can be:
# whitelist -> Only unload chunks in these worlds.
# blacklist -> Unload chunks in all worlds EXCEPT these.
mode
: whitelist
# List of worlds to include/exclude depending on mode.
list
:
- world
- world_nether
# - world_the_end
# ==================================================
# Logging and Broadcasting
# ==================================================
logging
:
# Log every unload to console.
log-unloads
: true
# Broadcast unload results to ALL players.
broadcast-unloads
: false
# Message format when broadcasting (uses placeholders):
# {count} = number of chunks unloaded
# {memory} = approx MB freed
broadcast-format
:
"&b[HydroLiteChunks]&7 Unloaded &e{count}&7 chunks (~{memory} MB)!"
# ==================================================
# Safety Features
# ==================================================
safety
:
# Maximum chunks that can be unloaded per cycle.
# Prevents lag spikes if thousands of chunks are loaded.
max-unload-per-cycle
: 500
# Pause/suspend aggressive unloads if TPS is too low.
tps-aware-interval
: true
tps-threshold
: 15.0
# ==================================================
# Hooks
# ==================================================
hooks
:
# WorldGuard support:
# Skip unloading chunks if inside a protected region.
worldguard
: false
# Set to true if using
# Essentials support:
# Skip unloading the spawn chunk.
essentials-spawn
: false
# Set to true if using
# Dynmap support:
# Marks unloaded chunks on Dynmap using markers.
dynmap
: false
# Set to true if using
# ==================================================
# Metrics
# ==================================================
# Enable bStats metrics (anonymous usage statistics).
metrics
: true
Version Compatibility
- Tested on Paper 1.21.x
- Soft-depend integrations: WorldGuard, Dynmap, Essentials (Can add more if requested. I added these as they are all very commonly used.)
Why HydroLiteChunks?
Many servers suffer from lag caused by large numbers of inactive chunks staying loaded. HydroLiteChunks provides a
safe, configurable, and plugin-friendly way to unload them automatically.
It’s designed for administrators who want
reliable performance gains without sacrificing stability.
All Support will be provided in the Discord ONLY.
# bStats
![[IMG]](//proxy.spigotmc.org/747cdfb4b5a2b9fadbf641e0b8272fd702c4383c/68747470733a2f2f6273746174732e6f72672f7369676e6174757265732f62756b6b69742f487964726f4368756e6b4c6974652e737667)