feat: add sections on world loading

Author: LooFifteen

.vitepress/config.mts

@@ -78,11 +78,18 @@ export default defineConfig({
           text: "World",
           items: [
             { text: "Instances", link: "/docs/world/instances" },
+            {
+              text: "Loading",
+              link: "/docs/world/loading",
+              items: [
+                { text: "Anvil", link: "/docs/world/loading/anvil" },
+                { text: "Polar", link: "/docs/world/loading/polar" },
+              ],
+            },
             {
               text: "Chunk Management",
               link: "/docs/world/chunk-management",
               items: [
-                { text: "Anvil Loader", link: "/docs/world/anvilloader" },
                 { text: "Lighting", link: "/docs/world/lightloader" },
               ],
             },

docs/world/anvilloader.md

@@ -0,0 +1,29 @@
+# World Loading
+
+In order to load or save an [`Instance`](https://javadoc.minestom.net/net/minestom/server/instance/Instance.html), you must provide an [`IChunkLoader`](https://javadoc.minestom.net/net/minestom/server/instance/IChunkLoader.html) that Minestom will use to read and write chunk data to and from.
+
+When creating your instance, you can provide the loader in multiple ways:
+* [`InstanceManager#createInstanceContainer(@Nullable IChunkLoader)`](https://javadoc.minestom.net/net/minestom/server/instance/InstanceManager.html#createInstanceContainer(net.minestom.server.instance.IChunkLoader))
+* [`InstanceManager#createInstanceContainer(RegistryKey<DimensionType>, @Nullable IChunkLoader)`](https://javadoc.minestom.net/net/minestom/server/instance/InstanceManager.html#createInstanceContainer(net.minestom.server.instance.IChunkLoader))
+* [`InstanceContainer#setChunkLoader(IChunkLoader)`](https://javadoc.minestom.net/net/minestom/server/instance/InstanceContainer.html#setChunkLoader(net.minestom.server.instance.IChunkLoader))
+
+Minestom will automatically load chunks from the loader once provided.
+
+## Saving
+
+Saving must be done in two steps:
+1. [`Instance#saveChunksToStorage`](https://javadoc.minestom.net/net/minestom/server/instance/Instance.html#saveChunksToStorage())
+2. [`Instance#saveInstance`](https://javadoc.minestom.net/net/minestom/server/instance/Instance.html#saveInstance())
+
+```java
+MinecraftServer.getSchedulerManager().buildShutdownTask(() -> {
+    this.instance.saveChunksToStorage();
+    this.instance.saveInstance();
+});
+```
+
+## Loaders
+
+* [No-op](https://javadoc.minestom.net/net/minestom/server/instance/IChunkLoader.html#noop())
+* [Anvil](/docs/world/loading/anvil.md)
+* [Polar](/docs/world/loading/polar.md)

docs/world/loading.md

@@ -0,0 +1,19 @@
+# Anvil Loader
+
+Anvil is the format made by Mojang for vanilla. Minestom provides this format and it is chosen **by default** on newly created instances. Anvil is a multi-file world format, so must be provided with a directory to store world data. The anvil loader also supports reading light data from the worlds, this is enabled by default.
+
+## Requirements
+
+Worlds to be used with [`AnvilLoader`](https://javadoc.minestom.net/net/minestom/server/instance/anvil/AnvilLoader.html) only need to contain the `region` directory, which is where the chunk data comes from. Chunk loaders do not read entity data.
+
+## Usage
+
+To use a world from the **runtime file system**, you can do something like the following code snippet, which constructs the loader using [`AnvilLoader#<init>(Path)`](https://javadoc.minestom.net/net/minestom/server/instance/anvil/AnvilLoader.html#%3Cinit%3E(java.nio.file.Path)).
+
+```java
+final Path directory = this.worlds.join("world");
+final AnvilLoader loader = new AnvilLoader(directory);
+final InstanceContainer instance = MinecraftServer.getInstanceManager().createInstanceContainer(loader);
+```
+
+Remember, however, that this **does not** read from the jar resources. Other war crimes must be committed for this to happen.

docs/world/loading/anvil.md

@@ -0,0 +1,66 @@
+# Polar Loader
+
+::: warning
+Polar is an external library made by [Hollow Cube](https://github.com/hollow-cube/). External libraries have no obligation to be updated alongside Minestom and may go stale in the future.
+:::
+
+[Polar](https://github.com/hollow-cube/polar) is a format made by Hollow Cube, designed to store large amounts of user-generated instances. Polar has numerous benefits over Anvil, like being stored in a single file and supporting zstd compression. However, it is not the best option in many use cases.
+
+Custom data provided by the server can also be stored in Polar files alongside chunk data, more information about this can be found in the [README](https://github.com/hollow-cube/polar/tree/main?tab=readme-ov-file#user-data--callbacks).
+
+## Requirements
+
+Polar requires a world in the Polar format, of course. The library ships with an Anvil conversion utility found in the `AnvilPolar` class. You may also opt to create your worlds using Minestom to be saved straight into Polar.
+
+## Usage
+
+Polar can be found on Maven Central, so no repositories are required on top of Minestom's.
+
+:::tabs
+== Gradle (Groovy)
+
+```groovy-vue
+dependencies {
+    implementation 'dev.hollowcube:polar:<see releases>'
+}
+```
+
+== Gradle (Kotlin)
+
+```kotlin-vue
+dependencies {
+    implementation("dev.hollowcube:polar:<see releases>")
+}
+```
+
+== Maven
+
+```xml-vue
+<dependencies>
+    <dependency>
+        <groupId>dev.hollowcube</groupId>
+        <artifactId>polar</artifactId>
+        <version>see releases</version>
+    </dependency>
+</dependencies>
+```
+:::
+
+### Direct
+
+```java
+final Path file = this.worlds.join("world.polar");
+final PolarLoader loader = new PolarLoader(file); // can also take an InputStream
+final InstanceContainer instance = MinecraftServer.getInstanceManager().createInstanceContainer(loader);
+```
+
+### Streaming
+
+Loads a polar world into an instance in a streaming manner. This method significantly reduces the memory overhead of loading a world and should generally be preferrable.
+
+```java
+final Path file = this.worlds.join("world.polar");
+final FileChannel channel = FileChannel.open(file, StandardOpenOption.READ);
+final InstanceContainer instance = MinecraftServer.getInstanceManager().createInstanceContainer();
+final CompletableFuture<Void> future = PolarLoader.streamLoad(instance, channel, channel.size(), null, null, true);
+```