Biome Cleaner

Cleans up the messy, scattered biome patches that Minecraft's terrain generation creates. Small biome regions are merged into their larger neighbors, giving your world cleaner boundaries and a more natural feel -- without changing terrain shape, structures, or gameplay.

The mod works server-side only (no client installation needed) and runs entirely on its own background threads, so your server's tick rate is unaffected.

Before & After

With the default settings, those tiny 1-chunk patches of plains in the middle of a forest, or awkward slivers of beach where they don't belong, get absorbed into the surrounding biome. The result is smoother, more coherent biome regions while keeping the overall world layout intact.

Features

• Configurable threshold -- Set how small a biome region must be before it gets merged (default: 512 quarts)
• Biome protection -- Mark specific biomes (like rare ones) to never be replaced
• Replacement control -- Prevent certain biomes (like oceans) from spreading into other areas
• Biome groups -- Define groups for bulk configuration (e.g., all ocean variants)
• Per-group thresholds -- Use different size thresholds for different biome types
• Background preprocessing -- Chunks are cleaned ahead of the player, so there's no lag when new terrain loads
• Server-side only -- No client installation required

Adding to an Existing World

The mod works best on new worlds, but you can add it to an existing world with one caveat: biome seams can appear at the border of your already-explored area.

This happens because the mod only affects chunks as they're generated for the first time. If a small biome patch straddles the boundary between chunks you've already explored and chunks you haven't, the old side keeps its original biomes while the new side gets cleaned up -- creating a visible mismatch where the two halves meet.

These seams only occur right at the edge of your previously explored territory and only where a small biome patch happens to cross that boundary. The rest of your new terrain will be fully cleaned as expected. Once you move past the border area, everything is seamless.

Starting a new world? No issues at all -- every chunk is cleaned as it generates.

Configuration

Main Config

Located at config/biomecleaner/common.json:

Option Default Description enabled true Master toggle for biome cleaning sizeThreshold 512 Minimum region size in quarts (4x4 block areas). Regions smaller than this get merged. Range: 1--1024 neverReplace ["rare"] Biomes/groups that are never replaced, even if small neverUseAsReplacement ["oceans", "rivers"] Biomes/groups that never replace other biomes allowIntraGroupReplacement ["oceans"] Groups where biomes can replace others within the same group preprocessingEnabled true Enable background preprocessing (recommended). When enabled, chunks are cleaned before the player reaches them preprocessingThreadCount 0 Number of worker threads for preprocessing. 0 = automatic (based on your CPU) cacheMemoryMB 128 Memory budget for the preprocessing cache in MB. Increase if you have RAM to spare and want longer lead times

What is a quart? Minecraft stores biomes at 1/4 block resolution (one biome value per 4x4x4 block cube). A "quart" is one of these 4x4 biome cells. The default threshold of 512 quarts corresponds to roughly a 90x90 block area -- small patches below this size get cleaned up.

Advanced Config

Located at config/biomecleaner/advanced.json:

Field Description groups Define named groups of biomes for use in the main config sizeThresholdOverrides Override the size threshold for specific biomes or groups { "groups": { "rare": ["minecraft:mushroom_fields", "minecraft:stony_peaks"], "oceans": [ "minecraft:ocean", "minecraft:warm_ocean", "minecraft:lukewarm_ocean", "minecraft:cold_ocean", "minecraft:frozen_ocean", "minecraft:deep_ocean", "minecraft:deep_lukewarm_ocean", "minecraft:deep_cold_ocean", "minecraft:deep_frozen_ocean" ], "rivers": ["minecraft:river", "minecraft:frozen_river"], "beaches": ["minecraft:beach", "minecraft:snowy_beach", "minecraft:stony_shore"] }, "sizeThresholdOverrides": { "beaches": 32, "rivers": 48 } }

Recommended JVM Arguments

The mod's worker threads are designed to run at a lower priority than the main server thread, so they automatically yield CPU time when the server needs it. By default, Java ignores thread priority settings. Adding these two JVM flags to your server startup script enables them:

-XX:+UseThreadPriorities -XX:ThreadPriorityPolicy=1

This is optional but recommended -- it ensures the mod's background work never competes with tick processing, even under heavy load.

Performance

TL;DR: You won't notice it. The mod adds about 2.4% CPU overhead at the default settings and runs entirely on its own background threads -- your server tick rate stays the same.

These numbers are from the default sizeThreshold = 512. Lower thresholds cost less, higher thresholds cost a bit more -- but all stay under 3% CPU.

What Result CPU overhead 2.4% total, all on dedicated worker threads Impact on vanilla server code None measurable (within 0.1% of vanilla) Chunk processing time 92.7% of chunks cleaned in under 1 ms Cache hit rate 100% -- chunks are ready before you get there Average lead time 6.1 seconds ahead of the player GC pauses All under 16 ms (tick budget is 50 ms)

The mod predicts where the player is heading and pre-cleans chunks in the background well before they're needed. In benchmarks, 79% of chunks were ready more than 5 seconds before the player arrived.

Threshold Comparison

Higher thresholds clean more aggressively (merging larger patches) at a small additional cost:

256 512 (default) 1024 CPU overhead 2.0% 2.4% 2.9% Chunks cleaned < 1 ms 97.8% 92.7% 87.1% Chunks receiving replacements 2.7% 4.1% 5.9% Cache hit rate 100% 100% 100% Lead time 6.1 s 6.1 s 5.9 s

All thresholds run on dedicated background threads with no impact on vanilla server performance.

Test Setup

Parameter Value Minecraft 1.21.11 Runs 10 per configuration Travel distance 5,000 blocks View/Sim distance 10 Background threads 16 Server memory 6 GB

CPU Breakdown

Metric Vanilla 256 512 1024 Mod CPU work -- 2.0% 2.4% 2.9% Non-mod delta vs vanilla -- -0.4% -0.1% -1.0%

Non-mod code stays within 1% of vanilla across all thresholds, confirming the mod does not steal CPU time from the server.

Chunk Processing

Percentile 256 512 1024 Median (p50) 0.060 ms 0.047 ms 0.038 ms p95 0.745 ms 1.117 ms 1.948 ms p99 1.356 ms 1.975 ms 3.331 ms Max 9.97 ms 11.19 ms 24.94 ms

Mean processing time at the default threshold is 0.249 ms per chunk.

Garbage Collection

Metric Vanilla 256 512 1024 Avg total pause/run 228 ms 282 ms 284 ms 286 ms Avg pause duration 7.46 ms 8.85 ms 8.93 ms 9.07 ms Max single pause 12.3 ms 23.9 ms 15.5 ms 15.4 ms

GC impact is nearly identical across thresholds. All pauses remain well under the 50 ms tick budget.

Cache & Warming

Metric 256 512 1024 Chunks processed/run ~8,500 ~8,500 ~8,400 Cache hit rate 100.0% 100.0% 100.0% Mean lead time 6.1 s 6.1 s 5.9 s Warmed 5+ seconds early 76.9% 78.9% 75.6% Chunks with replacements 2.7% 4.1% 5.9%