Polar

Polar world format for Paper

Polar is a world format very similar to Slime, with similar advantages:

• Small file sizes (see SLIME_COMPARISON)
• Single file world
• Immutable (worlds do not save until explicitly requested)
• Store worlds wherever (whether as a file or in a database)
• Great for lobbies and game arenas
• Fast loading and saving

Polar supports loading both .polar and .slime worlds out of the box.

Polar is also a single plugin and so doesn't require a Paper fork or classloaders

Polar currently supports versions 26.3 - 1.21.11, and requires minimum Java 25

Polar was originally developed for Minestom, see the Minestom loader here

Support Discord

Large worlds

Polar is not designed for large worlds!

Polar is most useful when the whole world is mostly within render distance. The entire world is held in memory as a trade-off to allow for faster loading. This means the size/number of worlds you can load depends on how much RAM you have available.

If you need large worlds, it's likely Anvil (the default world format) will be more useful.

Permissions

Permission nodes are simply polarpaper.<subcommand>, for example: polarpaper.info for /polar info

polarpaper.use for the root command (/polar)

API

Remember to add polarpaper to your depend list in plugin.yml if using as a plugin/compileOnly

depend:
  - polarpaper

Add to Gradle:

repositories {
    maven("https://repo.minehub.live/releases")
}
dependencies {
    compileOnly("live.minehub:polarpaper:<latest version>")
}

Load a polar world

// Manually
Path path = Path.of("path/to/world.polar");
String worldName = path.getFileName().toString().split("\\.polar")[0];
byte[] bytes;
try {
    // This example shows reading a world from a file, however
    // as long as you can read and write an array of bytes, you can read it
    // from wherever you want - including mysql and redis!
    bytes = Files.readAllBytes(path);
} catch (IOException e) {
    throw new RuntimeException(e);
}
PolarWorld polarWorld = PolarReader.read(bytes);
Polar.loadWorld(polarWorld, worldName);

// or by using config
Polar.loadWorldConfigSource("gamingworld");

Save a polar world

// Using config (same as /polar save)
World bukkitWorld = player.getWorld();
Polar.saveWorldConfigSource(bukkitWorld);

// Custom source
World bukkitWorld = player.getWorld();
Path savePath = Path.of("./epic/world.polar");
// feel free to use your own PolarSource class
PolarSource source = new FilePolarSource(savePath);
Polar.saveWorld(bukkitWorld, source);

Get the PolarWorld that a player is in

PolarWorld polarWorld = PolarWorld.fromWorld(player.getWorld());
// (returns null if the world is not from PolarPaper)

Register events

// If you're not running the PolarPaper plugin and instead using it exclusively
// as a dependency (e.g. implementation instead of compileOnly), you do not need to
// add it to the depend list in your plugin.yml. However, in order to allow entities
// to be read and spawned automatically, you must manually register the plugin listeners:
PolarPaper.registerEvents();