Biome Cleaner

Removes micro-biomes from your world.

Загрузки: 7K
Подписчики: 54
Обновлён: 10 мая 2026 г.
Лицензия: MIT

Опубликован 13 января 2026 г.

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
Size-range trimming -- Cap a biome's maximum size by trimming oversized regions down instead of replacing them outright (e.g. keep stony shores small)
Group-aware preservation -- Mark a group as "preferred" so its members merge into each other before flipping to outside biomes; mid-sized regions with no in-group neighbour are kept rather than replaced (e.g. preserve inland lakes, but still clean up tiny ocean puddles)
Boundary requirements -- Force a biome to be cleaned up if its boundary doesn't touch the right neighbours, regardless of size (e.g. wipe out inland beaches with no ocean or river next to them)
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. Accepts a single number (minimum size) or a `[min, max]` pair
`intraGroupPreference`	Mark a group as "preferred" so its members merge into each other before flipping to a different group, and preserve mid-sized regions that have no in-group neighbour
`requiredBoundaryGroups`	Require a biome's boundary to touch at least one of the listed groups -- regions that don't are cleaned up regardless of size

`sizeThresholdOverrides`

Each entry takes either a single number or a [min, max] pair:

"biome": N -- regions smaller than N quarts get replaced. No upper bound. (Same behaviour as before 1.1.0.)
"biome": [min, max] -- regions smaller than min get replaced; regions between min and max are kept; regions larger than max get trimmed down to a max-sized patch instead of replaced outright.

The default config uses [32, 64] for minecraft:stony_shore so that very small stony shore patches are still cleaned up entirely, but oversized stony shore expanses get shrunk down rather than wiped from the world.

When the same biome is named both directly (e.g. "minecraft:stony_shore") and through a group it belongs to (e.g. "beaches"), the more specific biome-id entry wins.

`intraGroupPreference`

Each entry maps a group name to a preference object:

mode: "preferred" -- regions of biomes in this group prefer to merge into other members of the same group when possible.
fallbackOutOfGroupBelowSize: N -- if no in-group neighbour is available, regions smaller than N quarts fall through and get a normal out-of-group replacement; regions at or above N are preserved instead of being flipped.

The default config marks oceans as preferred with a fallback size of 8. The practical effect:

A tiny ocean puddle in the middle of land (under 8 quarts) gets cleaned up to the surrounding land like normal -- no other ocean nearby to merge into, and small enough that we don't want to keep it.
A larger inland lake (8 quarts or more) is preserved instead of being replaced, even though it has no other ocean as a neighbour.
A coastal sliver of ocean sitting next to a different ocean variant (e.g. a small ocean patch next to frozen_ocean) merges into that neighbouring variant rather than turning into beach. So a region that's half ocean and half frozen ocean cleans up into a single ocean variant.

`requiredBoundaryGroups`

Each entry maps a biome (or group) to a list of groups that must appear on its boundary. If none of the required groups are present, the region is cleaned up regardless of size.

The default config requires beaches to touch oceans or rivers. Without this rule, an unusually large beach patch with nothing but forest around it would be kept simply because it's big enough to clear the size threshold. With the rule, any inland beach with no water nearby is cleaned up no matter how big it is.

Default Advanced Config

{
  "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,
    "minecraft:stony_shore": [32, 64],
    "rivers": 48
  },
  "intraGroupPreference": {
    "oceans": {
      "mode": "preferred",
      "fallbackOutOfGroupBelowSize": 8
    }
  },
  "requiredBoundaryGroups": {
    "beaches": ["oceans", "rivers"]
  }
}

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

Note on these numbers: Every figure in this section was captured against version 1.0.3. Version 1.1.0 ships a rewritten cleaner algorithm and three new config features, and has no known performance regressions, but the numbers below have not yet been re-measured against the new build. A refreshed run will land in a future release.

TL;DR: You won't notice it. On 1.0.3, the mod added about 2.4% CPU overhead at the default settings and ran entirely on its own background threads -- the server tick rate was unaffected. We expect 1.1.0 to land in the same ballpark.

These numbers are from the default sizeThreshold = 512. Lower thresholds cost less, higher thresholds cost a bit more -- but all stayed 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.

Detailed Benchmark Data

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.