minestom-anvil-worlds

Minestom Anvil worlds

Minestom does not save worlds by default — instances are in-memory. To load an existing Minecraft world or persist edits, attach a ChunkLoader. AnvilLoader reads/writes the vanilla Anvil region format.

Load an existing world

import net.minestom.server.instance.AnvilLoader;

InstanceContainer instance = MinecraftServer.getInstanceManager().createInstanceContainer();
instance.setChunkLoader(new AnvilLoader("worlds/myworld"));

The folder needs at least a region/ subdirectory (the .mca files). Chunks are read lazily as they load. Generation and the loader coexist: chunks present on disk are loaded; missing chunks fall back to the instance Generator (set one, or unloaded areas stay empty).

instance.setGenerator(unit -> unit.modifier().fillHeight(0, 40, Block.STONE)); // fallback for ungenerated chunks

Save edits to disk

instance.saveChunksToStorage();          // all loaded chunks -> disk
instance.saveInstance();                  // instance-level data + chunks

Saving only works for instances backed by a loader that supports writing (AnvilLoader does). Call it on shutdown and/or periodically from a scheduler — Minestom won't autosave.

MinecraftServer.getSchedulerManager().buildTask(instance::saveChunksToStorage)
    .repeat(TaskSchedule.minutes(5))
    .schedule();

Loading / unloading chunks explicitly

instance.loadChunk(chunkX, chunkZ).thenAccept(chunk -> { /* ready */ });
instance.unloadChunk(chunkX, chunkZ);    // drops from memory (save first if dirty)

Chunk load returns a CompletableFuture — I/O happens off the tick thread. Don't block on it from a tick; chain with thenAccept.

Custom storage — IChunkLoader

To store chunks somewhere other than Anvil files (DB, network, the Polar format), implement IChunkLoader:

public interface IChunkLoader {
    CompletableFuture<Chunk> loadChunk(Instance instance, int chunkX, int chunkZ);
    CompletableFuture<Void>  saveChunk(Chunk chunk);
    // + saveChunks / supportsParallelSaving / unload hooks
}
instance.setChunkLoader(new MyChunkLoader());

This is how alternative formats (e.g. Polar, a compact single-file format from the community) plug in — same interface, different backing store.

Notes & gotchas

• A vanilla-saved world only has terrain/blocks in region/; Minestom won't run vanilla mob/redstone logic — it just serves the blocks.
• Saving an instance that was never loaded via a writing loader is a no-op / error — set the loader first.
• Loading is async; treat freshly-createInstanceContainer'd instances as empty until chunks resolve.
• Anvil version compatibility tracks the Minecraft version Minestom targets; a world from a far-newer/older MC may not parse.
• See minestom-instances-worlds for instance basics and generators, minestom-schedulers-tasks for autosave timers.

Sources: https://minestom.net/docs/world/anvilloader