From 7c0d3f4bd6ea1eea9f3b34dac9e523dc67a903e1 Mon Sep 17 00:00:00 2001
From: RecursivePineapple <recursive_pineapple@proton.me>
Date: Tue, 28 Oct 2025 00:52:40 -0400
Subject: [PATCH] Expose ability to iterate over structures (#49)

---
 .../structure/IStructureDefinition.java       | 16 ++++++++++++++++
 .../structure/IStructureWalker.java           | 19 ++++++++++++++++++-
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureDefinition.java b/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureDefinition.java
index d9cba10d..c95f8172 100644
--- a/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureDefinition.java
+++ b/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureDefinition.java
@@ -319,6 +319,22 @@ public interface IStructureDefinition<T> {
         return walker.getBuilt();
     }
 
+    default void iterate(String piece, World world, ExtendedFacing extendedFacing, int basePositionX, int basePositionY,
+            int basePositionZ, int basePositionA, int basePositionB, int basePositionC, IStructureWalker<T> predicate) {
+        StructureUtility.iterateV2(
+                getStructureFor(piece),
+                world,
+                extendedFacing,
+                basePositionX,
+                basePositionY,
+                basePositionZ,
+                basePositionA,
+                basePositionB,
+                basePositionC,
+                predicate,
+                "customIterate");
+    }
+
     /**
      * Low level utility.
      *
diff --git a/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureWalker.java b/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureWalker.java
index 2f3111df..d0856684 100644
--- a/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureWalker.java
+++ b/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureWalker.java
@@ -2,8 +2,25 @@ package com.gtnewhorizon.structurelib.structure;
 
 import net.minecraft.world.World;
 
-interface IStructureWalker<T> {
+/**
+ * A functional interface that is used to iterate over an arbitrary structure.
+ */
+@FunctionalInterface
+public interface IStructureWalker<T> {
 
+    /**
+     * Called once per structure element.
+     *
+     * @param element The current element
+     * @param world   The current world
+     * @param x       The absolute X position of the element in world coordinates
+     * @param y       The absolute Y position of the element in world coordinates
+     * @param z       The absolute Z position of the element in world coordinates
+     * @param a       The relative A position of the element in structure-local coordinates (pre transform)
+     * @param b       The relative B position of the element in structure-local coordinates (pre transform)
+     * @param c       The relative C position of the element in structure-local coordinates (pre transform)
+     * @return False to stop iterating, true to continue.
+     */
     boolean visit(IStructureElement<T> element, World world, int x, int y, int z, int a, int b, int c);
 
     default boolean blockNotLoaded(IStructureElement<T> element, World world, int x, int y, int z, int a, int b,