How sharding works

Regions and shards

Folia defines a region as a set of chunks that touch each other, and ticks each region on one thread. While players stay close together their chunks keep touching, so the region cannot be split, and no Folia setting can cut it in two.

BetterMultiThreaded leaves the region alone and parallelises what is inside it. A sharded region’s chunks are grouped into square shards, 8 to 64 chunks on a side, and a pool of worker threads ticks those shards at the same time. The region thread joins in as one more worker.

While a worker ticks a shard it holds the 3×3 block of shards around it, so nothing two workers do can reach the same chunk. 8 chunks (128 blocks) is the smallest shard: that is the longest reach of any vanilla mechanic (a lightning rod), so neighbouring shards always cover it.

Smaller shards give more parallelism for a crowd packed into a small area, at the cost of more traffic across shard borders. Larger shards suit a town that is spread out.

Automatic mode

Automatic mode watches every region and shards the ones that need it. With the defaults a region is sharded when:

• it has at least min-players (40) players and its 5-second average MSPT is at or above activate-mspt (22), or
• it has at least force-players (80) players, whatever its MSPT.

It is un-sharded when its player count stays below deactivate-below-players (30). MSPT is not used for switching off, because sharding lowers MSPT by design. A condition has to hold for hysteresis-seconds (20) before the mode flips.

All five values are in the sharded-regions.auto section. See Configuration.

Doing it by hand

Four tools shard a region or a world without waiting for the automatic rule. Each manual split becomes an entry you can switch off, re-plan or delete later.

The split button in /tps

/tps lists every region. Under each one a line shows its mode: Folia (single thread), or SHARDED followed by why it is sharded (auto, zone, world or manual), the shard size, the shard count and the live speed-up. Buttons follow on the same line.

Button	What it does
[Split ⚡]	Looks at the region’s chunks and where its players stand, picks a shard size, and saves the result as a permanent zone. On a region that is already sharded it re-plans for the current player spread.
[Undo]	Shown on a sharded region. Turns its manual split off: the zone is disabled and a live override is cleared.
[Menu]	Opens /bmt folia.

The buttons run /bmt foliafix, so the line only appears for operators and for players with bettermultithreaded.command.foliafix or bettermultithreaded.command.folia. The console gets the matching command as text instead.

World levels

/bmt foliaworld shards every region of a world at once.

Level	Shard size
0	Plain Folia: no sharding
1	64 chunks
2	32 chunks
3	16 chunks
4	8 chunks

Use it for a world that is busy as a whole, such as the Nether during an event, and set it back to 0 afterwards.

The selection wand

/bmt foliawand gives you a wand. Left-click the first corner and right-click the second. A menu opens where you choose automatic, a number of shards or a shard size for the selected area. Use it to prepare a tournament arena before the players arrive.

Region scan

/bmt shard scan checks the region you are standing in and, if it is lagging, turns it into a permanent sharded zone. /bmt shard scan all does the same for every region on the server, and adding report shows the result without changing anything. A region counts as lagging when its 5-second or 1-minute MSPT is at or above scan.mspt (20) with at least scan.min-players (20) players, or when it has scan.force-players (80) players.

Managing what you created

/bmt folia opens a menu that lists every zone, world level and live override in one place. From the console the same command takes list, disable, enable, delete, replan and panic.

Zones are stored in config/canvas-bolge-zones.json. A zone keeps applying when the region merges, splits or the server restarts, until you disable or delete it.

What runs inside the shards

Besides chunk and entity ticking, these parts of a sharded region’s tick run in parallel. All are on by default and each has its own switch in sharded-regions.

Part	Option
Entity tracker: visibility and movement packets	parallel-tracker
Player connection ticks: each player’s own movement and physics	shard-connections
The shard-safe head of each player’s packet queue: movement, digging, placing, container clicks	shard-packets
Plugin entity schedulers (Folia’s per-entity task API)	shard-entity-schedulers
The entity-activation-range pass	parallel-activation
Chunk ticket expiry	parallel-ticket-purge

Packets that can reach the whole region or server, such as commands, chat and respawns, are still handled on the region thread.

Steady TPS when players move

Every /warp, /rtp and portal trip makes Folia merge and split regions under a lock that other regions have to wait for. Two changes keep those moments from showing up as TPS drops.

• Incremental regioniser. When regions merge, the largest one survives and the smaller ones move into it. When a region falls apart, the largest part keeps the region and only the parts that broke off are moved. Folia rebuilds every piece.
• Work-stealing scheduler. A thread that is idle, or parked until its own region’s next tick, takes over a region another thread cannot start on time. This applies to the AFFINITY scheduler: set threaded-regions.scheduler to AFFINITY in config/paper-global.yml to use it.

The measurements are on Benchmarks.

Per-core savings

These do not depend on sharding and help at any player count.

DAB

Dynamic Activation of Brain, a port of Pufferfish’s DAB. The further a mob is from the nearest player, the less often its AI runs. Movement, physics and sensing still tick every tick. Mobs with a target, leashed mobs, mobs carrying a player and any types you blacklist are never throttled.

Async mob spawning

A port of Pufferfish’s mob spawning optimisation, adapted to region threading. Vanilla recounts every entity in the region on the tick thread before it spawns anything. Here the count runs on a background thread and the region reuses the latest finished result. Mobs are never spawned off-thread, only counted.

It is only active when entities.spawning.per-player-mob-spawns is true in paper-world-defaults.yml. A spawn tick is skipped while a recount is still running, so spawns are very slightly fewer.

Tick micro-optimisations

• Random-tick section mask — each chunk remembers which of its sections hold a randomly ticking block and only visits those.
• Equipment-change cache — the per-tick equipment comparison only runs in full when a slot’s item actually changed.

Per-hopper mode

Look at a hopper and run /hoppervanilla to make that one hopper behave exactly like vanilla: one item per transfer, checked every tick. /hopperperformance puts it back on the hopper-amount and hopper-check values from spigot.yml. The choice is saved on the hopper and survives restarts, so a redstone clock that depends on vanilla timing keeps working while the rest of the server uses your fast hopper settings.