Server Settings

Server settings

Every setting on the server side, in both spellings.

• Mod -- config/chunksmith/config.json, key in camelCase
• Plugin -- plugins/Chunksmith/config.yml, key in kebab-case

Set any of them in-game with /cs set <camelCaseName> <value> (the command uses the mod spelling on both platforms). A change applies immediately and rewrites the file.

Settings marked mod only do not exist on the plugin, and the reason is on Plugin vs mod -- it is never an oversight.

---

General

Setting	config.yml	Default	Notes
language	language	en	Falls back to en for anything not shipped. An unknown code is refused rather than silently becoming English.
continueOnRestart	continue-on-restart	false	Resume an unfinished task when the server comes back up.
forceLoadExistingChunks	force-load-existing-chunks	false	Re-visit chunks that already exist instead of skipping them. Slower; see How to.
silent	silent	false	Suppress progress broadcasts.
updateInterval	update-interval	1	Seconds between progress messages.

Throttling -- how hard Chunksmith is allowed to push

Pregeneration competes with the game for the server tick. These decide who wins.

Setting	config.yml	Default	Range	Notes
ioThrottle	io-throttle	true		The master switch for the throttle.
throttleTargetMspt	throttle-target-mspt	150.0	54.0 - 1000.0	Target tick time. Chunksmith backs off above it. 54 is a hair over vanilla's 50 ms tick.
throttleTickBudgetMillis	throttle-tick-budget-millis	25	5 - 500	Milliseconds per tick Chunksmith may spend.
throttlePlayerReserveMillis	throttle-player-reserve-millis	20	0 - 200	Milliseconds held back for players, never given to pregen.
throttleCeilingMillis	throttle-ceiling-millis	150	60 - 2000	Hard upper bound on a single tick's pregen work.
throttleMaxChunkMillis	throttle-max-chunk-millis	750	100 - 60000	A single chunk taking longer than this is treated as pathological.
throttleMaxQueuedWrites	throttle-max-queued-writes	800	50 - 1000000	Backpressure: pause generating when this many writes are queued.
throttleMaxAddedChunks	throttle-max-added-chunks	0	0, or 1000 - 5000000	0 = no limit.
throttleMaxHeapPercent	throttle-max-heap-percent	85	50 - 99	Pause when heap use passes this.
dispatchMaxConcurrent	dispatch-max-concurrent	derived from CPU count	1 - 4096	Chunks generated at once.
autoPauseOnOverload	auto-pause-on-overload	true		Pause automatically when the server is struggling.
autoPauseGraceSeconds	auto-pause-grace-seconds	120	10 - 3600	How long to wait before auto-pausing.

Settle -- mod only

Holds a freshly generated chunk in memory briefly so other mods that build on new land get a chance to see it. Dropping a chunk the instant it is generated silently breaks them.

Setting	Default	Range	Notes
pregenSettle	true		Off is for a pure terrain pregen with nothing else listening.
pregenSettleDelayTicks	40	up to 600	How long a chunk is held.
pregenSettleRadius	7	up to 16
pregenSettleMaxHeld	256	16 - 1000000	Cap on chunks held at once.

These four do not exist on the plugin, and /cs settle is hidden there rather than answering with a value it cannot honour.

World-enter pregen -- mod only, single-player

Pre-generates a single-player world on entry, behind a progress screen, before handing you control. Full page: World-enter pregen.

MC 26+ on Fabric and NeoForge. A dedicated server has no world-entry moment, so these keys are accepted and ignored there, and the plugin does not have them at all.

Setting	Default	Range	What it does
worldEnterPregen	true		On by default. Off means worlds open the way they always did.
worldEnterPregenRadius	4096	128 - 32768	How far out to generate, in blocks.

A world that finishes is never pre-generated again -- the completion is recorded beside the world data. Leaving early with Enter World Now records nothing, so that world simply continues next time; raising the radius asks for more and starts it again.

LOD

Setting	config.yml	Default	Notes
lodEnabled	lod-enabled	auto	auto / true / false. auto turns LOD on when a renderer is present.
lodDhOverride	--	false	Mod only. Force the Distant Horizons path even when detection says otherwise.
throttleMaxLodQueue	throttle-max-lod-queue	512	16 - 100000. Backpressure on the LOD write queue.
lodIndexBudgetMb	lod-index-budget-mb	2048	The one below.
lodBackchannelPort	lod-backchannel-port	0	0 derives game port + 1.
lodBackchannelBindAddress	lod-backchannel-bind-address	empty	Empty follows the game's bind.
lodBackchannelHost	lod-backchannel-host	empty	Empty lets each client use the address it connected to.

---

lodIndexBudgetMb -- read this one if your players use large render distances

Default 2048 MB. 0 means no limit. (new in 3.16.0; before that it was the same 2 GB, compiled in and not changeable.)

This is the ceiling on how much LOD a server will offer a client in one answer. Chunksmith lists the regions in range nearest-first and stops once it has named 2 GB of them.

The budget does not scale with the client's render distance, so it binds at the same distance every time. That is the thing to understand about it:

Distant Horizons radius	Regions in range	Roughly	Fits in 2 GB?
4096	~289	~1.5 GB	Yes -- never caps
8192	~800	~4.1 GB	No -- caps at ~395 regions

At radius 8192 with the default, terrain past that ring never arrives for a player who is standing still. Travelling does bring new terrain in, because the list is measured from the player -- but a player at their base is not travelling, and for them the far half of what they asked to draw simply is not there.

So: if your players run large render distances, raise this or set it to 0.

/cs set lodIndexBudgetMb 8192      # enough for radius 8192
/cs set lodIndexBudgetMb 0         # no limit; serve whatever is in range

It is a bandwidth control, not a safety limit. Nothing on the server needs it: the index message has its own separate cap on region count, the backchannel serves over HTTP at the client's own pace, and the in-band fallback sends fixed 24 KB slices four per tick rather than a total. Setting it to 0 does not put the server at risk; it puts more data on your transfer bill, and more on the player's disk.

It is also, by design, the only limit on how much LOD a client stores. There is no client-side disk cap -- the server admin sets the ceiling. At the default a client accumulates about 2 GB per dimension per server. At 0 and radius 8192, about 4 GB.

When it binds, the log now says so honestly -- once per player per ten minutes, naming which cap stopped the list and whether travelling will help. Before 3.16.0 it claimed travel would fix it in every case, including the case where it cannot.

The backchannel: port, bind address, and advertised host

Three separate questions, three separate keys. All of them rebind and re-advertise to connected players immediately -- no restart.

lodBackchannelPort -- which port to listen on. 0 derives game port + 1, which is right on a machine you control and wrong on a managed host that hands out a fixed set of ports. Set it to a port your host actually gave you.

lodBackchannelBindAddress -- which interface to listen on. Empty means "whatever the game bound". If your host sets server-ip to 127.0.0.1, which is normal behind a proxy, the backchannel lands on loopback where no player can reach it -- and the only symptom is everyone quietly falling back to the slow in-band channel. Set 0.0.0.0 to listen everywhere.

lodBackchannelHost -- what to tell clients. Empty means each client reuses the address it connected to, which is usually the best possible answer: it demonstrably reaches your server from where that player is sitting. It is wrong in one shape -- when the backchannel lives at a different address from the game port. Then name it here.

Binding to 0.0.0.0 does not remove the need for the third one. The socket then listens everywhere, and the client still has to be told where to look.

Hostnames with an underscore (myserver_minecraft.example.com) are accepted. They are not legal in a strict hostname, but DNS allows them and real hosts use them, so Chunksmith takes the name and resolves it for you rather than refusing it. The log says when it has done so. Before 3.17.0 such a name was rejected outright -- the key silently reset to empty and LOD downloads failed with no fallback (mod_support #26).

Set either address key to none to clear it.