Save Our Dimensions

Save Our Dimensions

A server-side Fabric mod for Minecraft 26.2 that snapshots and restores a single dimension’s
saved data while the server is running.

Two commands, nothing else:

<dimension> uses vanilla’s DimensionArgument, so it tab-completes and accepts
minecraft:overworld, minecraft:the_nether, minecraft:the_end, and any dimension added by a mod
or a datapack. Both commands require the owner permission level (Commands.LEVEL_OWNERS, the 26.2
equivalent of the old permission level 4).

⚠️ Read this before you use it

• This mod deletes world data. /dimload replaces the target dimension’s region/, entities/
  and poi/ directories with the contents of the snapshot. Anything built in that dimension since
  the snapshot is gone.
• Keep external backups. The snapshot lives inside the world folder, so it is not a backup —
  it dies with the world. Take a real backup before you rely on any of this.
• The target dimension freezes during /dimload. Every player in it is teleported out, all its
  chunks are unloaded, and it stays frozen until the restore finishes. Other dimensions keep ticking
  normally throughout.
• Only one snapshot per dimension. A second /dimsave overwrites the first. There are no named
  slots.
• Never touched: level.dat, playerdata/, advancements/, stats/, and the world-level
  data/ directory. Player inventories and progress survive a /dimload untouched.

What happens on /dimload

1. Every player in the target dimension is teleported to the fallback dimension (the overworld, or
   the first other loaded dimension if the overworld is the target), remembering where they were.
2. Force-loaded chunks are recorded and unforced; chunk tickets are dropped.
3. The dimension is drained until it has zero loaded chunks. If that does not happen within 200
   ticks (10 s), the operation aborts, reports how many chunks are still loaded, and puts the
   players and force-loads back. Nothing on disk is touched.
4. The dimension is flushed to disk, its region file handles are closed, and the files are swapped.
5. Derived in-memory caches are cleared, players are teleported back and force-loads are restored.

Step 3 is not optional. A loaded chunk is authoritative in memory and would write itself back over
the restored data at the next autosave, so the mod aborts rather than half-restore a world.

Where snapshots live

<world>/dimsave-snapshots/<namespace>__<path>/
    region/        entities/        poi/        snapshot.json

For example <world>/dimsave-snapshots/minecraft__the_nether/. A snapshot costs roughly the size of
the dimension; the mod refuses to start if the disk cannot fit it.

During a restore the live directories are renamed to region.dimsave-old-<epoch> and friends before
the copy starts, and only deleted once the copy has fully succeeded. If the server dies mid-restore,
those directories are your originals — rename them back by hand.

Known limitations

• Autosave overlap. File work runs on a background dimsave-io thread and the server thread
  does not wait for it. The exception is a vanilla autosave that starts during the swap window:
  its synchronous flush will wait on the dimension’s I/O gate and stall the server thread until the
  swap finishes (seconds, and it resolves itself). With vanilla’s 5-minute autosave interval this is
  unlikely, but it is real.
• A /dimsave can time out on a busy dimension. The mod waits for region I/O to go quiet before
  copying. If something is writing chunks continuously it gives up after 15 s with an error rather
  than copying a moving target.
• Restored players may land inside terrain. After /dimload players return to the exact
  coordinates they left from, which may now be solid rock. The completion message says so.
• One dimension at a time. A second command on a dimension that is already busy is rejected.
• An empty, paused server will not make progress. With pause-when-empty-seconds set (default
  60 in vanilla), a server with no players online stops calling tickChildren, so the mod’s
  per-tick step never runs and a job started from the console or RCON simply sits there. It is not
  stuck or corrupted — it resumes and completes the moment ticking does. If you drive these commands
  on an empty server, set pause-when-empty-seconds=0.

Licence

MIT — see LICENSE. Release history is in CHANGELOG.md.