#963: Add API for in-world structures

By: coll1234567 <joshl5324@gmail.com>

paper-api/src/main/java/org/bukkit/Chunk.java

@@ -6,6 +6,8 @@ import org.bukkit.block.Block;
 import org.bukkit.block.BlockState;
 import org.bukkit.block.data.BlockData;
 import org.bukkit.entity.Entity;
+import org.bukkit.generator.structure.GeneratedStructure;
+import org.bukkit.generator.structure.Structure;
 import org.bukkit.persistence.PersistentDataHolder;
 import org.bukkit.plugin.Plugin;
 import org.jetbrains.annotations.NotNull;
@@ -263,6 +265,26 @@ public interface Chunk extends PersistentDataHolder {
     @NotNull
     LoadLevel getLoadLevel();
 
+    /**
+     * Gets all generated structures that intersect this chunk. <br>
+     * If no structures are present an empty collection will be returned.
+     *
+     * @return a collection of placed structures in this chunk
+     */
+    @NotNull
+    Collection<GeneratedStructure> getStructures();
+
+    /**
+     * Gets all generated structures of a given {@link Structure} that intersect
+     * this chunk. <br>
+     * If no structures are present an empty collection will be returned.
+     *
+     * @param structure the structure to find
+     * @return a collection of placed structures in this chunk
+     */
+    @NotNull
+    Collection<GeneratedStructure> getStructures(@NotNull Structure structure);
+
     /**
      * An enum to specify the load level of a chunk.
      */

paper-api/src/main/java/org/bukkit/World.java

@@ -26,6 +26,7 @@ import org.bukkit.generator.BiomeProvider;
 import org.bukkit.generator.BlockPopulator;
 import org.bukkit.generator.ChunkGenerator;
 import org.bukkit.generator.WorldInfo;
+import org.bukkit.generator.structure.GeneratedStructure;
 import org.bukkit.generator.structure.Structure;
 import org.bukkit.generator.structure.StructureType;
 import org.bukkit.inventory.ItemStack;
@@ -2869,6 +2870,33 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
     @NotNull
     public Set<FeatureFlag> getFeatureFlags();
 
+    /**
+     * Gets all generated structures that intersect the chunk at the given
+     * coordinates. <br>
+     * If no structures are present an empty collection will be returned.
+     *
+     * @param x X-coordinate of the chunk
+     * @param z Z-coordinate of the chunk
+     * @return a collection of placed structures in the chunk at the given
+     * coordinates
+     */
+    @NotNull
+    public Collection<GeneratedStructure> getStructures(int x, int z);
+
+    /**
+     * Gets all generated structures of a given {@link Structure} that intersect
+     * the chunk at the given coordinates. <br>
+     * If no structures are present an empty collection will be returned.
+     *
+     * @param x X-coordinate of the chunk
+     * @param z Z-coordinate of the chunk
+     * @param structure the structure to find
+     * @return a collection of placed structures in the chunk at the given
+     * coordinates
+     */
+    @NotNull
+    public Collection<GeneratedStructure> getStructures(int x, int z, @NotNull Structure structure);
+
     /**
      * Represents various map environment types that a world may be
      */

paper-api/src/main/java/org/bukkit/generator/structure/GeneratedStructure.java

@@ -0,0 +1,38 @@
+package org.bukkit.generator.structure;
+
+import java.util.Collection;
+import org.bukkit.persistence.PersistentDataHolder;
+import org.bukkit.util.BoundingBox;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Represents a structure placed in the world.
+ *
+ * @see StructurePiece
+ */
+public interface GeneratedStructure extends PersistentDataHolder {
+
+    /**
+     * Gets the bounding box of this placed structure.
+     *
+     * @return bounding box of this placed structure
+     */
+    @NotNull
+    public BoundingBox getBoundingBox();
+
+    /**
+     * Gets the structure that this PlacedStructure represents.
+     *
+     * @return the structure that this PlacedStructure represents
+     */
+    @NotNull
+    public Structure getStructure();
+
+    /**
+     * Gets all the {@link StructurePiece} that make up this PlacedStructure.
+     *
+     * @return a collection of all the StructurePieces
+     */
+    @NotNull
+    public Collection<StructurePiece> getPieces();
+}

paper-api/src/main/java/org/bukkit/generator/structure/StructurePiece.java

@@ -0,0 +1,20 @@
+package org.bukkit.generator.structure;
+
+import org.bukkit.util.BoundingBox;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Represents an individual part of a {@link GeneratedStructure}.
+ *
+ * @see GeneratedStructure
+ */
+public interface StructurePiece {
+
+    /**
+     * Gets the bounding box of this structure piece.
+     *
+     * @return bounding box of this structure piece
+     */
+    @NotNull
+    public BoundingBox getBoundingBox();
+}