Chronos Backups

^{The wonderful mod icon and banner were created by Mylèna Yarah Krijnen.}

Chronos Backups is a multi-loader, multi-version Minecraft backup utility. Saves only the most important parts of your world, keeping backups smaller.

Features

• Multi-version, multi-loader architecture (Fabric, NeoForge, Forge).
• Scheduled and manual backups via an in-game /chronos command with a configurable permission level.
• Backups are pruned and filtered to only include the most important parts of your world, keeping backups much smaller than traditional backups.
• Configurable file copy blacklist to exclude specific files and folders from the backup, prefilled with common server-related files and folders.

Commands

Command	Description
/chronos backup	Run a manual backup immediately.
/chronos cancel	Stop the backup currently in progress.
/chronos speedtest <seconds>	Run repeated backups for benchmarking (diagnostic. not for normal use).

The required permission level defaults to 4.

Limitations

Chronos prioritizes aged world data, chunks that do not yet count as "old enough" can be left out of a backup. If you enter a new chunk, change blocks or items, and a backup runs before that area is included, those changes may be missing from that backup (depending on configuration). That situation is seen as extremely rare and can only cause loss on restore, never duplication.

Supported versions

All currently supported versions are listed below. If a specific subversion does not have a modloader associated with it (eg 1.7.3-1.7.9), it may still appear as supported if the major version is supported.

Minecraft	Support	Loader(s)	Backup	Config	Notes
26.2.x	✅ Supported	Fabric + NeoForge	✅	🟠 File-only	-
26.1.x	✅ Supported	Fabric + NeoForge	✅	🟠 File-only	-
1.21.x	✅ Supported	Fabric + NeoForge	✅	🟠 File-only	-
1.20.x	✅ Supported	Forge + Fabric + NeoForge	✅	🟠 File-only	Forge 1.20.0-1.20.1. Fabric 1.20.x. NeoForge 1.20.2-1.20.6.
1.19.x	✅ Supported	Fabric + Forge	✅	🟠 File-only	-
1.18.x	✅ Supported	Fabric + Forge	✅	🟠 File-only	-
1.17.x	✅ Supported	Fabric + Forge	✅	🟠 File-only	-
1.16.x	✅ Supported	Fabric + Forge	✅	🟠 File-only	-
1.15.x	✅ Supported	Fabric + Forge	✅	🟠 File-only	-
1.14.x	✅ Supported	Fabric + Forge	✅	🟠 File-only	-
1.13.x	✅ Supported	Forge	✅	🟠 File-only	1
1.12.x	✅ Supported	Forge	✅	🟠 File-only	1
1.11.x	✅ Supported	Forge	✅	🟠 File-only	1
1.10.x	✅ Supported	Forge	✅	🟠 File-only	1
1.9.x	✅ Supported	Forge	✅	🟠 File-only	1
1.8.x	✅ Supported	Forge	✅	🟠 File-only	1
1.7.x	✅ Supported	Forge	✅	🟠 File-only	2, 1
1.6.x	❌ Unsupported	Forge	❌	🔴 None	1
1.5.x	❌ Unsupported	Forge	❌	🔴 None	1
1.4.x	❌ Unsupported	Forge	❌	🔴 None	1
1.3.x	❌ Unsupported	Forge	❌	🔴 None	1
1.2.x	❌ Unsupported	Forge	❌	🔴 None	-
Beta & Alpha	❌ Unsupported	Babric	❌	🔴 None	Beta & Alpha versions may be supported in the future, but the flagship Chronos feature (world pruning) will be unavailable.

Configuration

The mod's configuration is stored in the config/chronos.toml file. This file is automatically created when the mod is first run, and is located in the config folder of the mod's directory. For the forseeable future, there is no GUI configuration available. Config options include:

• backupFolderName: The name of the folder that will contain the backups.
• pruneChunks: Whether chunk pruning is enabled for backups.
• pruneTimeRequirementSeconds: Minimum playtime (in seconds) for a chunk to count toward world pruning.
• pruneMaxWorkerThreads: Maximum worker threads for pruning. 0 (or less) means "auto" (pruner picks a sensible default).
• scheduleBackups: Whether to run backups on a timer.
• backupIntervalSeconds: Seconds between automatic backup runs.
• maxStoredBackups: Maximum backups kept per world. After a successful backup, oldest backups are removed if the limit is exceeded. Recommended value: 5. Values lower than 3 can be used to save space, but risks serious data loss if a catastrophic error occurs. Values below 1 disable automatic removal.
• compressionMethod: Whether to compress the backups into a zip file or store it as an uncompressed folder. Accepts "zip" or "none".
• commandRequiredPermissionLevel: Permission level required to run /chronos.
• copyBlacklist: Folders and files to exclude from the backup.

This list may be out of date. To see the latest available configuration options and their descriptions, see ChronosTomlSpec.java.

Nightly releases

Github Actions automatically builds and uploads nightly releases to the GitHub Releases page. These are not the same as stable releases found on Modrinth, CurseForge or Github Releases, and should not be relied upon or assumed to be stable.

Development

Note

This repository is meant to compile with the build tool (for example ./gradlew buildAll). Editors are not guaranteed to work, so you may see persistent missing imports and other false errors in the IDE even when the command-line build succeeds. This might even result in ludicrous errors such as String cannot be resolved to a type. Treat the build output as the real check until further notice. Your IDE will complain. Sorry.

Chronos Backups is dedicated to making the development of this mod as easy as possible, on any OS, in any IDE, with simple automatic setups and tools for testing and building, but there are still some manual steps required.

Prerequisites

• Install JDK 25+ and set JAVA_HOME to it. Older variants use a Java 8, 17 or 21 toolchain via Gradle/Foojay automatically.
• Install Rustup and ensure cargo / rustup are on PATH, and install Rust nightly toolchain:

rustup toolchain install nightly

• Install Docker to run most tests. Follow your operating system specific installation instructions, ensuring the docker command is available in your environment.

Rust native library

Chronos Backups bundles a custom built native Rust pruning library, which in turn makes use of mca and na_nbt for maximum performance. This is automatically built and bundled with the mod during normal Gradle builds, or can be built manually through buildRust for verification. By default, due to platform constraints, local development builds compile and stage only the current host OS/arch native target. In GitHub Actions, Chronos builds rust-pruner on Linux, Windows and macOS runners, then merges those artifacts before buildAll, so the produced jars include all supported native platforms. This means that local builds:

• are intended for development on the current machine only, and should not be released through release channels, or even shared with other developers or users (to avoid confusion).
• cannot be used on a non-native platform unless you add extra targets or use merged CI artifacts.

Docker tests (testServers) require Docker to be installed and running. One command runs buildAll, cross-compiles linux-x86_64 rust-pruner in Docker via cargo-zigbuild (glibc 2.17 max, compatible with old dedicated-server images such as itzg/minecraft-server:java8), and tests every supported loader/version in Docker:

./gradlew testServers

linux-x86_64 natives are always built that way (including on Linux CI) so they load on older server distros.

Note

Rust builds are only produced for 64-bit systems. 32-bit architectures are not supported.

To benchmark pruning locally, place a world at core/native/rust-pruner/test/world/ (gitignored) and run:

cd core/native/rust-pruner
cargo +nightly run --release --features world-test --bin prune-world-test

It copies the world, prunes the snapshot, prints the results, and discards the backup.

Project structure

The project is organized as a small, version-agnostic core (scheduler + backup runner) plus loader/version-specific shells, with gradle.properties as the central place to edit mod metadata shared across all variants/loaders.

• Shell layer: loader and version specific integration code that hooks into the server/runtime and registers commands, events and other hooks.
• Core layer: loader-agnostic scheduling and backup execution logic reused across all targets.

Project variants can use code from multiple shells to reduce duplicate code and improve maintainability. For example, the fabric-line-1_21_11 variant uses code from the shell-fabric and shell-mojmap shells, while the neoforge-line-26_1 variant uses code from the shell-neoforge and shell-mojmap shells. Minecraft versions that use Brigadier for command registration (1.13+) use the shell-brigadier shell, etc etc.

New variants are defined in gradle/chronos-compile-groups.json. gradle/chronos-java-matrix.json defines the Java language levels and toolchains for all supported versions. The project has a dedicated tooling/ folder that contains the Java tools for generating variants and running tests.

Gradle commands

All commands should be run from the repository root. The Gradle project provides several useful commands for building and testing the mod.

• buildAll: Builds all enabled variants, then collects output jars.
• collectAllJars: Copies final jars to root build/libs/ (runs as part of buildAll).
• buildRust: Builds native rust-pruner libraries (host-only by default. testServers adds linux-x86_64 via Docker on Windows/macOS).
• testServers: Builds jars (with Docker-compatible natives) and runs Docker-based server integration tests.
• generateVariants: Regenerates variants/ from gradle/chronos-compile-groups.json (should be run automatically when appropriate).
• cleanVariants: Clears the variants/ folder. Useful when encountering issues with stale/locked variant directories.
• smokeTest: (DEPRECATED) Automated dedicated-server smoke runs. Spins up a server for each variant and runs specific tests to ensure the mod is working correctly.
• :fabric-line-…:build / :neoforge-line-…:build: Build a specific variant's jar.
• :fabric-line-…:runClient / :neoforge-line-…:runServer: Run a specific variant's server or client.

Variant generation (generateVariants)

variants/ is a folder that contains the Gradle projects for each variant. Each variant is a separate project, and is built separately. The generateVariants task is used to regenerate the variants/ folder from the gradle/chronos-compile-groups.json file. generateVariants should be run automatically when appropriate, but can be run manually alongside cleanVariants to force a regeneration. CHRONOS_VARIANT_GENERATION environment variable can be set to skip to skip the automatic variant regeneration.

Server testing (testServers)

testServers is a utility that uses Docker and the itzg/minecraft-server image to run integration tests for every supported loader/version combination. It first creates a Rust build environment in Docker and uses cargo-zigbuild to compile the rust-pruner library for linux-x86_64. It then builds all JARs with the native library included.

Once the artifacts are built, testServers starts a Dockerized Minecraft server for each supported loader/version combination. During startup, it checks the server logs for a number of markers to verify that the mod loaded and initialized correctly. Finally, it runs the speedtest command to confirm that backups function correctly and meet expected performance targets.

To run one or a few targets instead of the full matrix, pass -Pchronos.testServers.args with --only (repeatable). Targets use the form loader-version, with dots or underscores in the version (e.g. fabric-1.14.4, forge-1_14_4). These match the Docker container id suffix (chronos-fabric-1_14_4).

This test is meant for power users and should be run at least once before any release to ensure the mod is working correctly on every supported version. On the initial run, it will need to pull every Docker Image (7 in total), as well as create and install every loader and version in the server, for over 100 combinations. This can take an extremely long time on first install, but will mostly be cached after that. The entire test run, after the initial install, can still take more than an hour in the best case scenario.

Note

Keep in mind that Docker Images and containers are stored and managed by Docker. Commands like cleanVariants and clean will not remove them. You will need to manually remove them with your operating system's Docker management tools.

Command examples

./gradlew cleanVariants
./gradlew buildAll
./gradlew :neoforge-line-26_1:runClient
./gradlew :fabric-line-1_21_11:runServer
./gradlew testServers
./gradlew testServers "-Pchronos.testServers.args=--only fabric-1.14.4"
./gradlew testServers "-Pchronos.testServers.args=--only fabric-1_14_4 --only forge-1_14_4"

Footnotes

1. Might also be supported on Fabric through Legacy Fabric in the future. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹

2. Forge 1.7.2 does not build yet (Unimined#184). ↩