How To

How to

Walkthroughs for the things Chunksmith is actually used for. Commands are on Commands; settings are on Server settings.

---

Pregenerate an area

The normal case: generate a 5000-block radius around spawn.

/cs world world
/cs spawn
/cs shape circle
/cs radius 5000
/cs selection      # check it before committing
/cs start

Then /cs progress to watch it, /cs pause and /cs continue as needed.

On the pattern. concentric (the default) works outward from the centre, so the area nearest spawn is finished first and is usable while the rest runs. region visits whole region files at a time, which is friendlier to disk and faster overall but leaves the middle unfinished for longer. On a live server, prefer concentric; for an offline bulk run, region.

It will not be instant. Chunksmith deliberately leaves the server playable -- see throttling below.

Keep the server playable while it runs

The defaults are already tuned for a live server: pregen yields to the game, holds back 20 ms per tick for players, and pauses itself when the server struggles.

If it is still too intrusive:

/cs set throttleTickBudgetMillis 15
/cs set throttlePlayerReserveMillis 30

If the server is empty and you want it to go faster:

/cs set throttleTickBudgetMillis 60
/cs set throttleTargetMspt 300

autoPauseOnOverload stays on either way -- it is the backstop that keeps a bad setting from taking the server down.

If it pauses constantly, the cause is usually memory rather than CPU. Check throttleMaxHeapPercent (default 85) and give the server more heap; a pregen touches a lot of chunks and a cramped heap spends its time in GC.

Re-generate chunks that already exist

By default Chunksmith skips chunks that are already generated -- it reads the status out of the region file without loading them, which is why a re-run over finished ground is quick.

To force it to visit them anyway:

/cs set forceLoadExistingChunks true

Use it when an existing area needs re-processing (a new LOD store, say), and turn it back off afterwards. It is much slower, because every chunk is loaded rather than skipped.

Trim a world

/cs trim removes chunks instead of generating them. Select an area the same way, then trim -- optionally filtered by how long chunks have been inhabited:

/cs world world
/cs center 0 0
/cs shape square
/cs radius 10000
/cs inhabited 0
/cs trim

/cs inhabited <ticks> keeps chunks players have actually spent time in. Back the world up first. Trim deletes.

Get LOD working -- single player

1. Install Chunksmith and a renderer -- Distant Horizons or voxy.
2. Pregenerate as above. lodEnabled is auto, so LOD data is written when a renderer is present.
3. The terrain reaches the renderer as it is generated.

If nothing appears, /cslod status says whether a renderer was detected at all.

Get LOD working -- multiplayer

The server generates the LOD store; clients download it over a backchannel, a small HTTP listener on a second port.

On the server: run Chunksmith (mod or plugin, both serve LOD from 3.15.0) and pregenerate. The startup log names the backchannel port.

On the client: Chunksmith plus a renderer. Join. The server advertises the port, the client fetches what is in range and hands it to the renderer.

Open the backchannel port. It defaults to game port + 1 -- so a server on 25565 needs 25566 open too. That is the single most common reason multiplayer LOD does not work.

Multiplayer LOD is not arriving

Work down this list; each step rules out one thing.

1. Is the backchannel bound? /cs status on the server. If it says it could not bind, the port is taken or not permitted -- pick another:

/cs set lodBackchannelPort 25570

2. Is it listening somewhere reachable? If the startup line says listening on /127.0.0.1:..., your host has set server-ip to loopback and no player can reach it:

/cs set lodBackchannelBindAddress 0.0.0.0

3. Can the client actually reach it? /cslod status on the client. If the port was advertised but unreachable, the client says so and falls back. Check the firewall, and check that your host has actually opened that port -- many hosts open only the game port.

4. Is the client being told the right address? By default the client reuses the address it connected to. If your backchannel lives somewhere else -- a proxy in front, or a host that maps extra ports onto a different IP -- name it:

/cs set lodBackchannelHost lod.example.net

5. On the plugin, remember there is no fallback. The mod degrades to streaming LOD down the game connection when the backchannel fails. The plugin does not, so a blocked port means nothing arrives at all. See Plugin vs mod.

Players see terrain nearby but nothing far away

This is usually the index budget rather than a fault.

Check the server log for a line about the LOD index being capped. From 3.16.0 that line names which cap stopped the list and whether travelling will help.

If it is the byte budget, the default is 2048 MB and it does not scale with render distance. A Distant Horizons radius of 8192 needs about 4 GB and will be cut to roughly half. Raise it:

/cs set lodIndexBudgetMb 8192
/cs set lodIndexBudgetMb 0        # no limit at all

Full explanation, and the numbers per radius, on Server settings.

A player reset their renderer and terrain will not come back

Chunksmith remembers what it has already given the renderer, so it does not re-send. If the player emptied voxy's storage or Distant Horizons' database, that record now describes data that is gone.

On the client:

/cslod set reinject-on-join true

Join once, then set it back to false.

Make a change stick without restarting

Every setting has a command, every command writes the file, and the LOD address settings rebind and re-advertise to connected players on the spot. /cs reload re-reads the file if you edited it by hand.

The one thing to know: an existing config file is never rewritten to add new keys. After an upgrade, new settings are absent from your file and their defaults apply. Run the setting's /cs set once to write it out, or delete the file and let it regenerate.