From 708778538993685067a101456c294b3fe2530325 Mon Sep 17 00:00:00 2001
From: Bukkit/Spigot <noreply+git-bukkit@papermc.io>
Date: Sun, 4 Feb 2024 10:04:33 +1100
Subject: [PATCH] #963: Add API for in-world structures

By: coll1234567 <joshl5324@gmail.com>
---
 paper-api/src/main/java/org/bukkit/Chunk.java | 22 +++++++++++
 paper-api/src/main/java/org/bukkit/World.java | 28 ++++++++++++++
 .../structure/GeneratedStructure.java         | 38 +++++++++++++++++++
 .../generator/structure/StructurePiece.java   | 20 ++++++++++
 4 files changed, 108 insertions(+)
 create mode 100644 paper-api/src/main/java/org/bukkit/generator/structure/GeneratedStructure.java
 create mode 100644 paper-api/src/main/java/org/bukkit/generator/structure/StructurePiece.java

diff --git a/paper-api/src/main/java/org/bukkit/Chunk.java b/paper-api/src/main/java/org/bukkit/Chunk.java
index efbfed8552..a25f112f4d 100644
--- a/paper-api/src/main/java/org/bukkit/Chunk.java
+++ b/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.
      */
diff --git a/paper-api/src/main/java/org/bukkit/World.java b/paper-api/src/main/java/org/bukkit/World.java
index 17d31a2c39..488327daa0 100644
--- a/paper-api/src/main/java/org/bukkit/World.java
+++ b/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
      */
diff --git a/paper-api/src/main/java/org/bukkit/generator/structure/GeneratedStructure.java b/paper-api/src/main/java/org/bukkit/generator/structure/GeneratedStructure.java
new file mode 100644
index 0000000000..4d461d9f94
--- /dev/null
+++ b/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();
+}
diff --git a/paper-api/src/main/java/org/bukkit/generator/structure/StructurePiece.java b/paper-api/src/main/java/org/bukkit/generator/structure/StructurePiece.java
new file mode 100644
index 0000000000..f53587e76f
--- /dev/null
+++ b/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();
+}