Refactor Chunk and Volume

There have been multiple renames to more accurately reflect what the objects represent. Particularly of note:

* ProtoWorld is now WorldLike
* Chunk is now WorldChunk
* ProtoChunk is now Chunk (as it is the basic chunk)
* PrimitiveChunk is now a GenerationChunk
* ChunkVolume no longer implements BlockVolume, just Volume
* Volume methods that return block co-ordinates are renamed to not include the word "block" to reduce confusion, as they return positions, not blocks
* ChunkEvent has a WorldScoped subinterface that most chunk events now implement.
* regenerateChunk has been moved from ServerLevel to ChunkManager and now returns a completable future.

Author: Daniel Naylor

src/main/java/org/spongepowered/api/event/cause/entity/SpawnTypes.java

@@ -41,7 +41,7 @@
 import org.spongepowered.api.registry.RegistryScopes;
 import org.spongepowered.api.registry.RegistryTypes;
 import org.spongepowered.api.world.World;
-import org.spongepowered.api.world.chunk.Chunk;
+import org.spongepowered.api.world.chunk.WorldChunk;
 import org.spongepowered.api.world.weather.WeatherType;
 import org.spongepowered.plugin.PluginContainer;
 
@@ -68,7 +68,7 @@ public final class SpawnTypes {
     public static final DefaultedRegistryReference<SpawnType> BREEDING = SpawnTypes.key(ResourceKey.sponge("breeding"));
 
     /**
-     * An entity spawned due to a {@link Chunk} being loaded.
+     * An entity spawned due to a {@link WorldChunk} being loaded.
      */
     public static final DefaultedRegistryReference<SpawnType> CHUNK_LOAD = SpawnTypes.key(ResourceKey.sponge("chunk_load"));
 

src/main/java/org/spongepowered/api/event/world/chunk/ChunkEvent.java

@@ -27,55 +27,71 @@
 import org.spongepowered.api.ResourceKey;
 import org.spongepowered.api.event.Cancellable;
 import org.spongepowered.api.event.Event;
-import org.spongepowered.api.world.World;
+import org.spongepowered.api.util.annotation.eventgen.NoFactoryMethod;
 import org.spongepowered.api.world.chunk.Chunk;
+import org.spongepowered.api.world.chunk.WorldChunk;
+import org.spongepowered.api.world.server.ServerWorld;
 import org.spongepowered.math.vector.Vector3i;
 
 public interface ChunkEvent extends Event {
 
     /**
-     * Gets the {@link ResourceKey} of the {@link World} that the {@link Chunk} resides in.
+     * Gets the position of the {@link Chunk}, in chunk co-ordinates.
      *
-     * @return The key
+     * @return the position
      */
-    ResourceKey chunkWorld();
+    Vector3i chunkPosition();
 
     /**
-     * Gets the position of the {@link Chunk}.
-     *
-     * @return the position
+     * Represents an event that has knowledge about the {@link ServerWorld} that
+     * is being operated upon.
      */
-    Vector3i chunkPosition();
+    @NoFactoryMethod
+    interface WorldScoped extends ChunkEvent {
+
+        /**
+         * Gets the {@link ResourceKey} of the {@link WorldScoped} that the
+         * {@link WorldChunk} resides in.
+         *
+         * <p>Be careful when retrieving the {@link ServerWorld} within this
+         * event as some events may not fire on the main thread and such world
+         * access is not thread safe.</p>
+         *
+         * @return The world's {@link ResourceKey}
+         */
+        ResourceKey worldKey();
+
+    }
 
     /**
-     * Called when a {@link Chunk} was unloaded.
+     * Called when a {@link WorldChunk} was unloaded.
      */
-    interface Unload extends ChunkEvent {
+    interface Unload extends WorldScoped {
 
     }
 
     /**
-     * Called when a {@link Chunk} is performing a save.
+     * Called when a {@link WorldChunk} is performing a save.
      */
-    interface Save extends ChunkEvent {
+    interface Save extends WorldScoped {
 
         /**
-         * Called before the {@link Chunk} is saved. Cancelling this will prevent any of
+         * Called before the {@link WorldChunk} is saved. Cancelling this will prevent any of
          * the chunk's data being written to it's storage container.
          */
         interface Pre extends Save, Cancellable {
 
             /**
-             * Gets the {@link Chunk} being changed.
+             * Gets the {@link WorldChunk} being changed.
              *
              * @return The Chunk
              */
-            Chunk targetChunk();
+            WorldChunk targetChunk();
 
         }
 
         /**
-         * Called after the {@link Chunk} is saved. Guaranteed to exist in the chunk's
+         * Called after the {@link WorldChunk} is saved. Guaranteed to exist in the chunk's
          * storage container.
          *
          * Depending on the implementation, this event may be called off-thread.
@@ -84,22 +100,22 @@ interface Post extends Save {}
     }
 
     /**
-     * Called when a new {@link Chunk} was generated.
+     * Called when a new {@link WorldChunk} was generated.
      */
-    interface Generated extends ChunkEvent {
+    interface Generated extends WorldScoped {
 
     }
 
     /**
-     * Called when a {@link Chunk} is done loading.
+     * Called when a {@link WorldChunk} is done loading.
      */
-    interface Load extends ChunkEvent {
+    interface Load extends WorldScoped {
 
         /**
-         * Gets the {@link Chunk} being changed.
+         * Gets the {@link WorldChunk} being changed.
          *
          * @return The Chunk
          */
-        Chunk targetChunk();
+        WorldChunk targetChunk();
     }
 }

src/main/java/org/spongepowered/api/world/World.java

@@ -33,7 +33,7 @@
 import org.spongepowered.api.registry.ScopedRegistryHolder;
 import org.spongepowered.api.service.context.ContextSource;
 import org.spongepowered.api.util.annotation.DoNotStore;
-import org.spongepowered.api.world.chunk.Chunk;
+import org.spongepowered.api.world.chunk.WorldChunk;
 import org.spongepowered.api.world.storage.WorldProperties;
 import org.spongepowered.api.world.volume.archetype.ArchetypeVolumeCreator;
 import org.spongepowered.api.world.volume.block.PhysicsAwareMutableBlockVolume;
@@ -52,7 +52,7 @@
 @DoNotStore
 public interface World<W extends World<W, L>, L extends Location<W, L>> extends
     ForwardingAudience,
-    ProtoWorld<W>,
+    WorldLike<W>,
     LocationCreator<W, L>,
     PhysicsAwareMutableBlockVolume<W>,
     ContextSource,
@@ -128,8 +128,8 @@ default Optional<? extends Player> closestPlayer(final int x, final int y, final
 
     /**
      * {@inheritDoc}
-     * This gets a guaranteed {@link Chunk} at the desired block position; however,
-     * the {@link Chunk} instance may be {@link Chunk#isEmpty() empty}, and
+     * This gets a guaranteed {@link WorldChunk} at the desired block position; however,
+     * the {@link WorldChunk} instance may be {@link WorldChunk#isEmpty() empty}, and
      * likewise, may not be generated, valid, pre-existing. It is important to
      * check for these cases prior to attempting to modify the chunk.
      *
@@ -141,12 +141,12 @@ default Optional<? extends Player> closestPlayer(final int x, final int y, final
      * @return The available chunk at that position
      */
     @Override
-    Chunk chunkAtBlock(final Vector3i blockPosition);
+    WorldChunk chunkAtBlock(final Vector3i blockPosition);
 
     /**
      * {@inheritDoc}
-     * This gets a guaranteed {@link Chunk} at the desired block position; however,
-     * the {@link Chunk} instance may be {@link Chunk#isEmpty() empty}, and
+     * This gets a guaranteed {@link WorldChunk} at the desired block position; however,
+     * the {@link WorldChunk} instance may be {@link WorldChunk#isEmpty() empty}, and
      * likewise, may not be generated, valid, pre-existing. It is important to
      * check for these cases prior to attempting to modify the chunk.
      *
@@ -160,28 +160,28 @@ default Optional<? extends Player> closestPlayer(final int x, final int y, final
      * @return The available chunk at that position
      */
     @Override
-    Chunk chunkAtBlock(int bx, int by, int bz);
+    WorldChunk chunkAtBlock(int bx, int by, int bz);
 
     /**
      * {@inheritDoc}
-     * This gets a guaranteed {@link Chunk} at the desired chunk position; however,
-     * the {@link Chunk} instance may be {@link Chunk#isEmpty() empty}, and
+     * This gets a guaranteed {@link WorldChunk} at the desired chunk position; however,
+     * the {@link WorldChunk} instance may be {@link WorldChunk#isEmpty() empty}, and
      * likewise, may not be generated, valid, pre-existing. It is important to
      * check for these cases prior to attempting to modify the chunk.
      *
      * @param chunkPos The chunk position relative to the {@link Server#chunkLayout() chunk layout}
      * @return The available chunk at that position
      */
     @Override
-    default Chunk chunk(final Vector3i chunkPos) {
+    default WorldChunk chunk(final Vector3i chunkPos) {
         Objects.requireNonNull(chunkPos, "chunkPos");
         return this.chunk(chunkPos.x(), chunkPos.y(), chunkPos.z());
     }
 
     /**
      * {@inheritDoc}
-     * This gets a guaranteed {@link Chunk} at the desired chunk position; however,
-     * the {@link Chunk} instance may be {@link Chunk#isEmpty() empty}, and
+     * This gets a guaranteed {@link WorldChunk} at the desired chunk position; however,
+     * the {@link WorldChunk} instance may be {@link WorldChunk#isEmpty() empty}, and
      * likewise, may not be generated, valid, pre-existing. It is important to
      * check for these cases prior to attempting to modify the chunk.
      *
@@ -191,7 +191,7 @@ default Chunk chunk(final Vector3i chunkPos) {
      * @return The available chunk at the chunk position
      */
     @Override
-    Chunk chunk(int cx, int cy, int cz);
+    WorldChunk chunk(int cx, int cy, int cz);
 
     /**
      * Gets the chunk at the given chunk coordinate position if it exists or if
@@ -201,7 +201,7 @@ default Chunk chunk(final Vector3i chunkPos) {
      * @param shouldGenerate True to generate a new chunk
      * @return The loaded or generated chunk, if already generated
      */
-    default Optional<Chunk> loadChunk(final Vector3i chunkPosition, final boolean shouldGenerate) {
+    default Optional<WorldChunk> loadChunk(final Vector3i chunkPosition, final boolean shouldGenerate) {
         Objects.requireNonNull(chunkPosition, "chunkPosition");
         return this.loadChunk(chunkPosition.x(), chunkPosition.y(), chunkPosition.z(), shouldGenerate);
     }
@@ -218,7 +218,7 @@ default Optional<Chunk> loadChunk(final Vector3i chunkPosition, final boolean sh
      * @param shouldGenerate True to generate a new chunk
      * @return The loaded or generated chunk, if already generated
      */
-    Optional<Chunk> loadChunk(int cx, int cy, int cz, boolean shouldGenerate);
+    Optional<WorldChunk> loadChunk(int cx, int cy, int cz, boolean shouldGenerate);
 
     /**
      * Returns a Collection of all actively loaded chunks in this world.
@@ -227,6 +227,6 @@ default Optional<Chunk> loadChunk(final Vector3i chunkPosition, final boolean sh
      *
      * @return The loaded chunks
      */
-    Iterable<Chunk> loadedChunks();
+    Iterable<WorldChunk> loadedChunks();
 
 }

…/spongepowered/api/world/ProtoWorld.java …g/spongepowered/api/world/WorldLike.javasrc/main/java/org/spongepowered/api/world/ProtoWorld.java renamed to src/main/java/org/spongepowered/api/world/WorldLike.java src/main/java/org/spongepowered/api/world/ProtoWorld.java renamed to src/main/java/org/spongepowered/api/world/WorldLike.java

@@ -42,7 +42,7 @@
 
 import java.util.Objects;
 
-public interface ProtoWorld<P extends ProtoWorld<P>> extends
+public interface WorldLike<P extends WorldLike<P>> extends
     Region<P>,
     BiomeVolume.Modifiable<P>, // Because this is mutable
     BlockVolume.Modifiable<P>, // Because this is mutable