World storage & layout

Two config.yml settings decide where a realm’s blocks live and how they are arranged: realm.world-storage and realm.layout. Run /realm admin status at any time to see what the server is actually running — the backend and layout in use, not just what the file asks for.

World storage: folder or polar

folder (the default) is an ordinary Paper world per realm. It works on every server AtlasRealms supports, and is what the plugin has always done.

polar stores each realm as one compact file, through the PolarPaper plugin. Loading and unloading a realm becomes reading and writing a file instead of walking a folder tree, which is cheaper and produces smaller saves. It needs PolarPaper 2.1.0 or newer and a server on Java 25.

realm.polar-store decides where those blob files themselves live, and is ignored while world-storage: folder:

• file (default) — one .polar file per world under plugins/AtlasRealms/worlds/.
• mysql — one row per world in atlasrealms_worlds. Needs database.type: mysql; SQLite takes a single writer, and a world save in that same file would queue every realm save behind it.

Caution

Switching folder to polar is safe: realms already on disk keep working as folders, and only new ones become blobs. Switching polar back to folder is not — realms already saved as blobs become unreachable. Pick one and leave it.

Templates always stay ordinary worlds, whatever world-storage says — you cannot build inside a file.

Layout: world or grid

world (the default) gives each realm a world of its own, named after the realm’s id. Every server AtlasRealms supports can run this.

grid puts every realm inside one shared world, as a square. AtlasRealms never creates or unloads that world — it only reads the name you give it. Skyblock plugins work the same way.

The grid needs three things:

1. realm.world-storage: polar. Laying a template into a world the plugin does not own is PolarPaper’s work.
2. A world named in realm.grid.world that the server has already loaded at startup — usually a void world you make with any world manager.
3. No realms left over from the other layout. A realm made as a world has no grid square, and a realm made as a grid square has no world of its own. AtlasRealms refuses to switch layouts while either kind of leftover realm exists, rather than stranding them.

Realms in the grid sit realm.grid.spacing blocks apart (minimum 1024, and larger than realm.default-size) — far enough that a region-threaded server gives each realm its own thread, so two players in two realms tick side by side instead of sharing one.

Folia

Folia refuses to create or unload a world at all, so a realm cannot be a world there. realm.layout: grid is the only layout that runs on Folia — the plugin refuses to enable otherwise. World-building admin commands (world load, world unload, template generate, theme generate, theme generate-all) are refused on Folia proper; build templates on Paper or CanvasMC first, then copy the resulting .polar files across.

CanvasMC needs none of this — both layouts and both storage backends work there.

Checking what is actually running

/realm admin status prints the storage backend in use versus what config.yml asks for, the layout in use versus what is asked for, and — for the grid — its world, spacing, and how many realms are placed in it. If a switch was refused because of leftover realms, or PolarPaper is missing, this is where AtlasRealms says so.