Shinoyuki-BetterAutoSave

BetterAutoSave

简体中文 | English

> 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

Download: Modrinth · GitHub Releases

> Project status: actively developed and in a fast pre-1.0 iteration phase, with frequent updates (including releases coordinated with BetterBackup). The core async save has been validated in production for a long time and is safe by default; async chunk loading is a newer, opt-in feature and is off by default. Watch Releases / Modrinth for updates

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), and global data such as villages and raids (vanilla SavedData) where a single large file hits the disk.

BAS makes the main thread do only the one thing that must happen in place — taking an independent snapshot of the data to be saved. Serialization and disk IO are handed to background threads. Because the background works on copies, it never interferes with the main thread, which lets go immediately after the snapshot. Chunks, entities and saved data all go through this pipeline. When the server is struggling BAS automatically slows down, but forces full speed as the next autosave cycle approaches so a backlog can never build up.

Requirements and installation

Both loaders are maintained from the same source. Server-side only on both; clients do not need to install it.

• Forge 1.20.1: Forge 47.3.22 or newer (47.3 / 47.4 lines both work), Java 17 or newer
• NeoForge 1.21.1: NeoForge 21.1 line, Java 21 or newer

Download the jar matching your loader from Modrinth or Releases and drop it into the server's mods/ folder:

• For Forge, use the -all jar (named like shinoyuki_betterautosave-<version>-all.jar; it bundles MixinExtras and other dependencies). The plain thin jar crashes on load for missing dependencies.
• For NeoForge, use shinoyuki_betterautosave-neoforge-<version>.jar.

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, and the final save goes through the vanilla synchronous path.
• 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).
• If a background write fails it retries automatically and never pretends it succeeded: chunks and saved data fall back to the vanilla synchronous write once retries are exhausted; entities have no coordinate recovery queue and are already evicted from memory by vanilla, so an exhausted retry logs an ERROR and drops that chunk's latest entity increment — the same outcome as vanilla here (vanilla entity saving likewise has no retry and no synchronous fallback; BAS actually retries a few more times first).

Beyond that, the Forge build also fixes three vanilla paths that silently lose data (player data read failure, truncating writes for advancements and stats, and level.dat having only a single backup). Those fixes are on by default — see the configuration reference.

Common configuration

| 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 mods that write a lot of vanilla SavedData | | compat.eventCompatMode | PARTIAL | Event compatibility level; leave it alone unless you know you need it |

The Forge build has 43 settings, the NeoForge build 26. Every setting, why each default is what it is, and the recommended rollout path are documented in CONFIGURATION.en.md, covering player data protection, level.dat integrity, async chunk loading, Prometheus monitoring and working with backup tools.

Feature matrix across the two builds

The two builds are not identical. Some gaps exist because NeoForge fixed the problem upstream, so the corresponding option is unnecessary there; others are Forge-first and not yet ported symmetrically.