Add region files API

src/main/java/org/spongepowered/api/world/chunk/OfflineChunk.java

@@ -0,0 +1,51 @@
+/*
+ * This file is part of SpongeAPI, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) SpongePowered <https://www.spongepowered.org>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package org.spongepowered.api.world.chunk;
+
+import org.spongepowered.api.data.persistence.DataContainer;
+import org.spongepowered.api.data.persistence.DataSerializable;
+import org.spongepowered.math.vector.Vector3i;
+
+/**
+ * Represents an offline chunk and its data.
+ * The chunk may also be currently loaded!
+ */
+public interface OfflineChunk extends DataSerializable {
+
+    /**
+     * Returns the chunk position.
+     *
+     * @return the chunk position
+     */
+    Vector3i chunkPosition();
+
+    /**
+     * Returns the offline chunk data.
+     *
+     * @return the offline chunk data
+     */
+    @Override
+    DataContainer toContainer();
+}

src/main/java/org/spongepowered/api/world/server/ChunkManager.java

@@ -30,9 +30,12 @@
 import org.spongepowered.api.world.ChunkRegenerateFlag;
 import org.spongepowered.api.world.ChunkRegenerateFlags;
 import org.spongepowered.api.world.chunk.WorldChunk;
+import org.spongepowered.math.vector.Vector2i;
 import org.spongepowered.math.vector.Vector3i;
 
+import java.nio.file.Path;
 import java.util.Collection;
+import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
@@ -246,4 +249,65 @@ default CompletableFuture<Boolean> regenerateChunk(final Vector3i chunkPosition,
      */
     CompletableFuture<Boolean> regenerateChunk(int cx, int cy, int cz, ChunkRegenerateFlag flag);
 
+    /**
+     * Returns the path of the directory where region files are stored.
+     *
+     * @return The path of the region directory
+     */
+    Path regionDirPath();
+
+    /**
+     * Returns the path of the region file containing the given {@link WorldChunk}.
+     *
+     * @param chunk The {@link WorldChunk} for which to acquire the region file path
+     * @return The path of the region file for the given chunk
+     */
+    Path regionFilePath(WorldChunk chunk);
+
+    /**
+     * Calculates the maximum chunk coordinates for a given region coordinates (x, z) in a world.
+     *
+     * @param rx The x-coordinate of the region
+     * @param rz The z-coordinate of the region
+     * @return A {@link Vector3i} containing the maximum chunk coordinates for the given region coordinates
+     */
+    Vector3i maxChunkFromRegion(int rx, int rz);
+
+    /**
+     * Calculates the maximum chunk coordinates for a given region coordinates (x, z) in a world.
+     *
+     * @param regionCoordinate The coordinate of the region
+     * @return A {@link Vector3i} containing the maximum chunk coordinates for the given region coordinates
+     */
+    default Vector3i maxChunkFromRegion(Vector2i regionCoordinate) {
+        Objects.requireNonNull(regionCoordinate, "regionCoordinate");
+        return this.maxChunkFromRegion(regionCoordinate.x(), regionCoordinate.y());
+    }
+
+    /**
+     * Calculates the minimum chunk coordinates for a given region coordinates (x, z) in a world.
+     *
+     * @param rx The x-coordinate of the region
+     * @param rz The z-coordinate of the region
+     * @return A {@link Vector3i} containing the minimum chunk coordinates for the given region coordinates
+     */
+    Vector3i minChunkFromRegion(int rx, int rz);
+
+    /**
+     * Calculates the maximum chunk coordinates for a given region coordinates (x, z) in a world.
+     *
+     * @param regionCoordinate The coordinate of the region
+     * @return A {@link Vector3i} containing the maximum chunk coordinates for the given region coordinates
+     */
+    default Vector3i minChunkFromRegion(Vector2i regionCoordinate) {
+        Objects.requireNonNull(regionCoordinate, "regionCoordinate");
+        return this.minChunkFromRegion(regionCoordinate.x(), regionCoordinate.y());
+    }
+
+    /**
+     * Returns the region coordinates and file paths of existing regions.
+     *
+     * @return the region coordinates and their file paths.
+     */
+    Map<Vector2i, Path> regionFiles();
 }

src/main/java/org/spongepowered/api/world/server/ServerWorld.java

@@ -36,6 +36,7 @@
 import org.spongepowered.api.world.World;
 import org.spongepowered.api.world.WorldType;
 import org.spongepowered.api.world.WorldTypes;
+import org.spongepowered.api.world.chunk.OfflineChunk;
 import org.spongepowered.api.world.chunk.WorldChunk;
 import org.spongepowered.api.world.explosion.Explosion;
 import org.spongepowered.api.world.generation.ChunkGenerator;
@@ -50,6 +51,7 @@
 import java.util.Objects;
 import java.util.Optional;
 import java.util.UUID;
+import java.util.stream.Stream;
 
 public interface ServerWorld extends World<ServerWorld, ServerLocation>, Identifiable, InteractableVolume,
         ServerLocationCreator, WeatherUniverse.Mutable {
@@ -235,4 +237,29 @@ default boolean restoreSnapshot(final Vector3i position, final BlockSnapshot sna
      */
     ChunkManager chunkManager();
 
+    /**
+     * Returns a stream of existing chunk positions for this world.
+     * <p>
+     * Note that consuming the stream is slow, consider consuming it asynchronously.
+     * <p>
+     * The stream must be closed or fully consumed otherwise file handles may stay open.
+     *
+     * @return The stream of existing chunk positions.
+     */
+    Stream<Vector3i> chunkPositions();
+
+
+    /**
+     * Returns a stream of existing chunks for this world.
+     * <p>
+     * Note that consuming the stream is very slow, consider consuming it asynchronously.
+     * <p>
+     * The stream must be closed or fully consumed otherwise file handles may stay open.
+     * <p>
+     * You should not modify data of currently loaded chunks.
+     *
+     * @return The stream of existing chunks.
+     */
+    Stream<OfflineChunk> offlineChunks();
+
 }