Configuration

BetterMultiThreaded is configured in config/canvas-server.yml. The file is created on first start and carries a comment above every option. This page covers the sections that control sharding, region merging and splitting, the scheduler and the per-core savings.

sharded-regions

The main switch and the options that apply to every sharded region.

sharded-regions:
   enabled: true
   shard-size-chunks: 8
   world-mode-all-regions: true
   worker-threads: 0
   zones-force: true
   parallel-tracker: true
   shard-connections: true
   shard-packets: true
   shard-entity-schedulers: true
   parallel-activation: true
   parallel-ticket-purge: true
   keep-shards-on-split: true
   debug-log: false

Key	Default	Meaning
enabled	true	Master switch for sharded ticking. Set to false and run /bmt reload to turn it off without a restart.
shard-size-chunks	8	Default edge length of a shard in chunks. Rounded up to a power of two, 8 to 64. Every world and zone can override it at runtime.
world-mode-all-regions	true	When a whole world is sharded, also shard its regions that have no player in them. false = only regions with at least one player.
worker-threads	0	Shard worker threads shared by all sharded regions. The region thread joins as an extra worker. 0 = CPU cores ÷ 4, between 2 and 8.
zones-force	true	Force sharding for any region that has a player inside an enabled zone.
parallel-tracker	true	Run the entity tracker (visibility and movement packets) of a sharded region in parallel.
shard-connections	true	Run each player’s own movement and physics tick inside the shard tasks. false = on the region thread.
shard-packets	true	Handle the shard-safe head of every player’s packet queue inside the shard task that ticks the player.
shard-entity-schedulers	true	Run plugin entity schedulers inside the shard task that owns the entity.
parallel-activation	true	Run the entity-activation-range pass as parallel tasks.
parallel-ticket-purge	true	Run the chunk ticket expiry pass as a parallel task.
keep-shards-on-split	true	When a sharded region splits, hand its shards to the region that inherits most of the land instead of rebuilding them.
debug-log	false	Log activation, deactivation and per-tick phase timings. Spammy.

auto

When a region is sharded and un-sharded on its own.

sharded-regions:
   auto:
      enabled: true
      min-players: 40
      activate-mspt: 22.0
      force-players: 80
      deactivate-below-players: 30
      hysteresis-seconds: 20

Key	Default	Meaning
enabled	true	Automatically shard a region that grew too large and un-shard it when it shrinks again.
min-players	40	A region needs at least this many players before the MSPT rule is considered.
activate-mspt	22.0	Shard when the region’s 5-second average MSPT is at or above this while it has min-players players.
force-players	80	Shard regardless of MSPT once the region has this many players.
deactivate-below-players	30	Un-shard when the player count stays below this. MSPT is not used here: sharding lowers it by design.
hysteresis-seconds	20	A condition must hold this long before the mode flips.

scan

Thresholds for /bmt shard scan.

sharded-regions:
   scan:
      mspt: 20.0
      min-players: 20
      force-players: 80
      zone-prefix: "scan"

Key	Default	Meaning
mspt	20.0	A region counts as lagging when its 5-second or 1-minute MSPT is at or above this, and it has min-players players.
min-players	20	Minimum players a region needs before its MSPT is considered.
force-players	80	A region with this many players is converted regardless of MSPT.
zone-prefix	"scan"	Name prefix of the zones the scan creates. A config file from an older build keeps its old value until you change it.

grouping

Hot and cold planning. A shard with a player, a measurable tick cost or many entities is a task of its own; the remaining cold shards are grouped into larger squares that one worker ticks together. The effect is small pieces in the crowd and big pieces in empty land.

sharded-regions:
   grouping:
      enabled: true
      cold-group-size-chunks: 32
      hot-shard-micros: 100
      hot-shard-entities: 24

Key	Default	Meaning
enabled	true	Group cold shards into larger tasks.
cold-group-size-chunks	32	Edge length of a cold group in chunks. Rounded to a power of two, at least the shard size.
hot-shard-micros	100	A shard whose last tick took at least this many microseconds is hot.
hot-shard-entities	24	A shard with at least this many ticking entities is hot.

regioniser

How regions merge and split. Both switches take effect at the next merge or split, without a restart.

regioniser:
   keep-largest-region-on-merge: true
   incremental-split: true
   slow-operation-log-millis: 10.0

Key	Default	Meaning
keep-largest-region-on-merge	true	When regions merge, the largest one survives and the smaller ones are moved into it. false = Folia’s behaviour.
incremental-split	true	When a region falls apart, the largest connected part keeps the region and only the parts that broke off are moved. false = Folia’s full rebuild.
slow-operation-log-millis	10.0	Log every merge or split that held the regioniser lock for at least this long. 0 = log all of them, negative = never.

region-scheduler

The work-stealing options live under affinity-scheduler and are read at startup.

region-scheduler:
   affinity-scheduler:
      steal-threshold-millis: 3
      waiting-threads-steal: true
      foreign-tasks-min-slack-millis: 1.0
      foreign-tasks-budget-millis: 2.0

Key	Default	Meaning
steal-threshold-millis	3	How long a thread may delay a scheduled task before other threads are allowed to steal it.
waiting-threads-steal	true	Threads that are idle, or parked until their own region’s next tick, take over a region another thread cannot start on time.
foreign-tasks-min-slack-millis	1.0	A waiting thread only runs other regions’ intermediate tasks while at least this much time is left before its own tick.
foreign-tasks-budget-millis	2.0	Longest uninterrupted run of another region’s intermediate tasks before the thread looks at the next region.

dab

Dynamic Activation of Brain. The further a mob is from the nearest player, the less often its AI runs.

dab:
   enabled: true
   start-distance: 12
   max-tick-freq: 20
   activation-dist-mod: 8
   blacklisted-entities: []

Key	Default	Meaning
enabled	true	Throttle the AI of mobs that are far from every player.
start-distance	12	Blocks from the nearest player from which the AI is throttled.
max-tick-freq	20	Longest allowed interval between AI ticks. 20 = once per second.
activation-dist-mod	8	Shift applied to the squared distance to get the interval. With 8: 32 blocks → every 4 ticks, 64 blocks → every 16.
blacklisted-entities	[]	Entity type keys whose AI is never throttled, for example minecraft:villager.

async-mob-spawning

async-mob-spawning:
   enabled: true
   threads: 1

Key	Default	Meaning
enabled	true	Count the region’s entities for natural spawning on a background thread. Only active when entities.spawning.per-player-mob-spawns is true in paper-world-defaults.yml.
threads	1	Background threads shared by all regions for the recount. One is enough for most servers.

tick-optimizations

tick-optimizations:
   random-tick-section-mask-refresh-ticks: 20
   equipment-change-cache: true

Key	Default	Meaning
random-tick-section-mask-refresh-ticks	20	How often each chunk recomputes which sections hold a randomly ticking block. A newly planted crop gets its first random tick at most this many ticks late. 0 = recompute every tick (vanilla behaviour, no gain).
equipment-change-cache	true	Run the full equipment comparison only when a slot’s item, count or components changed.

Other files

File	Purpose
config/canvas-server.yml	Everything on this page.
config/canvas-bolge-zones.json	The zones and world levels you created. Managed by the commands; reload it with /bmt folia reload.
config/paper-global.yml	Paper and Folia settings, including threaded-regions.scheduler.

Next: FAQ.