BetterAutoSave

Make server autosaves stutter-free ~
Parts of this mod's code were generated by Claude Opus 4.8 / Claude Fable 5. If you run into any issue, please open an issue

What problem does this mod solve

A vanilla Minecraft server autosaves every 5 minutes. During that save, the main thread has to serialize every modified chunk and write it to disk — and the whole server is frozen while it happens. On an empty server you will not notice, but on a server with many mods and players this pause is routinely 200 ms to several seconds, and every player lags at once.

Besides the periodic autosave, several other moments stutter the same way:

• Players teleporting, or large numbers of chunks being unloaded (a chunk must be saved before it leaves memory)
• Entity-dense areas during a save (large farms / mob grinders) — saving entities one by one adds extra stalls
• Villages, raids and some mod data (e.g. MTR train data) being written to disk — a single large file can stall 50-200 ms

BAS moves the whole saving process to background threads. The main thread only does the one thing that must happen in place — taking a snapshot of the data to be saved. Serialization and disk IO are handed to the background. The stutter essentially disappears.

Requirements

• Minecraft 1.20.1
• Forge 47.3.22 or newer (47.3 / 47.4 lines both work)
• Java 17 or newer
• Server-side only, clients do not need to install it

Installation

Drop shinoyuki_betterautosave-0.11.0.jar into the server's mods/ folder and start. After the first launch the config file is generated at:

config/Shinoyuki-Optimize/shinoyuki_betterautosave/common.toml

The defaults work out of the box; most servers do not need to change anything.

Will it lose world data?

No. BAS is designed on one premise: it must never be less safe than vanilla:

• On shutdown it waits for every pending save to hit the disk before letting the server exit.
• The final save at shutdown goes through the vanilla synchronous path, exactly as if BAS were not installed.
• BAS never "holds saves for later" — a chunk enters background processing the moment it should be saved. There is no "nothing saved for minutes, crash loses it all" window (some similar mods have this problem, see compatibility below).
• If a background write fails it retries automatically; when retries are exhausted it falls back to the vanilla synchronous write instead of pretending it succeeded.

How it works (optional reading)

Vanilla saves stutter because two heavy jobs sit on the main thread: serializing world data into the save format, and writing the serialized data to disk.

BAS makes the main thread do only the snapshot — copying the chunk's current blocks, light, block entities and so on into an independent copy. This step is fast because it is just a copy, no format conversion. Once copied, the main thread immediately goes back to running the game while background threads take the copy through serialization and disk IO.

Because the background threads operate on copies, they never interfere with the main thread; after the snapshot the main thread lets go without waiting for the write. Chunks, entities and saved data all go through this pipeline.

When the server is struggling, BAS automatically slows down (fewer snapshots per tick once TPS drops below a threshold), but forces full speed as the next autosave cycle approaches so a backlog can never build up.

Configuration

The config file is config/Shinoyuki-Optimize/shinoyuki_betterautosave/common.toml. Common entries:

| Key | Default | Description |
|---|---|---|
| general.enabled | true | Master switch; off means vanilla behavior, as if not installed |
| throttle.chunksPerTickBase | 4 | Max chunks snapshotted by the main thread per game tick |
| throttle.adaptiveEnabled | true | Slow down automatically when the server struggles; keep it on |
| workers.chunkWorkerThreads | 2 | Background threads for chunks |
| workers.entityWorkerThreads | 2 | Background threads for entities |
| workers.savedDataWorkerThreads | 1 | Background threads for saved data; raise to 2 with heavy data mods (e.g. MTR) |
| compat.eventCompatMode | PARTIAL | Compatibility level, see below |

The remaining entries (retry counts, shutdown timeout, monitoring switches, etc.) are documented by comments inside the config file.

Compatibility level: eventCompatMode

A few mods listen to the "chunk save" event. This switch controls how complete the data BAS hands them is:

• PARTIAL (default, recommended): best performance, 99% of mods cannot tell the difference.
• FULL: 100% identical to vanilla, at half the performance. Only switch here when a specific mod demonstrably errors because it cannot read chunk block data.
• DISABLED: never dispatch the event at all; cheapest, provided you are sure no mod listens to it.

When unsure, stay on PARTIAL.

In-game commands (OP required)

| Command | Effect |
|---|---|
| /betterautosave status | One-line current status |
| /betterautosave metrics | One-line metrics summary |
| /betterautosave debug | Full diagnostics: queue depths, per-stage timings, counters |
| /betterautosave flush | Synchronously flush every pending save to disk right now |
| /betterautosave drain-unload | Manually wait for all pending chunks to land before shutdown |
| /betterautosave hottest-chunks [count] | List the slowest-saving chunks (default 10, max 50) to locate hotspots |
| /betterautosave force-async | Force one background save pass over all chunks in the current dimension (diagnostic) |

Monitoring (v0.9, optional)

v0.9 added two diagnostic tools so you can see save performance without an external profiler.

The hottest-chunks command lists the slowest chunks by save time, highest first:

/betterautosave hottest-chunks 20

High-cost chunks usually sit where block entities are dense — large automated farms, mod shop panels, complex redstone. Once you know the exact position you can optimize it directly.

The Prometheus metrics endpoint (off by default) serves a /metrics page on the configured port. Hooked into Grafana it gives you long-term save-performance trends, far more convenient than repeatedly running /betterautosave debug. Enable it in the config:

[prometheus]
enabled = true
port = 9450

Security note: the port listens on 0.0.0.0 by default. On public servers (cloud / VPS), firewall port 9450 or set bindAddress to 127.0.0.1 to allow local connections only. The metrics contain no player privacy, but they do expose the server's activity patterns.

Mod conflicts

• Smooth Chunk Save: pick one. Both modify the chunk-unload save path. Compared to it, BAS does not delay disk writes (no data-loss window), does not cancel vanilla periodic autosaves and does not swallow exceptions.
• C2ME-Forge: takes over the same save path as BAS; installing both means double processing, pick one. It is no longer maintained, so the overlap should be rare in practice.
• Lithium ports (Radium / Canary), Starlight Forge: compatible.
• Other mods that also touch chunk saving: they may occasionally make BAS's takeover fail, in which case BAS automatically falls back to vanilla handling — data safety is unaffected, you just lose a bit of the performance gain.

The full compatibility matrix is in ROADMAP (Chinese).

Quick recovery if something goes wrong

All three options keep world data intact:

1. Disable temporarily: set general.enabled to false in the config, restart or /reload. The mod stays installed but all logic is skipped — pure vanilla.
2. Uninstall completely: move the jar out of mods/ and restart. World data remains protected by vanilla saving; uninstalling loses nothing.
3. Tune instead of removing: if you suspect a performance setting, adjust chunksPerTickBase (range 1-64) or switch eventCompatMode to FULL first — no need to uninstall.

Building / development

./gradlew build         # compile + run tests
./gradlew runServer     # start a dev server

Technical deep dive, ecosystem research, full compatibility matrix and the version roadmap are in ROADMAP.md (Chinese).

License

See the LICENSE file.