Vwoop

adapters/bukkit/nms/v26_2_R1/src/main/java/art/arcane/iris/core/nms/v26_2_R1/CustomBiomeSource.java

@@ -66,34 +66,33 @@ public class CustomBiomeSource extends BiomeSource {
         this.cacheDimension = engine.getDimension();
     }
 
-    private static List<Holder<Biome>> getAllBiomes(Registry<Biome> customRegistry, Registry<Biome> registry, Engine engine, Holder<Biome> fallback) {
+    private static List<Holder<Biome>> getAllBiomes(Registry<Biome> customRegistry, Registry<Biome> registry, Engine engine) {
         LinkedHashSet<Holder<Biome>> biomes = new LinkedHashSet<>();
-        boolean resolutionFailed = false;
 
         for (IrisBiome i : engine.getAllBiomes()) {
             Holder<Biome> vanillaHolder = NMSBinding.biomeToBiomeBase(registry, i.getVanillaDerivative());
-            if (vanillaHolder != null) {
-                biomes.add(vanillaHolder);
-            } else if (!i.isCustom()) {
-                resolutionFailed = true;
+            if (vanillaHolder == null) {
+                throw new IllegalStateException("Iris structure biome derivative '"
+                        + i.getVanillaDerivativeKey() + "' is not registered for biome '" + i.getLoadKey() + "'");
             }
+            biomes.add(vanillaHolder);
 
             if (i.isCustom()) {
                 for (IrisBiomeCustom j : i.getCustomDerivitives()) {
                     Holder<Biome> customHolder = resolveCustomBiomeHolder(customRegistry, engine, j.getId());
-                    if (customHolder != null) {
-                        biomes.add(customHolder);
-                    } else {
-                        resolutionFailed = true;
+                    if (customHolder == null) {
+                        throw new IllegalStateException("Iris custom structure biome '"
+                                + engine.getDimension().getLoadKey() + ":" + j.getId() + "' is not registered");
                     }
+                    biomes.add(customHolder);
                 }
             }
         }
 
-        if ((resolutionFailed || biomes.isEmpty()) && fallback != null) {
-            biomes.add(fallback);
+        if (biomes.isEmpty()) {
+            throw new IllegalStateException("Iris pack '" + engine.getName()
+                    + "' has no registered structure biomes");
         }
-
         return new ArrayList<>(biomes);
     }
 
@@ -159,7 +158,7 @@ public class CustomBiomeSource extends BiomeSource {
                 .lookup(Registries.BIOME).orElse(null);
         Registry<Biome> worldRegistry = ((CraftWorld) world).getHandle().registryAccess()
                 .lookup(Registries.BIOME).orElse(null);
-        return Set.copyOf(getAllBiomes(customRegistry, worldRegistry, engine, fallbackBiome));
+        return Set.copyOf(getAllBiomes(customRegistry, worldRegistry, engine));
     }
 
     private KMap<String, Holder<Biome>> fillCustomBiomes(Registry<Biome> customRegistry, Engine engine, Holder<Biome> fallback) {
@@ -310,10 +309,16 @@ public class CustomBiomeSource extends BiomeSource {
         int blockZ = z << 2;
         IrisBiome irisBiome = engine.getComplex().getTrueBiomeStream().get(blockX, blockZ);
         if (irisBiome == null) {
-            return getFallbackBiome();
+            throw new IllegalStateException("Iris returned no surface structure biome at block "
+                    + blockX + "," + blockZ);
         }
         Holder<Biome> holder = NMSBinding.biomeToBiomeBase(biomeRegistry, irisBiome.getVanillaDerivative());
-        return holder == null ? getFallbackBiome() : holder;
+        if (holder == null) {
+            throw new IllegalStateException("Iris structure biome derivative '"
+                    + irisBiome.getVanillaDerivativeKey() + "' is not registered at block "
+                    + blockX + "," + blockZ);
+        }
+        return holder;
     }
 
     public Holder<Biome> getVisibleNoiseBiome(int x, int y, int z, Climate.Sampler sampler) {
@@ -362,19 +367,17 @@ public class CustomBiomeSource extends BiomeSource {
     private Holder<Biome> resolveStructureBiomeHolder(int x, int y, int z) {
         BiomeResolution resolution = resolveBiomeResolution(x, y, z);
         if (resolution == null) {
-            return getFallbackBiome();
+            throw new IllegalStateException("Iris returned no structure biome at quart "
+                    + x + "," + y + "," + z);
         }
 
         Holder<Biome> holder = NMSBinding.biomeToBiomeBase(biomeRegistry, resolution.irisBiome.getVanillaDerivative());
-        if (holder != null) {
-            return holder;
+        if (holder == null) {
+            throw new IllegalStateException("Iris structure biome derivative '"
+                    + resolution.irisBiome.getVanillaDerivativeKey() + "' is not registered at block "
+                    + resolution.blockX + "," + resolution.blockY + "," + resolution.blockZ);
         }
-
-        if (resolution.irisBiome.isCustom()) {
-            return resolveCustomHolder(resolution);
-        }
-
-        return getFallbackBiome();
+        return holder;
     }
 
     private Holder<Biome> resolveVisibleBiomeHolder(int x, int y, int z) {

adapters/bukkit/nms/v26_2_R1/src/main/java/art/arcane/iris/core/nms/v26_2_R1/IrisChunkGenerator.java

@@ -2,12 +2,15 @@ package art.arcane.iris.core.nms.v26_2_R1;
 
 import art.arcane.iris.engine.framework.Engine;
 import art.arcane.iris.engine.framework.IrisStructureLocator;
+import art.arcane.iris.engine.framework.NativeStructureGenerationPolicy;
+import art.arcane.iris.core.structure.NativeStructureLocateCapability;
 import art.arcane.iris.engine.object.IrisDimension;
-import art.arcane.iris.engine.object.IrisImportedStructureControl;
 import art.arcane.iris.engine.object.IrisNativeStructureDecision;
-import art.arcane.iris.engine.object.IrisVanillaStructureStiltSettings;
+import art.arcane.iris.engine.object.IrisStructureStiltSettings;
+import art.arcane.iris.engine.object.NativeStructureGenerationStatus;
+import art.arcane.iris.nativegen.NativeStructureGenerationException;
+import art.arcane.iris.nativegen.NativeStructureLocateResults;
 import art.arcane.iris.nativegen.NativeStructurePostProcessor;
-import art.arcane.iris.spi.IrisLogging;
 import art.arcane.iris.spi.PlatformBlockState;
 import art.arcane.iris.util.common.data.IrisCustomData;
 import art.arcane.iris.util.common.reflect.WrappedField;
@@ -81,7 +84,6 @@ import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ConcurrentHashMap;
 
 public class IrisChunkGenerator extends CustomChunkGenerator {
-    private static final String NATIVE_MONUMENT_KEY = "minecraft:monument";
     private static final WrappedField<ChunkGenerator, BiomeSource> BIOME_SOURCE;
     private static final WrappedReturningMethod<Heightmap, Object> SET_HEIGHT;
     private final ChunkGenerator delegate;
@@ -109,74 +111,83 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
 
     @Override
     public @Nullable Pair<BlockPos, Holder<Structure>> findNearestMapStructure(ServerLevel level, HolderSet<Structure> holders, BlockPos pos, int radius, boolean findUnexplored) {
-        try {
-            Registry<Structure> registry = level.registryAccess().lookupOrThrow(Registries.STRUCTURE);
-            BlockPos best = null;
-            Holder<Structure> bestHolder = null;
-            long bestDist = Long.MAX_VALUE;
-            for (Holder<Structure> holder : holders) {
-                Object id = registry.getKey(holder.value());
-                if (id == null) {
-                    continue;
-                }
-                IrisStructureLocator.LocateResult result = IrisStructureLocator.locate(
-                        engine, id.toString(), pos.getX(), pos.getZ(), Math.max(1, radius));
-                if (result.status() == IrisStructureLocator.LocateStatus.SEARCH_LIMIT_REACHED) {
-                    continue;
-                }
-                if (!result.found()) {
-                    continue;
-                }
-                long dx = (long) result.originX() - pos.getX();
-                long dz = (long) result.originZ() - pos.getZ();
-                long d = dx * dx + dz * dz;
-                if (d < bestDist) {
-                    bestDist = d;
-                    best = new BlockPos(result.originX(), result.baseY(), result.originZ());
-                    bestHolder = holder;
-                }
-            }
-            if (best != null) {
-                return Pair.of(best, bestHolder);
-            }
-        } catch (Throwable e) {
-            IrisLogging.reportError("Iris-placed structure lookup failed near "
-                    + pos.getX() + ", " + pos.getZ() + ".", e);
-        }
-        if (!importedControl().active()) {
-            return null;
-        }
+        Pair<BlockPos, Holder<Structure>> irisPlaced = findNearestIrisStructure(
+                level, holders, pos, Math.max(1, radius), findUnexplored);
         HolderSet<Structure> reachable = filterReachableStructures(level, holders);
-        if (reachable == null || reachable.size() == 0) {
-            return null;
-        }
-        try {
-            return delegate.findNearestMapStructure(level, reachable, pos, radius, findUnexplored);
-        } catch (Throwable e) {
-            IrisLogging.reportError("Vanilla structure locate failed near "
-                    + pos.getX() + ", " + pos.getZ() + ".", e);
-            return null;
-        }
+        Pair<BlockPos, Holder<Structure>> nativeLocated = reachable == null || reachable.size() == 0
+                ? null
+                : delegate.findNearestMapStructure(level, reachable, pos, radius, findUnexplored);
+        return NativeStructureLocateResults.nearest(pos, irisPlaced, nativeLocated);
     }
 
-    private HolderSet<Structure> filterReachableStructures(ServerLevel level, HolderSet<Structure> holders) {
-        Set<String> reachable = reachableStructureKeys(level);
-        IrisImportedStructureControl control = importedControl();
+    private Pair<BlockPos, Holder<Structure>> findNearestIrisStructure(ServerLevel level,
+                                                                       HolderSet<Structure> holders,
+                                                                       BlockPos pos, int radius,
+                                                                       boolean findUnexplored) {
+        if (findUnexplored) {
+            return null;
+        }
         Registry<Structure> registry = level.registryAccess().lookupOrThrow(Registries.STRUCTURE);
-        List<Holder<Structure>> kept = new ArrayList<>(holders.size());
+        BlockPos best = null;
+        Holder<Structure> bestHolder = null;
+        long bestDist = Long.MAX_VALUE;
         for (Holder<Structure> holder : holders) {
             Object id = registry.getKey(holder.value());
             if (id == null) {
+                throw new IllegalStateException("Native structure locate received an unregistered structure holder");
+            }
+            String structureId = id.toString();
+            IrisNativeStructureDecision decision = NativeStructureGenerationPolicy.resolve(engine,
+                    structureId, NativeStructurePostProcessor.isUndergroundStep(holder.value().step()));
+            if (decision.status() != NativeStructureGenerationStatus.REPLACED_BY_IRIS) {
                 continue;
             }
+            IrisStructureLocator.LocateResult result = IrisStructureLocator.locate(
+                    engine, structureId, pos.getX(), pos.getZ(), radius);
+            if (result.status() == IrisStructureLocator.LocateStatus.SEARCH_LIMIT_REACHED) {
+                throw new IllegalStateException("Iris structure locate reached its safety limit for "
+                        + structureId + " within " + radius + " chunks");
+            }
+            if (!result.found()) {
+                continue;
+            }
+            long dx = (long) result.originX() - pos.getX();
+            long dz = (long) result.originZ() - pos.getZ();
+            long d = dx * dx + dz * dz;
+            if (d < bestDist) {
+                bestDist = d;
+                best = new BlockPos(result.originX(), result.baseY(), result.originZ());
+                bestHolder = holder;
+            }
+        }
+        return best == null ? null : Pair.of(best, bestHolder);
+    }
+
+    private HolderSet<Structure> filterReachableStructures(ServerLevel level, HolderSet<Structure> holders) {
+        Registry<Structure> registry = level.registryAccess().lookupOrThrow(Registries.STRUCTURE);
+        List<NativeLocateCandidate> candidates = new ArrayList<>(holders.size());
+        for (Holder<Structure> holder : holders) {
+            Object id = registry.getKey(holder.value());
+            if (id == null) {
+                throw new IllegalStateException("Native structure filtering received an unregistered structure holder");
+            }
             String key = id.toString();
-            IrisNativeStructureDecision decision = control.resolve(
+            IrisNativeStructureDecision decision = NativeStructureGenerationPolicy.resolve(engine,
                     key, NativeStructurePostProcessor.isUndergroundStep(holder.value().step()));
-            if (NATIVE_MONUMENT_KEY.equals(key) || !decision.generate()
-                    || IrisStructureLocator.suppressesVanilla(engine, key) || !reachable.contains(key)) {
+            if (NativeStructureLocateCapability.isPaperUnavailable(key) || !decision.generate()) {
                 continue;
             }
-            kept.add(holder);
+            candidates.add(new NativeLocateCandidate(holder, key));
+        }
+        if (candidates.isEmpty()) {
+            return HolderSet.direct(List.of());
+        }
+        Set<String> reachable = reachableStructureKeys(level);
+        List<Holder<Structure>> kept = new ArrayList<>(candidates.size());
+        for (NativeLocateCandidate candidate : candidates) {
+            if (reachable.contains(candidate.key())) {
+                kept.add(candidate.holder());
+            }
         }
         if (kept.size() == holders.size()) {
             return holders;
@@ -195,14 +206,8 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
             if (cached != null && cached.dimension() == dimension) {
                 return cached.keys();
             }
-            Set<String> reachable;
-            try {
-                reachable = Set.copyOf(VanillaStructureBiomes.reachableStructureKeys(level, customBiomeSource));
-            } catch (Throwable error) {
-                IrisLogging.reportError("Iris could not resolve native structure biome reachability; "
-                        + "native locate is disabled until the next hotload.", error);
-                reachable = Set.of();
-            }
+            Set<String> reachable = Set.copyOf(
+                    VanillaStructureBiomes.reachableStructureKeys(level, customBiomeSource));
             reachableStructureCache = new ReachableStructureCache(dimension, reachable);
             return reachable;
         }
@@ -232,9 +237,6 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
 
     @Override
     public void createStructures(RegistryAccess registryAccess, ChunkGeneratorStructureState structureState, StructureManager structureManager, ChunkAccess access, StructureTemplateManager templateManager, ResourceKey<Level> levelKey) {
-        if (!importedControl().active()) {
-            return;
-        }
         Map<Structure, StructureStart> previousStarts = new HashMap<>(access.getAllStarts());
         super.createStructures(registryAccess, structureState, structureManager, access, templateManager, levelKey);
         adjustGeneratedStructures(registryAccess, access, previousStarts);
@@ -242,7 +244,7 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
 
     private void adjustGeneratedStructures(RegistryAccess registryAccess, ChunkAccess access, Map<Structure, StructureStart> previousStarts) {
         Registry<Structure> registry = registryAccess.lookupOrThrow(Registries.STRUCTURE);
-        IrisImportedStructureControl control = importedControl();
+        ChunkPos chunkPos = access.getPos();
         for (Map.Entry<Structure, StructureStart> entry : access.getAllStarts().entrySet()) {
             Structure structure = entry.getKey();
             StructureStart start = entry.getValue();
@@ -251,32 +253,40 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
             }
             Identifier id = registry.getKey(structure);
             String structureId = id == null ? null : id.toString();
-            IrisNativeStructureDecision decision = control.resolve(
-                    structureId, NativeStructurePostProcessor.isUndergroundStep(structure.step()));
-            if (!decision.generate() || IrisStructureLocator.suppressesVanilla(engine, structureId)) {
+            if (structureId == null) {
+                throw NativeStructureGenerationException.failure(
+                        "resolution", null, chunkPos.x(), chunkPos.z());
+            }
+            boolean undergroundStep = NativeStructurePostProcessor.isUndergroundStep(structure.step());
+            IrisNativeStructureDecision decision;
+            try {
+                decision = NativeStructureGenerationPolicy.resolve(engine,
+                        structureId, undergroundStep);
+            } catch (Throwable error) {
+                throw NativeStructureGenerationException.failure(
+                        "policy resolution", structureId, chunkPos.x(), chunkPos.z(), error);
+            }
+            if (!decision.generate()) {
                 access.setStartForStructure(structure, StructureStart.INVALID_START);
                 continue;
             }
             try {
-                NativeStructurePostProcessor.applyVerticalShift(
+                NativeStructurePostProcessor.applyVerticalPlacement(
                         start,
+                        structureId,
                         decision.yShift(),
+                        getSeaLevel(),
                         access.getMinY(),
-                        access.getMinY() + access.getHeight());
-            } catch (RuntimeException error) {
-                access.setStartForStructure(structure, StructureStart.INVALID_START);
-                IrisLogging.reportError("Iris rejected native structure " + structureId + " in chunk "
-                        + access.getPos().x() + "," + access.getPos().z()
-                        + " because its vertical bounds are invalid.", error);
-                continue;
+                        access.getMinY() + access.getHeight(),
+                        undergroundStep,
+                        (x, z) -> engine.getHeight(x, z, true) + engine.getMinHeight());
+            } catch (Throwable error) {
+                throw NativeStructureGenerationException.failure(
+                        "vertical adjustment", structureId, chunkPos.x(), chunkPos.z(), error);
             }
         }
     }
 
-    private IrisImportedStructureControl importedControl() {
-        return engine.getDimension().getImportedStructures();
-    }
-
     @Override
     public ChunkGeneratorStructureState createState(HolderLookup<StructureSet> holderlookup, RandomState randomstate, long i, SpigotWorldConfig conf) {
         return delegate.createState(holderlookup, randomstate, i, conf);
@@ -347,15 +357,17 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
     @Override
     public void applyBiomeDecoration(WorldGenLevel generatoraccessseed, ChunkAccess ichunkaccess, StructureManager structuremanager, boolean vanilla) {
         addVanillaDecorations(generatoraccessseed, ichunkaccess, structuremanager);
-        if (importedControl().active()) {
-            placeVanillaStructures(generatoraccessseed, ichunkaccess, structuremanager);
-        }
+        placeVanillaStructures(generatoraccessseed, ichunkaccess, structuremanager);
         delegate.applyBiomeDecoration(generatoraccessseed, ichunkaccess, structuremanager, false);
     }
 
     private void placeVanillaStructures(WorldGenLevel world, ChunkAccess chunk, StructureManager structureManager) {
         if (!structureManager.shouldGenerateStructures()) {
-            return;
+            ChunkPos disabledChunk = chunk.getPos();
+            throw new IllegalStateException("Iris cannot generate native structures in chunk "
+                    + disabledChunk.x() + "," + disabledChunk.z()
+                    + " because structure generation is disabled outside the pack; enable native structure generation "
+                    + "and deny individual structures through importedStructures.disabled");
         }
         ChunkPos chunkPos = chunk.getPos();
         SectionPos sectionPos = SectionPos.of(chunkPos, world.getMinSectionY());
@@ -366,42 +378,60 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
         long decoSeed = random.setDecorationSeed(world.getSeed(), origin.getX(), origin.getZ());
         BoundingBox area = writableArea(chunk);
         int steps = GenerationStep.Decoration.values().length;
-        IrisImportedStructureControl control = importedControl();
         List<NativePlacementGroup> placementGroups = new ArrayList<>();
+        List<StructureStart> nativeStarts = new ArrayList<>();
         List<NativeStructurePostProcessor.VegetationTarget> vegetationTargets = new ArrayList<>();
         for (int step = 0; step < steps; step++) {
             int index = 0;
             for (Structure structure : byStep.get(step)) {
                 Object id = registry.getKey(structure);
                 String structureId = id == null ? null : id.toString();
-                IrisNativeStructureDecision decision = control.resolve(
-                        structureId, NativeStructurePostProcessor.isUndergroundStep(structure.step()));
-                if (decision.generate() && !IrisStructureLocator.suppressesVanilla(engine, structureId)) {
-                    try {
+                if (structureId == null) {
+                    throw NativeStructureGenerationException.failure(
+                            "resolution", null, chunkPos.x(), chunkPos.z());
+                }
+                try {
+                    IrisNativeStructureDecision decision = NativeStructureGenerationPolicy.resolve(engine,
+                            structureId, NativeStructurePostProcessor.isUndergroundStep(structure.step()));
+                    if (decision.generate()) {
                         List<StructureStart> starts = structureManager.startsForStructure(sectionPos, structure);
                         if (!starts.isEmpty()) {
                             List<StructureStart> resolvedStarts = List.copyOf(starts);
                             placementGroups.add(new NativePlacementGroup(
                                     structureId, decision, index, step, resolvedStarts));
+                            nativeStarts.addAll(resolvedStarts);
+                            boolean clearEntireFootprint = NativeStructurePostProcessor
+                                    .shouldClearEntireVegetationFootprint(
+                                            structure.step(), decision.clearVegetation());
                             for (StructureStart start : resolvedStarts) {
                                 vegetationTargets.add(new NativeStructurePostProcessor.VegetationTarget(
-                                        start, decision.clearVegetation()));
+                                        start, clearEntireFootprint));
                             }
                         }
-                    } catch (Throwable e) {
-                        IrisLogging.reportError("Iris failed to resolve native structure " + structureId
-                                + " in chunk " + chunkPos.x() + "," + chunkPos.z() + ".", e);
                     }
+                } catch (Throwable error) {
+                    throw NativeStructureGenerationException.failure(
+                            "resolution", structureId, chunkPos.x(), chunkPos.z(), error);
                 }
                 index++;
             }
         }
+        try {
+            NativeStructurePostProcessor.prepareSurfaceStructures(
+                    world, area, nativeStarts,
+                    (x, z) -> engine.getHeight(x, z, true) + engine.getMinHeight());
+        } catch (Throwable error) {
+            throw NativeStructureGenerationException.failure(
+                    "terrain integration", nativeStructureBatchContext(placementGroups),
+                    chunkPos.x(), chunkPos.z(), error);
+        }
         try {
             NativeStructurePostProcessor.clearIntersectingVegetation(
                     world, chunk, area, vegetationTargets);
-        } catch (Throwable e) {
-            IrisLogging.reportError("Iris failed to clear vegetation from native structures in chunk "
-                    + chunkPos.x() + "," + chunkPos.z() + ".", e);
+        } catch (Throwable error) {
+            throw NativeStructureGenerationException.failure(
+                    "vegetation cleanup", nativeStructureBatchContext(placementGroups),
+                    chunkPos.x(), chunkPos.z(), error);
         }
         for (NativePlacementGroup group : placementGroups) {
             random.setFeatureSeed(decoSeed, group.featureIndex(), group.step());
@@ -410,13 +440,27 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
                     placeVanillaStructure(world, structureManager, random, area, chunkPos,
                             group.structureId(), start, group.decision());
                 }
-            } catch (Throwable e) {
-                IrisLogging.reportError("Iris failed to place native structure " + group.structureId()
-                        + " in chunk " + chunkPos.x() + "," + chunkPos.z() + ".", e);
+            } catch (Throwable error) {
+                throw NativeStructureGenerationException.failure(
+                        "placement", group.structureId(), chunkPos.x(), chunkPos.z(), error);
             }
         }
     }
 
+    private static String nativeStructureBatchContext(List<NativePlacementGroup> placementGroups) {
+        if (placementGroups.isEmpty()) {
+            return "<no resolved native structures>";
+        }
+        StringBuilder context = new StringBuilder("[");
+        for (int i = 0; i < placementGroups.size(); i++) {
+            if (i > 0) {
+                context.append(", ");
+            }
+            context.append(placementGroups.get(i).structureId());
+        }
+        return context.append(']').toString();
+    }
+
     private void placeVanillaStructure(WorldGenLevel world, StructureManager structureManager, WorldgenRandom random,
                                        BoundingBox area, ChunkPos chunkPos, String structureId, StructureStart start,
                                        IrisNativeStructureDecision decision) {
@@ -451,13 +495,14 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
         }
     }
 
-    private BlockState resolveStiltBlock(IrisVanillaStructureStiltSettings settings, RNG rng, int x, int y, int z) {
+    private BlockState resolveStiltBlock(IrisStructureStiltSettings settings, RNG rng, int x, int y, int z) {
         if (settings.getPalette() == null) {
             return Blocks.COBBLESTONE.defaultBlockState();
         }
         PlatformBlockState platformState = settings.getPalette().get(rng, x, y, z, engine.getData());
         if (platformState == null || !(platformState.nativeHandle() instanceof BlockData blockData)) {
-            return Blocks.COBBLESTONE.defaultBlockState();
+            throw new IllegalStateException("Configured native structure stilt palette did not resolve a Bukkit block at "
+                    + x + "," + y + "," + z);
         }
         if (blockData instanceof IrisCustomData customData) {
             blockData = customData.getBase();
@@ -465,7 +510,8 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
         if (blockData instanceof CraftBlockData craftBlockData) {
             return craftBlockData.getState();
         }
-        return Blocks.COBBLESTONE.defaultBlockState();
+        throw new IllegalStateException("Configured native structure stilt palette resolved unsupported Bukkit block data "
+                + blockData.getClass().getName() + " at " + x + "," + y + "," + z);
     }
 
     private BoundingBox writableArea(ChunkAccess chunk) {
@@ -616,4 +662,7 @@ public class IrisChunkGenerator extends CustomChunkGenerator {
     private record NativePlacementGroup(String structureId, IrisNativeStructureDecision decision,
                                         int featureIndex, int step, List<StructureStart> starts) {
     }
+
+    private record NativeLocateCandidate(Holder<Structure> holder, String key) {
+    }
 }

adapters/bukkit/nms/v26_2_R1/src/main/java/art/arcane/iris/core/nms/v26_2_R1/NMSBinding.java

@@ -15,6 +15,7 @@ import art.arcane.iris.engine.data.chunk.TerrainChunk;
 import art.arcane.iris.engine.framework.Engine;
 import art.arcane.iris.engine.object.IrisDimensionRuntimeContract;
 import art.arcane.iris.engine.platform.PlatformChunkGenerator;
+import art.arcane.iris.nativegen.NativeStructureGenerationException;
 import art.arcane.iris.util.project.agent.Agent;
 import art.arcane.volmlib.util.collection.KList;
 import art.arcane.volmlib.util.collection.KMap;
@@ -396,6 +397,11 @@ public class NMSBinding implements INMSBinding {
         return true;
     }
 
+    @Override
+    public boolean supportsIrisWorldGeneration() {
+        return true;
+    }
+
     @Override
     public int getTrueBiomeBaseId(Object biomeBase) {
         return getCustomBiomeRegistry().getId(((Holder<net.minecraft.world.level.biome.Biome>) biomeBase).value());
@@ -470,8 +476,8 @@ public class NMSBinding implements INMSBinding {
         KList<String> keys = new KList<>();
         try {
             registry().lookupOrThrow(Registries.STRUCTURE).keySet().forEach(k -> keys.add(k.toString()));
-        } catch (Throwable e) {
-            IrisLogging.reportError(e);
+        } catch (RuntimeException e) {
+            throw new IllegalStateException("Iris failed to read registered structure keys from the Minecraft registry", e);
         }
         return keys;
     }
@@ -481,8 +487,8 @@ public class NMSBinding implements INMSBinding {
         KList<String> keys = new KList<>();
         try {
             registry().lookupOrThrow(Registries.STRUCTURE_SET).keySet().forEach(k -> keys.add(k.toString()));
-        } catch (Throwable e) {
-            IrisLogging.reportError(e);
+        } catch (RuntimeException e) {
+            throw new IllegalStateException("Iris failed to read registered structure-set keys from the Minecraft registry", e);
         }
         return keys;
     }
@@ -494,8 +500,9 @@ public class NMSBinding implements INMSBinding {
             ServerLevel level = ((CraftWorld) world).getHandle();
             BiomeSource source = level.getChunkSource().getGenerator().getBiomeSource();
             keys.addAll(VanillaStructureBiomes.reachableStructureKeys(level, source));
-        } catch (Throwable e) {
-            IrisLogging.reportError(e);
+        } catch (RuntimeException e) {
+            throw new IllegalStateException("Iris failed to resolve reachable structures for Bukkit world '"
+                    + (world == null ? "<null>" : world.getName()) + "'", e);
         }
         return keys;
     }
@@ -504,9 +511,14 @@ public class NMSBinding implements INMSBinding {
     public KList<String> getStructureBiomeKeys(String structureKey) {
         KList<String> keys = new KList<>();
         try {
-            keys.addAll(VanillaStructureBiomes.structureBiomeKeys(registry(), structureKey));
-        } catch (Throwable e) {
-            IrisLogging.reportError(e);
+            RegistryAccess access = registry();
+            if (access == null) {
+                throw new IllegalStateException("Minecraft registry access is unavailable");
+            }
+            keys.addAll(VanillaStructureBiomes.structureBiomeKeys(access, structureKey));
+        } catch (RuntimeException e) {
+            throw new IllegalStateException("Iris failed to resolve biome keys for registered structure '"
+                    + structureKey + "'", e);
         }
         return keys;
     }
@@ -518,8 +530,9 @@ public class NMSBinding implements INMSBinding {
             ServerLevel level = ((CraftWorld) world).getHandle();
             BiomeSource source = level.getChunkSource().getGenerator().getBiomeSource();
             keys.addAll(VanillaStructureBiomes.possibleBiomeKeys(source));
-        } catch (Throwable e) {
-            IrisLogging.reportError(e);
+        } catch (RuntimeException e) {
+            throw new IllegalStateException("Iris failed to resolve possible structure biome keys for Bukkit world '"
+                    + (world == null ? "<null>" : world.getName()) + "'", e);
         }
         return keys;
     }
@@ -636,9 +649,9 @@ public class NMSBinding implements INMSBinding {
                 }
             }
             return new int[]{box.minX(), box.minY(), box.minZ(), box.maxX(), box.maxY(), box.maxZ()};
-        } catch (Throwable e) {
-            IrisLogging.reportError(e);
-            return null;
+        } catch (RuntimeException e) {
+            throw NativeStructureGenerationException.failure(
+                    "capture placement", structureKey, chunkX, chunkZ, e);
         }
     }
 

adapters/bukkit/nms/v26_2_R1/src/main/java/art/arcane/iris/core/nms/v26_2_R1/VanillaStructureBiomes.java

@@ -21,10 +21,10 @@ final class VanillaStructureBiomes {
     }
 
     static Set<String> possibleBiomeKeys(BiomeSource source) {
-        Set<String> keys = new LinkedHashSet<>();
         if (source == null) {
-            return keys;
+            throw new IllegalStateException("Minecraft chunk generator has no biome source");
         }
+        Set<String> keys = new LinkedHashSet<>();
         Set<Holder<Biome>> possibleBiomes = source instanceof CustomBiomeSource customBiomeSource
                 ? customBiomeSource.possibleStructureBiomes()
                 : source.possibleBiomes();
@@ -34,18 +34,24 @@ final class VanillaStructureBiomes {
                 keys.add(key.get().identifier().toString());
             }
         }
+        if (keys.isEmpty()) {
+            throw new IllegalStateException("Minecraft biome source exposes no registered possible biomes");
+        }
         return keys;
     }
 
     static Set<String> structureBiomeKeys(RegistryAccess access, String structureKey) {
-        Set<String> keys = new LinkedHashSet<>();
-        if (access == null || structureKey == null || structureKey.isEmpty()) {
-            return keys;
+        if (access == null) {
+            throw new IllegalStateException("Minecraft registry access is unavailable");
         }
+        if (structureKey == null || structureKey.isBlank()) {
+            throw new IllegalArgumentException("Registered structure key must not be blank");
+        }
+        Set<String> keys = new LinkedHashSet<>();
         Registry<Structure> registry = access.lookupOrThrow(Registries.STRUCTURE);
         Structure structure = registry.getValue(Identifier.parse(structureKey));
         if (structure == null) {
-            return keys;
+            throw new IllegalArgumentException("Registered structure does not exist: " + structureKey);
         }
         for (Holder<Biome> holder : structure.biomes()) {
             Optional<ResourceKey<Biome>> key = holder.unwrapKey();
@@ -53,18 +59,19 @@ final class VanillaStructureBiomes {
                 keys.add(key.get().identifier().toString());
             }
         }
+        if (keys.isEmpty()) {
+            throw new IllegalStateException("Registered structure '" + structureKey
+                    + "' exposes no registered biome keys");
+        }
         return keys;
     }
 
     static Set<String> reachableStructureKeys(ServerLevel level, BiomeSource source) {
+        if (level == null) {
+            throw new IllegalStateException("Minecraft server level is unavailable");
+        }
         Set<String> reachable = new LinkedHashSet<>();
-        if (level == null || source == null) {
-            return reachable;
-        }
         Set<String> possible = possibleBiomeKeys(source);
-        if (possible.isEmpty()) {
-            return reachable;
-        }
         Registry<Structure> registry = level.registryAccess().lookupOrThrow(Registries.STRUCTURE);
         for (Map.Entry<ResourceKey<Structure>, Structure> entry : registry.entrySet()) {
             for (Holder<Biome> holder : entry.getValue().biomes()) {

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/core/nms/v26_2_R1/IrisChunkGeneratorFailureContractTest.java

@@ -0,0 +1,57 @@
+package art.arcane.iris.core.nms.v26_2_R1;
+
+import org.junit.Test;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class IrisChunkGeneratorFailureContractTest {
+    @Test
+    public void structureLocateDoesNotCatchAndFallThroughToAnotherImplementation() throws IOException {
+        String source = Files.readString(Path.of(System.getProperty("iris.nmsChunkGeneratorSource")));
+        int locateStart = source.indexOf("public @Nullable Pair<BlockPos, Holder<Structure>> findNearestMapStructure");
+        int locateEnd = source.indexOf("private HolderSet<Structure> filterReachableStructures", locateStart);
+        String locate = source.substring(locateStart, locateEnd);
+        int reachabilityStart = source.indexOf("private Set<String> reachableStructureKeys");
+        int reachabilityEnd = source.indexOf("protected MapCodec", reachabilityStart);
+        String reachability = source.substring(reachabilityStart, reachabilityEnd);
+
+        assertTrue(locate.contains("reached its safety limit"));
+        assertTrue(locate.contains("unregistered structure holder"));
+        assertFalse(locate.contains("catch (Throwable"));
+        assertFalse(locate.contains("IrisLogging.reportError"));
+        assertFalse(reachability.contains("catch (Throwable"));
+        assertFalse(reachability.contains("reachable = Set.of()"));
+    }
+
+    @Test
+    public void structureGenerationAbortsInsteadOfLoggingAndContinuing() throws IOException {
+        String source = Files.readString(Path.of(System.getProperty("iris.nmsChunkGeneratorSource")));
+        int adjustmentStart = source.indexOf("private void adjustGeneratedStructures");
+        int adjustmentEnd = source.indexOf("public ChunkGeneratorStructureState createState", adjustmentStart);
+        String adjustment = source.substring(adjustmentStart, adjustmentEnd);
+        int placementStart = source.indexOf("private void placeVanillaStructures");
+        int placementEnd = source.indexOf("private void placeVanillaStructure(", placementStart + 1);
+        String placement = source.substring(placementStart, placementEnd);
+
+        assertTrue(adjustment.contains("NativeStructureGenerationException.failure("));
+        assertTrue(adjustment.contains("\"vertical adjustment\""));
+        assertFalse(adjustment.contains("IrisLogging.reportError"));
+        assertTrue(placement.contains("\"resolution\""));
+        assertTrue(placement.contains("\"terrain integration\""));
+        assertTrue(placement.contains("\"vegetation cleanup\""));
+        assertTrue(placement.contains("\"placement\""));
+        assertTrue(placement.contains("because structure generation is disabled outside the pack"));
+        assertTrue(placement.contains("prepareSurfaceStructures"));
+        assertTrue(placement.contains("clearIntersectingVegetation"));
+        assertTrue(placement.indexOf("prepareSurfaceStructures")
+                < placement.indexOf("clearIntersectingVegetation"));
+        assertTrue(placement.indexOf("clearIntersectingVegetation")
+                < placement.indexOf("for (NativePlacementGroup group"));
+        assertFalse(placement.contains("IrisLogging.reportError"));
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/core/nms/v26_2_R1/IrisChunkGeneratorMonumentLocateContractTest.java

@@ -1,5 +1,10 @@
 package art.arcane.iris.core.nms.v26_2_R1;
 
+import art.arcane.iris.nativegen.NativeStructureLocateResults;
+import com.mojang.datafixers.util.Pair;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.world.level.levelgen.structure.Structure;
 import org.junit.Test;
 
 import java.io.IOException;
@@ -8,35 +13,70 @@ import java.nio.file.Path;
 
 import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertSame;
 
 public class IrisChunkGeneratorMonumentLocateContractTest {
     @Test
-    public void irisPlacementRunsBeforeExactNativeMonumentIsRemovedFromDelegateLookup() throws IOException {
+    public void nativeLocateAllowsExplicitReplacementBeforeNativeCapabilityGate() throws IOException {
         String source = Files.readString(Path.of(System.getProperty("iris.nmsChunkGeneratorSource")));
         int findStart = source.indexOf("findNearestMapStructure(ServerLevel level");
         assertTrue(findStart >= 0);
-        int filterStart = source.indexOf("private HolderSet<Structure> filterReachableStructures", findStart);
-        assertTrue(filterStart > findStart);
-        String findMethod = source.substring(findStart, filterStart);
-        int irisLocate = findMethod.indexOf("IrisStructureLocator.locate(");
-        int searchLimit = findMethod.indexOf("LocateStatus.SEARCH_LIMIT_REACHED", irisLocate);
-        int limitSkip = findMethod.indexOf("continue;", searchLimit);
-        int nativeFilter = findMethod.indexOf("filterReachableStructures(level, holders)");
-        int delegateLocate = findMethod.indexOf("delegate.findNearestMapStructure(level, reachable");
+        int irisHelperStart = source.indexOf("private Pair<BlockPos, Holder<Structure>> findNearestIrisStructure(", findStart);
+        int filterStart = source.indexOf("private HolderSet<Structure> filterReachableStructures", irisHelperStart);
+        assertTrue(irisHelperStart > findStart);
+        assertTrue(filterStart > irisHelperStart);
+        String outerMethod = source.substring(findStart, irisHelperStart);
+        String irisHelper = source.substring(irisHelperStart, filterStart);
+        int policyResolution = irisHelper.indexOf("NativeStructureGenerationPolicy.resolve(engine,");
+        int unexploredGuard = irisHelper.indexOf("if (findUnexplored)");
+        int registryLookup = irisHelper.indexOf("level.registryAccess().lookupOrThrow(Registries.STRUCTURE)");
+        int replacementCheck = irisHelper.indexOf(
+                "decision.status() != NativeStructureGenerationStatus.REPLACED_BY_IRIS");
+        int irisLocate = irisHelper.indexOf("IrisStructureLocator.locate(", replacementCheck);
+        int searchLimit = irisHelper.indexOf("LocateStatus.SEARCH_LIMIT_REACHED", irisLocate);
+        int limitSkip = irisHelper.indexOf("continue;", searchLimit);
+        int nativeFilter = outerMethod.indexOf("filterReachableStructures(level, holders)");
+        int delegateLocate = outerMethod.indexOf("delegate.findNearestMapStructure(level, reachable");
+        int nearestSelection = outerMethod.indexOf(
+                "NativeStructureLocateResults.nearest(pos, irisPlaced, nativeLocated)");
         int reachabilityStart = source.indexOf("private Set<String> reachableStructureKeys", filterStart);
         assertTrue(reachabilityStart > filterStart);
         String filterMethod = source.substring(filterStart, reachabilityStart);
-        int monumentReject = filterMethod.indexOf("if (NATIVE_MONUMENT_KEY.equals(key)");
+        int monumentReject = filterMethod.indexOf("if (NativeStructureLocateCapability.isPaperUnavailable(key)");
         int rejectContinue = filterMethod.indexOf("continue;", monumentReject);
+        int emptyNativePartition = filterMethod.indexOf("if (candidates.isEmpty())", rejectContinue);
+        int reachabilityLookup = filterMethod.indexOf("reachableStructureKeys(level)", emptyNativePartition);
 
-        assertTrue(irisLocate >= 0);
+        assertTrue(policyResolution >= 0);
+        assertTrue(unexploredGuard >= 0);
+        assertTrue(registryLookup > unexploredGuard);
+        assertTrue(policyResolution > registryLookup);
+        assertTrue(replacementCheck > policyResolution);
+        assertTrue(irisLocate > replacementCheck);
         assertTrue(searchLimit > irisLocate);
         assertTrue(limitSkip > searchLimit);
-        assertTrue(nativeFilter > limitSkip);
+        assertTrue(nativeFilter >= 0);
         assertTrue(delegateLocate > nativeFilter);
+        assertTrue(nearestSelection > delegateLocate);
         assertTrue(monumentReject >= 0);
         assertTrue(rejectContinue > monumentReject);
-        assertTrue(findMethod.contains("new BlockPos(result.originX(), result.baseY(), result.originZ())"));
+        assertTrue(emptyNativePartition > rejectContinue);
+        assertTrue(reachabilityLookup > emptyNativePartition);
+        assertFalse(irisHelper.contains("NativeStructureLocateCapability.isPaperUnavailable(structureId)"));
+        assertTrue(irisHelper.contains("new BlockPos(result.originX(), result.baseY(), result.originZ())"));
+    }
+
+    @Test
+    public void mixedLocateSelectsNearestProviderAndPrefersNativeOnTie() {
+        BlockPos origin = BlockPos.ZERO;
+        Pair<BlockPos, Holder<Structure>> irisNear = Pair.of(new BlockPos(4, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeFar = Pair.of(new BlockPos(8, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeNear = Pair.of(new BlockPos(2, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeTie = Pair.of(new BlockPos(0, 70, 4), null);
+
+        assertSame(irisNear, NativeStructureLocateResults.nearest(origin, irisNear, nativeFar));
+        assertSame(nativeNear, NativeStructureLocateResults.nearest(origin, irisNear, nativeNear));
+        assertSame(nativeTie, NativeStructureLocateResults.nearest(origin, irisNear, nativeTie));
     }
 
     @Test
@@ -54,18 +94,34 @@ public class IrisChunkGeneratorMonumentLocateContractTest {
     }
 
     @Test
-    public void verticalShiftMovesPiecesJigsawJunctionsAndCachedBoundsTogether() throws IOException {
+    public void verticalPlacementMovesPiecesMonumentChildrenJigsawJunctionsAndCachedBoundsTogether() throws IOException {
         String source = Files.readString(Path.of(System.getProperty("iris.nativeStructurePostProcessorSource")));
-        int method = source.indexOf("public static int applyVerticalShift");
-        int clamp = source.indexOf("StructureVerticalBounds.clampOffset", method);
-        int pieceMove = source.indexOf("piece.move(0, offsetY, 0)", clamp);
-        int junctionMove = source.indexOf("junction.getSourceGroundY() + offsetY", pieceMove);
-        int boundsMove = source.indexOf("bounds.move(0, offsetY, 0)", junctionMove);
+        int placementStart = source.indexOf("public static int applyVerticalPlacement");
+        int shiftStart = source.indexOf("public static int applyVerticalShift", placementStart);
+        int alignmentStart = source.indexOf("static int alignOceanMonumentToSeaLevel", shiftStart);
+        int moveStart = source.indexOf("private static void moveStructureStart", alignmentStart);
+        int movePieceStart = source.indexOf("private static void moveStructurePiece", moveStart);
+        int monumentChildrenStart = source.indexOf("static List<StructurePiece> monumentChildPieces", movePieceStart);
 
-        assertTrue(method >= 0);
-        assertTrue(clamp > method);
-        assertTrue(pieceMove > clamp);
-        assertTrue(junctionMove > pieceMove);
-        assertTrue(boundsMove > junctionMove);
+        assertTrue(placementStart >= 0);
+        assertTrue(shiftStart > placementStart);
+        assertTrue(alignmentStart > shiftStart);
+        assertTrue(moveStart > alignmentStart);
+        assertTrue(movePieceStart > moveStart);
+        assertTrue(monumentChildrenStart > movePieceStart);
+        String placementMethod = source.substring(placementStart, shiftStart);
+        String shiftMethod = source.substring(shiftStart, alignmentStart);
+        String moveMethod = source.substring(moveStart, movePieceStart);
+        String movePieceMethod = source.substring(movePieceStart, monumentChildrenStart);
+
+        assertTrue(placementMethod.contains("return alignOceanMonumentToSeaLevel("));
+        assertTrue(placementMethod.contains("return applyVerticalShift("));
+        assertTrue(shiftMethod.contains("StructureVerticalBounds.clampOffset"));
+        assertTrue(shiftMethod.contains("moveStructureStart(start, bounds, offsetY)"));
+        assertTrue(moveMethod.contains("moveStructurePiece(piece, offsetY)"));
+        assertTrue(moveMethod.contains("cachedBounds.move(0, offsetY, 0)"));
+        assertTrue(movePieceMethod.contains("piece.move(0, offsetY, 0)"));
+        assertTrue(movePieceMethod.contains("child.move(0, offsetY, 0)"));
+        assertTrue(movePieceMethod.contains("junction.getSourceGroundY() + offsetY"));
     }
 }

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/core/nms/v26_2_R1/NMSBindingPlacementFailureContractTest.java

@@ -0,0 +1,29 @@
+package art.arcane.iris.core.nms.v26_2_R1;
+
+import org.junit.Test;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NMSBindingPlacementFailureContractTest {
+    @Test
+    public void structurePlacementPropagatesRuntimeFailuresWithContext() throws IOException {
+        Path chunkGeneratorSource = Path.of(System.getProperty("iris.nmsChunkGeneratorSource"));
+        String source = Files.readString(chunkGeneratorSource.resolveSibling("NMSBinding.java"));
+        int methodStart = source.indexOf("public int[] placeStructure(");
+        int methodEnd = source.indexOf("\n    @Override", methodStart + 1);
+        String method = source.substring(methodStart, methodEnd);
+        int catchStart = method.indexOf("catch (RuntimeException e)");
+
+        assertTrue(catchStart >= 0);
+        String failurePath = method.substring(catchStart);
+        assertTrue(failurePath.contains("throw NativeStructureGenerationException.failure("));
+        assertTrue(failurePath.contains("\"capture placement\", structureKey, chunkX, chunkZ, e"));
+        assertFalse(failurePath.contains("return null;"));
+        assertFalse(failurePath.contains("catch (Throwable"));
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/core/nms/v26_2_R1/NMSBindingStructureFailureContractTest.java

@@ -0,0 +1,43 @@
+package art.arcane.iris.core.nms.v26_2_R1;
+
+import org.junit.Test;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NMSBindingStructureFailureContractTest {
+    @Test
+    public void structureRegistryHooksThrowInsteadOfReturningEmptyOnFailure() throws IOException {
+        Path chunkGeneratorSource = Path.of(System.getProperty("iris.nmsChunkGeneratorSource"));
+        String source = Files.readString(chunkGeneratorSource.resolveSibling("NMSBinding.java"));
+        List<String> methodNames = List.of(
+                "getStructureKeys",
+                "getStructureSetKeys",
+                "getReachableStructureKeys",
+                "getStructureBiomeKeys",
+                "getPossibleBiomeKeys");
+
+        for (String methodName : methodNames) {
+            String method = methodSource(source, methodName);
+            assertTrue(methodName + " must preserve failure context", method.contains("throw new IllegalStateException("));
+            assertTrue(methodName + " must retain its root cause", method.contains(", e);"));
+            assertFalse(methodName + " must not log and return an empty registry result",
+                    method.contains("IrisLogging.reportError"));
+            assertFalse(methodName + " must not catch fatal JVM errors", method.contains("catch (Throwable"));
+        }
+    }
+
+    private static String methodSource(String source, String methodName) {
+        int start = source.indexOf("public KList<String> " + methodName + "(");
+        int end = source.indexOf("\n    @Override", start + 1);
+        if (start < 0 || end < 0) {
+            throw new IllegalArgumentException("Unable to find NMS binding method " + methodName);
+        }
+        return source.substring(start, end);
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorMonumentTest.java

@@ -0,0 +1,140 @@
+package art.arcane.iris.nativegen;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Direction;
+import net.minecraft.core.HolderSet;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentPieces;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructurePostProcessorMonumentTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void vanillaSeaLevelKeepsTheVanillaMonumentHeight() {
+        StructureStart start = monumentStart(1337L);
+
+        int offset = NativeStructurePostProcessor.applyVerticalPlacement(
+                start, "minecraft:monument", 0, 63, -64, 320, false, (x, z) -> 0);
+
+        assertEquals(0, offset);
+        assertEquals(39, start.getBoundingBox().minY());
+        assertEquals(61, start.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void shiftedSeaLevelMovesTheShellAndEveryRoomTogether() {
+        StructureStart start = monumentStart(1337L);
+        OceanMonumentPieces.MonumentBuilding building = monumentBuilding(start);
+        List<StructurePiece> children = NativeStructurePostProcessor.monumentChildPieces(building);
+        int[] childMinY = minimumYs(children);
+        BoundingBox cachedBounds = start.getBoundingBox();
+
+        int offset = NativeStructurePostProcessor.applyVerticalPlacement(
+                start, "minecraft:monument", 0, 50, -256, 512, false, (x, z) -> 0);
+
+        assertEquals(-13, offset);
+        assertSame(cachedBounds, start.getBoundingBox());
+        assertEquals(26, building.getBoundingBox().minY());
+        assertEquals(48, building.getBoundingBox().maxY());
+        assertEquals(26, start.getBoundingBox().minY());
+        assertEquals(48, start.getBoundingBox().maxY());
+        assertTrue(children.size() > 20);
+        for (int i = 0; i < children.size(); i++) {
+            assertEquals(childMinY[i] - 13, children.get(i).getBoundingBox().minY());
+        }
+
+        int repeatedOffset = NativeStructurePostProcessor.applyVerticalPlacement(
+                start, "minecraft:monument", 0, 50, -256, 512, false, (x, z) -> 0);
+        assertEquals(0, repeatedOffset);
+    }
+
+    @Test
+    public void configuredOffsetIsRelativeToTheActualSeaLevel() {
+        StructureStart start = monumentStart(1337L);
+
+        int offset = NativeStructurePostProcessor.applyVerticalPlacement(
+                start, "minecraft:monument", 3, 50, -256, 512, false, (x, z) -> 0);
+
+        assertEquals(-10, offset);
+        assertEquals(29, start.getBoundingBox().minY());
+        assertEquals(51, start.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void vanillaReloadRegenerationIsRealignedBeforePlacement() {
+        long seed = 1337L;
+        ChunkPos chunkPos = new ChunkPos(0, 0);
+        StructureStart initial = monumentStart(seed);
+        NativeStructurePostProcessor.applyVerticalPlacement(
+                initial, "minecraft:monument", 0, 50, -256, 512, false, (x, z) -> 0);
+
+        PiecesContainer regenerated = OceanMonumentStructure.regeneratePiecesAfterLoad(
+                chunkPos, seed, new PiecesContainer(initial.getPieces()));
+        StructureStart reloaded = new StructureStart(
+                monumentStructure(), chunkPos, 0, regenerated);
+
+        assertEquals(39, reloaded.getBoundingBox().minY());
+        int offset = NativeStructurePostProcessor.applyVerticalPlacement(
+                reloaded, "minecraft:monument", 0, 50, -256, 512, false, (x, z) -> 0);
+        assertEquals(-13, offset);
+        assertEquals(26, reloaded.getBoundingBox().minY());
+        assertEquals(48, reloaded.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void impossibleSeaLevelAlignmentFailsInsteadOfClippingTheMonument() {
+        StructureStart start = monumentStart(1337L);
+        try {
+            NativeStructurePostProcessor.applyVerticalPlacement(
+                    start, "minecraft:monument", 0, -50, -64, 320, false, (x, z) -> 0);
+        } catch (IllegalStateException error) {
+            assertTrue(error.getMessage().contains("cannot align"));
+            return;
+        }
+        throw new AssertionError("Expected an out-of-bounds monument alignment to fail");
+    }
+
+    private static StructureStart monumentStart(long seed) {
+        ChunkPos chunkPos = new ChunkPos(0, 0);
+        OceanMonumentPieces.MonumentBuilding building = new OceanMonumentPieces.MonumentBuilding(
+                RandomSource.create(seed), -29, -29, Direction.NORTH);
+        return new StructureStart(
+                monumentStructure(), chunkPos, 0, new PiecesContainer(List.of(building)));
+    }
+
+    private static OceanMonumentStructure monumentStructure() {
+        return new OceanMonumentStructure(new Structure.StructureSettings(HolderSet.empty()));
+    }
+
+    private static OceanMonumentPieces.MonumentBuilding monumentBuilding(StructureStart start) {
+        return (OceanMonumentPieces.MonumentBuilding) start.getPieces().get(0);
+    }
+
+    private static int[] minimumYs(List<StructurePiece> pieces) {
+        int[] ys = new int[pieces.size()];
+        for (int i = 0; i < pieces.size(); i++) {
+            ys[i] = pieces.get(i).getBoundingBox().minY();
+        }
+        return ys;
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorSurfaceTerrainTest.java

@@ -0,0 +1,327 @@
+package art.arcane.iris.nativegen;
+
+import com.mojang.datafixers.util.Either;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.levelgen.GenerationStep;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.TerrainAdjustment;
+import net.minecraft.world.level.levelgen.structure.pools.SinglePoolElement;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructurePlaceSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplate;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.Field;
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Modifier;
+import java.lang.reflect.Proxy;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructurePostProcessorSurfaceTerrainTest {
+    @BeforeClass
+    public static void bootstrapMinecraft() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void onlySurfaceBeardThinStructuresPrepareTerrain() {
+        assertTrue(NativeStructurePostProcessor.shouldPrepareSurfaceTerrain(
+                TerrainAdjustment.BEARD_THIN, GenerationStep.Decoration.SURFACE_STRUCTURES));
+        assertFalse(NativeStructurePostProcessor.shouldPrepareSurfaceTerrain(
+                TerrainAdjustment.BURY, GenerationStep.Decoration.SURFACE_STRUCTURES));
+        assertFalse(NativeStructurePostProcessor.shouldPrepareSurfaceTerrain(
+                TerrainAdjustment.BEARD_BOX, GenerationStep.Decoration.SURFACE_STRUCTURES));
+        assertFalse(NativeStructurePostProcessor.shouldPrepareSurfaceTerrain(
+                TerrainAdjustment.ENCAPSULATE, GenerationStep.Decoration.SURFACE_STRUCTURES));
+    }
+
+    @Test
+    public void undergroundAdjustmentsNeverPrepareSurfaceTerrain() {
+        for (TerrainAdjustment adjustment : List.of(
+                TerrainAdjustment.BEARD_THIN,
+                TerrainAdjustment.BURY,
+                TerrainAdjustment.BEARD_BOX,
+                TerrainAdjustment.ENCAPSULATE)) {
+            assertFalse(NativeStructurePostProcessor.shouldPrepareSurfaceTerrain(
+                    adjustment, GenerationStep.Decoration.UNDERGROUND_STRUCTURES));
+        }
+    }
+
+    @Test
+    public void surfaceAnchorIsFlushInsideAndUnchangedAtRadius() {
+        NativeStructurePostProcessor.SurfaceAnchor anchor = anchor(80, 2);
+
+        assertEquals(80, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(anchor), 2, 2, 64));
+        assertEquals(64, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(anchor), 16, 2, 64));
+        assertEquals(64, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(anchor), 17, 2, 64));
+    }
+
+    @Test
+    public void surfaceAnchorRaisesAndLowersThroughTheTaper() {
+        NativeStructurePostProcessor.SurfaceAnchor raised = anchor(80, 2);
+        NativeStructurePostProcessor.SurfaceAnchor lowered = anchor(64, 2);
+
+        assertEquals(68, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(raised), 10, 2, 64));
+        assertEquals(76, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(lowered), 10, 2, 80));
+    }
+
+    @Test
+    public void containingRigidFloorsHaveDeterministicPriority() {
+        NativeStructurePostProcessor.SurfaceAnchor rigid = anchor(70, 2);
+        NativeStructurePostProcessor.SurfaceAnchor junction = anchor(90, 1);
+
+        assertEquals(70, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(rigid, junction), 2, 2, 64));
+        assertEquals(70, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(junction, rigid), 2, 2, 64));
+
+        NativeStructurePostProcessor.SurfaceAnchor weakTie = anchor(48, 1);
+        NativeStructurePostProcessor.SurfaceAnchor strongTie = anchor(80, 2);
+        assertEquals(80, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(weakTie, strongTie), 2, 2, 64));
+        assertEquals(80, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(strongTie, weakTie), 2, 2, 64));
+    }
+
+    @Test
+    public void containingFootprintOverridesAnAdjacentPiecesFalloff() {
+        NativeStructurePostProcessor.SurfaceAnchor local =
+                new NativeStructurePostProcessor.SurfaceAnchor(0, 4, 0, 4, 65, 2);
+        NativeStructurePostProcessor.SurfaceAnchor adjacent =
+                new NativeStructurePostProcessor.SurfaceAnchor(5, 9, 0, 4, 80, 2);
+
+        assertEquals(77, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(adjacent), 4, 2, 64));
+        assertEquals(65, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(local, adjacent), 4, 2, 64));
+        assertEquals(65, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(adjacent, local), 4, 2, 64));
+    }
+
+    @Test
+    public void opposingFalloffsBlendWithoutAnAbruptMidpointSeam() {
+        NativeStructurePostProcessor.SurfaceAnchor high =
+                new NativeStructurePostProcessor.SurfaceAnchor(0, 0, 0, 0, 80, 2);
+        NativeStructurePostProcessor.SurfaceAnchor low =
+                new NativeStructurePostProcessor.SurfaceAnchor(12, 12, 0, 0, 48, 2);
+        int previous = NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(high, low), 0, 0, 64);
+
+        for (int x = 1; x <= 12; x++) {
+            int forward = NativeStructurePostProcessor.resolveSurfaceTarget(
+                    List.of(high, low), x, 0, 64);
+            int reversed = NativeStructurePostProcessor.resolveSurfaceTarget(
+                    List.of(low, high), x, 0, 64);
+            assertEquals(forward, reversed);
+            assertTrue(Math.abs(forward - previous) <= 4);
+            previous = forward;
+        }
+        assertEquals(64, NativeStructurePostProcessor.resolveSurfaceTarget(
+                List.of(high, low), 6, 0, 64));
+    }
+
+    @Test
+    public void surfaceColumnsMutateTerrainAndRemoveUnsupportedDecoration() {
+        Map<BlockPos, BlockState> lowered = new HashMap<>();
+        put(lowered, 0, 61, 0, Blocks.STONE.defaultBlockState());
+        put(lowered, 0, 62, 0, Blocks.DIRT.defaultBlockState());
+        put(lowered, 0, 63, 0, Blocks.DIRT.defaultBlockState());
+        put(lowered, 0, 64, 0, Blocks.GRASS_BLOCK.defaultBlockState());
+        put(lowered, 0, 65, 0, Blocks.DANDELION.defaultBlockState());
+
+        NativeStructurePostProcessor.applySurfaceColumn(
+                world(lowered), new BlockPos.MutableBlockPos(),
+                0, 0, 64, 62, -64, 319);
+
+        assertEquals(Blocks.STONE.defaultBlockState(), state(lowered, 0, 61, 0));
+        assertEquals(Blocks.GRASS_BLOCK.defaultBlockState(), state(lowered, 0, 62, 0));
+        assertEquals(Blocks.AIR.defaultBlockState(), state(lowered, 0, 63, 0));
+        assertEquals(Blocks.AIR.defaultBlockState(), state(lowered, 0, 64, 0));
+        assertEquals(Blocks.AIR.defaultBlockState(), state(lowered, 0, 65, 0));
+
+        Map<BlockPos, BlockState> raised = new HashMap<>();
+        put(raised, 0, 63, 0, Blocks.DIRT.defaultBlockState());
+        put(raised, 0, 64, 0, Blocks.GRASS_BLOCK.defaultBlockState());
+        put(raised, 0, 65, 0, Blocks.DANDELION.defaultBlockState());
+
+        NativeStructurePostProcessor.applySurfaceColumn(
+                world(raised), new BlockPos.MutableBlockPos(),
+                0, 0, 64, 68, -64, 319);
+
+        assertEquals(Blocks.DIRT.defaultBlockState(), state(raised, 0, 65, 0));
+        assertEquals(Blocks.DIRT.defaultBlockState(), state(raised, 0, 66, 0));
+        assertEquals(Blocks.DIRT.defaultBlockState(), state(raised, 0, 67, 0));
+        assertEquals(Blocks.GRASS_BLOCK.defaultBlockState(), state(raised, 0, 68, 0));
+    }
+
+    @Test
+    public void loweredFluidColumnsRemainFluidFilled() {
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        put(blocks, 0, 62, 0, Blocks.DIRT.defaultBlockState());
+        put(blocks, 0, 63, 0, Blocks.DIRT.defaultBlockState());
+        put(blocks, 0, 64, 0, Blocks.GRAVEL.defaultBlockState());
+        put(blocks, 0, 65, 0, Blocks.WATER.defaultBlockState());
+
+        NativeStructurePostProcessor.applySurfaceColumn(
+                world(blocks), new BlockPos.MutableBlockPos(),
+                0, 0, 64, 62, -64, 319);
+
+        assertEquals(Blocks.WATER.defaultBlockState(), state(blocks, 0, 63, 0));
+        assertEquals(Blocks.WATER.defaultBlockState(), state(blocks, 0, 64, 0));
+        assertEquals(Blocks.WATER.defaultBlockState(), state(blocks, 0, 65, 0));
+        assertEquals(Blocks.GRAVEL.defaultBlockState(), state(blocks, 0, 62, 0));
+    }
+
+    @Test
+    public void singlePoolTemplateFieldMatchesTheRuntimeContract() {
+        Field field = NativeStructurePostProcessor.resolveSinglePoolTemplateField();
+
+        assertEquals(SinglePoolElement.class, field.getDeclaringClass());
+        assertEquals(Either.class, field.getType());
+        assertTrue(Modifier.isProtected(field.getModifiers()));
+        assertTrue(Modifier.isFinal(field.getModifiers()));
+        assertFalse(Modifier.isStatic(field.getModifiers()));
+        assertTrue(field.trySetAccessible());
+    }
+
+    @Test
+    public void runtimeTemplatesAndLegacyAirUseTheExactContract() {
+        StructureTemplate runtimeTemplate = new StructureTemplate();
+
+        assertEquals(runtimeTemplate, NativeStructurePostProcessor.resolveTemplateReference(
+                Either.right(runtimeTemplate), null));
+        assertFalse(NativeStructurePostProcessor.shouldClearLegacyAir(79, 80, false));
+        assertTrue(NativeStructurePostProcessor.shouldClearLegacyAir(80, 80, false));
+        assertTrue(NativeStructurePostProcessor.shouldClearLegacyAir(96, 80, false));
+        assertFalse(NativeStructurePostProcessor.shouldClearLegacyAir(96, 80, true));
+    }
+
+    @Test
+    public void rotatedTemplateAirClearsOnlyInsideTheChunkAndAboveTheFloor() throws Exception {
+        StructureTemplate.StructureBlockInfo clear = new StructureTemplate.StructureBlockInfo(
+                new BlockPos(1, 0, 0), Blocks.AIR.defaultBlockState(), null);
+        StructureTemplate.StructureBlockInfo belowFloor = new StructureTemplate.StructureBlockInfo(
+                new BlockPos(0, -1, 0), Blocks.AIR.defaultBlockState(), null);
+        StructureTemplate.StructureBlockInfo outsideChunk = new StructureTemplate.StructureBlockInfo(
+                new BlockPos(3, 0, 0), Blocks.AIR.defaultBlockState(), null);
+        StructureTemplate template = template(List.of(clear, belowFloor, outsideChunk));
+        BlockPos origin = new BlockPos(10, 80, 10);
+        StructurePlaceSettings settings = new StructurePlaceSettings().setRotation(Rotation.CLOCKWISE_90);
+        BlockPos clearPosition = origin.offset(StructureTemplate.calculateRelativePosition(settings, clear.pos()));
+        BlockPos belowFloorPosition = origin.offset(
+                StructureTemplate.calculateRelativePosition(settings, belowFloor.pos()));
+        BlockPos outsidePosition = origin.offset(
+                StructureTemplate.calculateRelativePosition(settings, outsideChunk.pos()));
+        BoundingBox area = new BoundingBox(
+                Math.min(clearPosition.getX(), belowFloorPosition.getX()),
+                Math.min(clearPosition.getY(), belowFloorPosition.getY()),
+                Math.min(clearPosition.getZ(), belowFloorPosition.getZ()),
+                Math.max(clearPosition.getX(), belowFloorPosition.getX()),
+                Math.max(clearPosition.getY(), belowFloorPosition.getY()),
+                Math.max(clearPosition.getZ(), belowFloorPosition.getZ()));
+        settings.setBoundingBox(area);
+        assertFalse(area.isInside(outsidePosition));
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        blocks.put(clearPosition, Blocks.DIRT.defaultBlockState());
+        blocks.put(belowFloorPosition, Blocks.DIRT.defaultBlockState());
+        blocks.put(outsidePosition, Blocks.DIRT.defaultBlockState());
+
+        NativeStructurePostProcessor.clearTemplateAir(
+                world(blocks), template, origin, 80, settings);
+
+        assertEquals(Blocks.AIR.defaultBlockState(), blocks.get(clearPosition));
+        assertEquals(Blocks.DIRT.defaultBlockState(), blocks.get(belowFloorPosition));
+        assertEquals(Blocks.DIRT.defaultBlockState(), blocks.get(outsidePosition));
+    }
+
+    @Test
+    public void unrelatedPieceBoundsAreRejectedBeforeTemplateScanning() {
+        BoundingBox area = new BoundingBox(0, -64, 0, 15, 319, 15);
+
+        assertTrue(NativeStructurePostProcessor.intersects(
+                new BoundingBox(15, 60, 15, 30, 90, 30), area));
+        assertFalse(NativeStructurePostProcessor.intersects(
+                new BoundingBox(16, 60, 16, 30, 90, 30), area));
+        assertFalse(NativeStructurePostProcessor.intersects(
+                new BoundingBox(0, 320, 0, 15, 350, 15), area));
+    }
+
+    @Test
+    public void vegetationCleanupUsesTheSameCircularTaperAsTerrain() {
+        BoundingBox piece = new BoundingBox(0, 60, 0, 4, 80, 4);
+
+        assertTrue(NativeStructurePostProcessor.withinSurfaceTerrainRadius(16, 2, piece, 12));
+        assertFalse(NativeStructurePostProcessor.withinSurfaceTerrainRadius(16, 16, piece, 12));
+    }
+
+    private static NativeStructurePostProcessor.SurfaceAnchor anchor(int meetY, int strength) {
+        return new NativeStructurePostProcessor.SurfaceAnchor(0, 4, 0, 4, meetY, strength);
+    }
+
+    private static StructureTemplate template(
+            List<StructureTemplate.StructureBlockInfo> blocks) throws Exception {
+        Constructor<StructureTemplate.Palette> constructor =
+                StructureTemplate.Palette.class.getDeclaredConstructor(List.class);
+        assertTrue(constructor.trySetAccessible());
+        StructureTemplate.Palette palette = constructor.newInstance(blocks);
+        StructureTemplate template = new StructureTemplate();
+        template.palettes.add(palette);
+        return template;
+    }
+
+    private static WorldGenLevel world(Map<BlockPos, BlockState> blocks) {
+        InvocationHandler handler = (proxy, method, arguments) -> {
+            String methodName = method.getName();
+            if (methodName.equals("getBlockState")) {
+                BlockPos position = (BlockPos) arguments[0];
+                return state(blocks, position.getX(), position.getY(), position.getZ());
+            }
+            if (methodName.equals("setBlock")) {
+                BlockPos position = (BlockPos) arguments[0];
+                BlockState blockState = (BlockState) arguments[1];
+                put(blocks, position.getX(), position.getY(), position.getZ(), blockState);
+                return true;
+            }
+            if (methodName.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (methodName.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (methodName.equals("toString")) {
+                return "surface-test-world";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        };
+        return (WorldGenLevel) Proxy.newProxyInstance(
+                WorldGenLevel.class.getClassLoader(), new Class<?>[]{WorldGenLevel.class}, handler);
+    }
+
+    private static void put(Map<BlockPos, BlockState> blocks,
+                            int x, int y, int z, BlockState state) {
+        blocks.put(new BlockPos(x, y, z), state);
+    }
+
+    private static BlockState state(Map<BlockPos, BlockState> blocks, int x, int y, int z) {
+        return blocks.getOrDefault(new BlockPos(x, y, z), Blocks.AIR.defaultBlockState());
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorVegetationTest.java

@@ -1,8 +1,10 @@
 package art.arcane.iris.nativegen;
 
 import net.minecraft.world.level.levelgen.GenerationStep;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
 import org.junit.Test;
 
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertTrue;
 
@@ -24,6 +26,22 @@ public class NativeStructurePostProcessorVegetationTest {
         assertTrue(NativeStructurePostProcessor.shouldClearVegetationColumn(20, 100, true));
     }
 
+    @Test
+    public void surfaceStructuresClearTheirEntireFootprintByDefault() {
+        assertTrue(NativeStructurePostProcessor.shouldClearEntireVegetationFootprint(
+                GenerationStep.Decoration.SURFACE_STRUCTURES, false));
+        assertTrue(NativeStructurePostProcessor.shouldClearEntireVegetationFootprint(
+                GenerationStep.Decoration.SURFACE_STRUCTURES, true));
+    }
+
+    @Test
+    public void undergroundStructuresPreserveSurfaceVegetationUnlessConfigured() {
+        assertFalse(NativeStructurePostProcessor.shouldClearEntireVegetationFootprint(
+                GenerationStep.Decoration.UNDERGROUND_STRUCTURES, false));
+        assertTrue(NativeStructurePostProcessor.shouldClearEntireVegetationFootprint(
+                GenerationStep.Decoration.UNDERGROUND_STRUCTURES, true));
+    }
+
     @Test
     public void allUndergroundGenerationStepsShareOneClassification() {
         assertTrue(NativeStructurePostProcessor.isUndergroundStep(
@@ -35,4 +53,25 @@ public class NativeStructurePostProcessorVegetationTest {
         assertFalse(NativeStructurePostProcessor.isUndergroundStep(
                 GenerationStep.Decoration.SURFACE_STRUCTURES));
     }
+
+    @Test
+    public void undergroundStructuresUseTheLowestTerrainColumn() {
+        BoundingBox bounds = new BoundingBox(0, 60, 0, 1, 80, 0);
+        int offset = NativeStructurePostProcessor.resolveBuriedOffset(
+                bounds, 0, -64, 320, (x, z) -> x == 1 ? 76 : 100);
+        assertEquals(-5, offset);
+    }
+
+    @Test
+    public void undergroundStructuresFailWhenBurialWouldCrossWorldFloor() {
+        BoundingBox bounds = new BoundingBox(0, 60, 0, 1, 80, 0);
+        try {
+            NativeStructurePostProcessor.resolveBuriedOffset(
+                    bounds, 0, 58, 320, (x, z) -> x == 1 ? 76 : 100);
+        } catch (IllegalStateException e) {
+            assertTrue(e.getMessage().contains("world minimum"));
+            return;
+        }
+        throw new AssertionError("Expected underground burial to fail below the world floor");
+    }
 }

adapters/bukkit/plugin/src/main/java/art/arcane/iris/core/commands/BukkitNativeStructureLocatePolicy.java

@@ -1,35 +0,0 @@
-/*
- * Iris is a World Generator for Minecraft Bukkit Servers
- * Copyright (c) 2026 Arcane Arts (Volmit Software)
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-
-package art.arcane.iris.core.commands;
-
-final class BukkitNativeStructureLocatePolicy {
-    private static final String MONUMENT_KEY = "minecraft:monument";
-    private static final String UNAVAILABLE_MESSAGE = "Native monument locating is unavailable on Paper, Purpur, and Folia because a cold search can stall the server thread. The monument lookup was skipped; monument generation is unaffected.";
-
-    private BukkitNativeStructureLocatePolicy() {
-    }
-
-    static boolean isUnavailable(String structureKey) {
-        return structureKey != null && MONUMENT_KEY.equalsIgnoreCase(structureKey.trim());
-    }
-
-    static String unavailableMessage() {
-        return UNAVAILABLE_MESSAGE;
-    }
-}

adapters/bukkit/plugin/src/main/java/art/arcane/iris/core/commands/CommandFind.java

@@ -21,12 +21,16 @@ package art.arcane.iris.core.commands;
 import art.arcane.iris.Iris;
 import art.arcane.iris.platform.bukkit.BukkitPlatform;
 import art.arcane.iris.core.service.ObjectStudioSaveService;
+import art.arcane.iris.core.structure.NativeStructureLocateCapability;
 import art.arcane.iris.engine.framework.Engine;
 import art.arcane.iris.engine.framework.IrisStructureLocator;
+import art.arcane.iris.engine.framework.NativeStructureGenerationPolicy;
 import art.arcane.iris.engine.platform.EngineBukkitOps;
 import art.arcane.iris.engine.framework.StructureReachability;
 import art.arcane.iris.engine.object.IrisBiome;
+import art.arcane.iris.engine.object.IrisNativeStructureDecision;
 import art.arcane.iris.engine.object.IrisRegion;
+import art.arcane.iris.engine.object.NativeStructureGenerationStatus;
 import art.arcane.iris.util.common.director.DirectorExecutor;
 import art.arcane.iris.util.common.director.specialhandlers.ObjectHandler;
 import art.arcane.iris.util.common.director.specialhandlers.StructureHandler;
@@ -117,13 +121,34 @@ public class CommandFind implements DirectorExecutor {
             return;
         }
 
-        if (IrisStructureLocator.isPlaced(e, structure)) {
-            locateIrisStructure(e, structure, commandSender);
+        String structureKey = structure == null ? "" : structure.trim();
+        Structure nativeStructure = resolveNativeStructure(structureKey);
+        if (nativeStructure != null) {
+            IrisNativeStructureDecision decision = NativeStructureGenerationPolicy.resolve(
+                    e, structureKey, false);
+            if (!decision.generate()
+                    && decision.status() != NativeStructureGenerationStatus.REPLACED_BY_IRIS) {
+                commandSender.sendMessage(C.RED + NativeStructureGenerationPolicy.generationStatusMessage(
+                        structureKey, decision.status()));
+                return;
+            }
+            if (decision.status() == NativeStructureGenerationStatus.REPLACED_BY_IRIS) {
+                locateIrisStructure(e, structureKey, commandSender);
+                return;
+            }
+            if (NativeStructureLocateCapability.isPaperUnavailable(structureKey)) {
+                commandSender.sendMessage(C.RED + NativeStructureLocateCapability.unavailableMessage());
+                return;
+            }
+        }
+
+        if (nativeStructure == null && IrisStructureLocator.isPlaced(e, structureKey)) {
+            locateIrisStructure(e, structureKey, commandSender);
             return;
         }
 
-        if (BukkitNativeStructureLocatePolicy.isUnavailable(structure)) {
-            commandSender.sendMessage(C.RED + BukkitNativeStructureLocatePolicy.unavailableMessage());
+        if (nativeStructure == null) {
+            commandSender.sendMessage(C.RED + "Unknown structure: " + structureKey);
             return;
         }
 
@@ -135,42 +160,44 @@ public class CommandFind implements DirectorExecutor {
 
         World targetWorld = target.getWorld();
         Location origin = target.getLocation();
-        commandSender.sendMessage(C.GRAY + "Locating " + structure + "...");
+        commandSender.sendMessage(C.GRAY + "Locating " + structureKey + "...");
         J.s(() -> {
             try {
-                Registry<Structure> structureRegistry = RegistryAccess.registryAccess().getRegistry(RegistryKey.STRUCTURE);
-                Structure match = null;
-                for (Structure candidate : structureRegistry) {
-                    NamespacedKey key = structureRegistry.getKey(candidate);
-                    if (key != null && key.toString().equalsIgnoreCase(structure)) {
-                        match = candidate;
-                        break;
-                    }
-                }
-                if (match == null) {
-                    sendStructureMessage(target, commandSender, C.RED + "Unknown structure: " + structure);
-                    return;
-                }
-                if (!StructureReachability.isReachable(e, structure)) {
-                    KList<String> miss = StructureReachability.missingBiomeKeys(e, structure);
+                if (!StructureReachability.isReachable(e, structureKey)) {
+                    KList<String> miss = StructureReachability.missingBiomeKeys(e, structureKey);
                     sendStructureMessage(target, commandSender,
-                            C.YELLOW + structure + " cannot generate in this world (its required biomes are not produced by this pack"
+                            C.YELLOW + structureKey + " cannot generate in this world (its required biomes are not produced by this pack"
                                     + (miss.isEmpty() ? "" : ": needs " + String.join("/", miss)) + ").");
                     return;
                 }
-                StructureSearchResult result = targetWorld.locateNearestStructure(origin, match, 100, false);
+                StructureSearchResult result = targetWorld.locateNearestStructure(
+                        origin, nativeStructure, 100, false);
                 if (result == null || result.getLocation() == null) {
-                    sendStructureMessage(target, commandSender, C.YELLOW + "No " + structure + " found within range of you.");
+                    sendStructureMessage(target, commandSender,
+                            C.YELLOW + "No " + structureKey + " found within range of you.");
                     return;
                 }
-                prepareStructureTeleport(target, targetWorld, commandSender, structure, result.getLocation(), false);
+                prepareStructureTeleport(
+                        target, targetWorld, commandSender, structureKey, result.getLocation(), false);
             } catch (Throwable t) {
-                sendStructureMessage(target, commandSender, C.RED + "Could not locate " + structure + ": " + t.getClass().getSimpleName());
-                Iris.reportError("Could not locate structure '" + structure + "'.", t);
+                sendStructureMessage(target, commandSender,
+                        C.RED + "Could not locate " + structureKey + ": " + t.getClass().getSimpleName());
+                Iris.reportError("Could not locate structure '" + structureKey + "'.", t);
             }
         });
     }
 
+    private static Structure resolveNativeStructure(String structureKey) {
+        Registry<Structure> structureRegistry = RegistryAccess.registryAccess().getRegistry(RegistryKey.STRUCTURE);
+        for (Structure candidate : structureRegistry) {
+            NamespacedKey key = structureRegistry.getKey(candidate);
+            if (key != null && key.toString().equalsIgnoreCase(structureKey)) {
+                return candidate;
+            }
+        }
+        return null;
+    }
+
     private void locateIrisStructure(Engine engine, String structure, VolmitSender commandSender) {
         Player target = player();
         if (target == null) {

adapters/bukkit/plugin/src/main/java/art/arcane/iris/core/commands/CommandObject.java

@@ -22,15 +22,13 @@ import art.arcane.iris.Iris;
 import art.arcane.iris.platform.bukkit.BukkitPlatform;
 import art.arcane.iris.core.link.WorldEditLink;
 import art.arcane.iris.core.loader.IrisData;
-import art.arcane.iris.core.loader.ResourceLoader;
 import art.arcane.iris.core.runtime.ObjectStudioActivation;
 import art.arcane.iris.core.runtime.WorldRuntimeControlService;
 import art.arcane.iris.core.service.ObjectSVC;
 import art.arcane.iris.core.service.StudioSVC;
 import art.arcane.iris.core.service.WandSVC;
 import art.arcane.iris.core.tools.IrisConverter;
-import art.arcane.iris.core.tools.PlausibilizeMode;
-import art.arcane.iris.core.tools.TreePlausibilizer;
+import art.arcane.iris.core.tools.TreePlausibilizeBatch;
 import art.arcane.iris.engine.framework.Engine;
 import art.arcane.iris.engine.object.IObjectPlacer;
 import art.arcane.iris.engine.object.IrisDimension;
@@ -353,199 +351,63 @@ public class CommandObject implements DirectorExecutor {
         }
     }
 
-    @Director(description = "Make tree leaves vanilla-decay-plausible (every leaf within 6 blocks of a log)",
+    @Director(description = "Grow organic branches through the canopy so every leaf survives vanilla decay",
             origin = DirectorOrigin.BOTH)
     public void plausibilize(
             @Param(description = "Object key, prefix (trees/), or filesystem path",
                     customHandler = ObjectTargetHandler.class)
             String target,
-            @Param(description = "DEFAULT: tentacle logs, delete orphans. NORMALIZE: + flip persistent=false. FOLIAGE_OVERATURE: add leaves to bridge orphans, no deletions. SMOKE: wipe & repaint canopy shell.",
-                    defaultValue = "DEFAULT")
-            PlausibilizeMode mode,
-            @Param(description = "Analyze only, do not write", defaultValue = "false")
+            @Param(name = "dryrun", description = "dryrun=true analyzes only, writes nothing", defaultValue = "false")
             boolean dryRun,
-            @Param(description = "Canopy shell radius (SMOKE only), clamped [0,5]", defaultValue = "2")
-            int radius
+            @Param(name = "reach", description = "reach=N max branch length in blocks from existing wood; farther leaf clusters are pinned persistent instead. reach=0 grows unlimited", defaultValue = "12")
+            int reach
     ) {
-        List<Target> targets = resolveTargets(target);
+        IrisData nearest = data();
+        List<TreePlausibilizeBatch.Target> targets = TreePlausibilizeBatch.resolve(target, nearest);
+        if (targets.isEmpty() && nearest == null) {
+            targets = resolveFromPacks(target);
+        }
         if (targets.isEmpty()) {
             sender().sendMessage(C.RED + "No objects matched: " + target);
             return;
         }
 
-        sender().sendMessage(C.IRIS + "Plausibilize [" + mode.name()
-                + (dryRun ? " DRY" : "")
-                + (mode == PlausibilizeMode.SMOKE ? " r=" + radius : "")
+        sender().sendMessage(C.IRIS + "Plausibilize [reach=" + reach + (dryRun ? ", DRY" : "")
                 + "] queued " + targets.size() + " object(s)");
 
         org.bukkit.command.CommandSender s = sender();
-        J.a(() -> runPlausibilize(targets, dryRun, mode, radius, s));
+        List<TreePlausibilizeBatch.Target> queued = targets;
+        J.a(() -> TreePlausibilizeBatch.run(queued, dryRun, reach, nearest, (String line) ->
+                s.sendMessage(line.startsWith("Done:") || line.startsWith("Totals:") || line.startsWith("[")
+                        ? C.IRIS + line
+                        : C.GRAY + "  " + line)));
     }
 
-    private List<Target> resolveTargets(String target) {
-        List<Target> out = new ArrayList<>();
-        if (target == null || target.isEmpty()) {
-            return out;
-        }
-
-        File direct = new File(target);
-        if (direct.isFile() && target.toLowerCase().endsWith(".iob")) {
-            out.add(new Target(direct.getName().replaceAll("\\.iob$", ""), direct));
-            return out;
-        }
-        if (direct.isDirectory()) {
-            walkIob(direct, direct, out);
-            return out;
-        }
-
-        IrisData irisData = data();
-        if (irisData != null) {
-            ResourceLoader<IrisObject> loader = irisData.getObjectLoader();
-            if (!target.endsWith("/") && loader.findFile(target) != null) {
-                out.add(new Target(target, null));
-                return out;
-            }
-            String prefix = target.endsWith("/") ? target : target + "/";
-            for (String k : loader.getPossibleKeys()) {
-                if (k.startsWith(prefix)) {
-                    out.add(new Target(k, null));
-                }
-            }
-            return out;
-        }
-
+    private static List<TreePlausibilizeBatch.Target> resolveFromPacks(String target) {
+        List<TreePlausibilizeBatch.Target> out = new ArrayList<>();
         File packsFolder = Iris.instance.getDataFolder("packs");
         File[] packs = packsFolder.listFiles(File::isDirectory);
-        if (packs != null) {
-            for (File pack : packs) {
-                File objectsRoot = new File(pack, "objects");
-                if (!objectsRoot.isDirectory()) continue;
-                File candidate = new File(objectsRoot, target + ".iob");
-                if (candidate.isFile()) {
-                    out.add(new Target(pack.getName() + "/" + target, candidate));
-                    continue;
-                }
-                File candidateDir = new File(objectsRoot, target);
-                if (candidateDir.isDirectory()) {
-                    walkIob(candidateDir, objectsRoot, out);
-                }
+        if (packs == null) {
+            return out;
+        }
+        for (File pack : packs) {
+            File objectsRoot = new File(pack, "objects");
+            if (!objectsRoot.isDirectory()) {
+                continue;
+            }
+            File candidate = new File(objectsRoot, target + ".iob");
+            if (candidate.isFile()) {
+                out.add(new TreePlausibilizeBatch.Target(pack.getName() + "/" + target, candidate));
+                continue;
+            }
+            File candidateDir = new File(objectsRoot, target);
+            if (candidateDir.isDirectory()) {
+                TreePlausibilizeBatch.walkIob(candidateDir, objectsRoot, out);
             }
         }
         return out;
     }
 
-    private static void walkIob(File root, File keyRoot, List<Target> out) {
-        File[] kids = root.listFiles();
-        if (kids == null) return;
-        for (File f : kids) {
-            if (f.isDirectory()) {
-                walkIob(f, keyRoot, out);
-            } else if (f.getName().toLowerCase().endsWith(".iob")) {
-                String rel = keyRoot.toPath().relativize(f.toPath()).toString()
-                        .replace(File.separatorChar, '/')
-                        .replaceAll("\\.iob$", "");
-                out.add(new Target(rel, f));
-            }
-        }
-    }
-
-    private record Target(String key, File file) {
-    }
-
-    private static void runPlausibilize(
-            List<Target> targets,
-            boolean dryRun,
-            PlausibilizeMode mode,
-            int radius,
-            org.bukkit.command.CommandSender s
-    ) {
-        int processed = 0;
-        int skipped = 0;
-        int failed = 0;
-        int changed = 0;
-        long totalLogsAdded = 0L;
-        long totalLeavesAdded = 0L;
-        long totalLeavesRemoved = 0L;
-        long totalNormalized = 0L;
-        long totalUnreachableAfter = 0L;
-
-        int progressStep = Math.max(1, targets.size() / 20);
-        int index = 0;
-
-        for (Target t : targets) {
-            index++;
-            try {
-                IrisObject o = loadTarget(t);
-                if (o == null) {
-                    s.sendMessage(C.YELLOW + "  skip " + t.key() + ": failed to load");
-                    skipped++;
-                    continue;
-                }
-
-                TreePlausibilizer.Result r = dryRun
-                        ? TreePlausibilizer.analyze(o, mode, radius)
-                        : TreePlausibilizer.apply(o, mode, radius);
-
-                if (r.skipReason() != null) {
-                    s.sendMessage(C.YELLOW + "  skip " + t.key() + ": " + r.skipReason());
-                    skipped++;
-                    continue;
-                }
-
-                boolean touched = r.logsAdded() > 0 || r.leavesAdded() > 0
-                        || r.leavesRemoved() > 0 || r.leavesNormalized() > 0;
-                if (!dryRun && touched) {
-                    File dest = o.getLoadFile() != null ? o.getLoadFile() : t.file();
-                    if (dest != null) {
-                        o.write(dest);
-                        changed++;
-                    }
-                }
-
-                processed++;
-                totalLogsAdded += r.logsAdded();
-                totalLeavesAdded += r.leavesAdded();
-                totalLeavesRemoved += r.leavesRemoved();
-                totalNormalized += r.leavesNormalized();
-                totalUnreachableAfter += r.unreachableAfter();
-
-                if (touched || targets.size() == 1) {
-                    s.sendMessage(C.GRAY + "  " + t.key()
-                            + C.WHITE + " +" + r.logsAdded() + " logs"
-                            + C.WHITE + " +" + r.leavesAdded() + " leaves"
-                            + C.WHITE + " -" + r.leavesRemoved() + " removed"
-                            + (r.leavesNormalized() > 0 ? C.WHITE + " ~" + r.leavesNormalized() + " normalized" : "")
-                            + (r.unreachableAfter() > 0 ? C.YELLOW + " " + r.unreachableAfter() + " unreachable" : ""));
-                }
-
-                if (targets.size() > 1 && index % progressStep == 0) {
-                    s.sendMessage(C.IRIS + "  [" + index + "/" + targets.size() + "]");
-                }
-            } catch (Throwable e) {
-                s.sendMessage(C.RED + "  fail " + t.key() + ": " + e.getClass().getSimpleName()
-                        + ": " + e.getMessage());
-                e.printStackTrace();
-                failed++;
-            }
-        }
-
-        s.sendMessage(C.IRIS + "Done: " + processed + " processed, " + changed + " changed, "
-                + skipped + " skipped, " + failed + " failed");
-        s.sendMessage(C.IRIS + "Totals: +" + totalLogsAdded + " logs, +" + totalLeavesAdded + " leaves, -"
-                + totalLeavesRemoved + " removed, ~" + totalNormalized + " normalized, "
-                + totalUnreachableAfter + " unreachable");
-    }
-
-    private static IrisObject loadTarget(Target t) throws IOException {
-        if (t.file() != null) {
-            IrisObject o = new IrisObject();
-            o.read(t.file());
-            o.setLoadFile(t.file());
-            return o;
-        }
-        return IrisData.loadAnyObject(t.key(), null);
-    }
-
     @Director(description = "Convert .schem files in the 'convert' folder to .iob files.")
     public void convert () {
         try {

adapters/bukkit/plugin/src/main/java/art/arcane/iris/core/commands/CommandStructure.java

@@ -21,18 +21,23 @@ package art.arcane.iris.core.commands;
 import art.arcane.iris.Iris;
 import art.arcane.iris.core.loader.IrisData;
 import art.arcane.iris.core.structure.BulkStructureImporter;
+import art.arcane.iris.core.structure.NativeStructureLocateCapability;
 import art.arcane.iris.core.structure.StructureCaptureImporter;
 import art.arcane.iris.core.structure.StructureImporter;
 import art.arcane.iris.core.structure.StructureIndexService;
 import art.arcane.iris.engine.framework.Engine;
 import art.arcane.iris.engine.framework.IrisStructureLocator;
+import art.arcane.iris.engine.framework.NativeStructureGenerationPolicy;
 import art.arcane.iris.engine.framework.PlacedStructurePiece;
 import art.arcane.iris.engine.framework.StructureAssembler;
 import art.arcane.iris.engine.framework.StructureReachability;
 import art.arcane.iris.engine.object.IObjectPlacer;
 import art.arcane.iris.engine.object.IrisDimension;
+import art.arcane.iris.engine.object.IrisNativeStructureDecision;
 import art.arcane.iris.engine.object.IrisObjectPlacement;
+import art.arcane.iris.engine.object.IrisPosition;
 import art.arcane.iris.engine.object.IrisStructure;
+import art.arcane.iris.engine.object.NativeStructureGenerationStatus;
 import art.arcane.iris.engine.object.ObjectPlaceMode;
 import art.arcane.volmlib.util.collection.KList;
 import art.arcane.iris.util.common.director.DirectorExecutor;
@@ -158,14 +163,23 @@ public class CommandStructure implements DirectorExecutor {
     private void runVerification(Engine engine, KList<String> structureKeys, int centerX, int centerZ,
                                  int searchRadius, VolmitSender commandSender, Player target) {
         KList<String> messages = new KList<>();
-        Set<String> reachable;
-        try {
-            reachable = StructureReachability.reachableKeys(engine);
-        } catch (Throwable error) {
-            messages.add(C.RED + "Structure verification could not resolve native biome reachability.");
-            sendVerificationMessages(commandSender, target, messages);
-            Iris.reportError("Could not resolve native structure biome reachability for verification.", error);
-            return;
+        Map<String, IrisNativeStructureDecision> decisions = new HashMap<>(structureKeys.size());
+        boolean requiresNativeReachability = false;
+        for (String keyName : structureKeys) {
+            IrisNativeStructureDecision decision = NativeStructureGenerationPolicy.resolve(engine, keyName, false);
+            decisions.put(keyName, decision);
+            requiresNativeReachability |= decision.generate();
+        }
+        Set<String> reachable = Set.of();
+        if (requiresNativeReachability) {
+            try {
+                reachable = StructureReachability.reachableKeys(engine);
+            } catch (Throwable error) {
+                messages.add(C.RED + "Structure verification could not resolve native biome reachability.");
+                sendVerificationMessages(commandSender, target, messages);
+                Iris.reportError("Could not resolve native structure biome reachability for verification.", error);
+                return;
+            }
         }
         int located = 0;
         int nativeEligible = 0;
@@ -175,8 +189,8 @@ public class CommandStructure implements DirectorExecutor {
         int searchLimited = 0;
         int errors = 0;
         for (String keyName : structureKeys) {
-            boolean irisPlaced = IrisStructureLocator.isPlaced(engine, keyName);
-            if (irisPlaced) {
+            IrisNativeStructureDecision decision = decisions.get(keyName);
+            if (decision.status() == NativeStructureGenerationStatus.REPLACED_BY_IRIS) {
                 try {
                     IrisStructureLocator.LocateResult result =
                             IrisStructureLocator.locate(engine, keyName, centerX, centerZ, searchRadius);
@@ -201,7 +215,7 @@ public class CommandStructure implements DirectorExecutor {
                 }
                 continue;
             }
-            if (!engine.getDimension().getImportedStructures().shouldGenerate(keyName)) {
+            if (!decision.generate()) {
                 disabled++;
                 messages.add(C.GRAY + "[disabled] " + C.WHITE + keyName);
                 continue;
@@ -213,20 +227,20 @@ public class CommandStructure implements DirectorExecutor {
                         + (missing.isEmpty() ? "" : C.YELLOW + " needs " + String.join("/", missing)));
                 continue;
             }
-            if (BukkitNativeStructureLocatePolicy.isUnavailable(keyName)) {
+            nativeEligible++;
+            if (NativeStructureLocateCapability.isPaperUnavailable(keyName)) {
                 unavailable++;
-                messages.add(C.RED + "[unavailable] " + C.WHITE + keyName + C.RED + ": "
-                        + BukkitNativeStructureLocatePolicy.unavailableMessage());
+                messages.add(C.YELLOW + "[native-eligible/locate-unavailable] " + C.WHITE + keyName + C.YELLOW + ": "
+                        + NativeStructureLocateCapability.unavailableMessage());
                 continue;
             }
-            nativeEligible++;
             messages.add(C.GREEN + "[native-eligible] " + C.WHITE + keyName);
         }
         messages.add(C.GREEN + "Structure verify: " + C.WHITE + located + C.GREEN + " Iris placements located, "
                 + C.WHITE + nativeEligible + C.GREEN + " native structures eligible, "
                 + C.WHITE + disabled + C.GREEN + " disabled by policy, "
                 + C.WHITE + unreachable + C.GREEN + " biome-unreachable, "
-                + C.WHITE + unavailable + C.GREEN + " unavailable on this platform, "
+                + C.WHITE + unavailable + C.GREEN + " generation-eligible but unavailable to synchronous locate, "
                 + C.WHITE + searchLimited + C.GREEN + " density searches safety-limited, "
                 + C.WHITE + errors + C.GREEN + " errors. Native eligibility is checked without running blocking live locates.");
         sendVerificationMessages(commandSender, target, messages);
@@ -285,12 +299,13 @@ public class CommandStructure implements DirectorExecutor {
             sender().sendMessage(C.RED + "Could not resolve the pack for dimension " + dimension.getLoadKey());
             return;
         }
-        IrisStructure s = IrisData.loadAnyStructure(structure, data);
+        IrisStructure s = data.load(IrisStructure.class, structure, false);
         if (s == null) {
             sender().sendMessage(C.RED + "No iris structure '" + structure + "' in this pack");
             return;
         }
-        StructureAssembler assembler = new StructureAssembler(data, s, 0, 64, 0);
+        StructureAssembler assembler = StructureAssembler.forData(
+                data, s, new IrisPosition(0, 64, 0));
         KList<PlacedStructurePiece> pieces = assembler.assemble(new RNG(1234));
         if (pieces == null || pieces.isEmpty()) {
             sender().sendMessage(C.RED + "Structure '" + structure + "' assembled 0 pieces (check startPool '" + s.getStartPool() + "')");
@@ -321,13 +336,14 @@ public class CommandStructure implements DirectorExecutor {
             sender().sendMessage(C.RED + "Could not resolve the pack for dimension " + dimension.getLoadKey());
             return;
         }
-        IrisStructure s = IrisData.loadAnyStructure(structure, data);
+        IrisStructure s = data.load(IrisStructure.class, structure, false);
         if (s == null) {
             sender().sendMessage(C.RED + "No iris structure '" + structure + "' in this pack");
             return;
         }
         Location loc = player().getLocation();
-        StructureAssembler assembler = new StructureAssembler(data, s, loc.getBlockX(), loc.getBlockY(), loc.getBlockZ());
+        StructureAssembler assembler = StructureAssembler.forData(
+                data, s, new IrisPosition(loc.getBlockX(), loc.getBlockY(), loc.getBlockZ()));
         RNG rng = new RNG((long) loc.getBlockX() * 341873128712L + loc.getBlockZ());
         KList<PlacedStructurePiece> pieces = assembler.assemble(rng);
         if (pieces == null || pieces.isEmpty()) {

adapters/bukkit/plugin/src/main/java/art/arcane/iris/core/commands/CommandStudio.java

@@ -26,6 +26,7 @@ import art.arcane.iris.core.gui.NoiseExplorerGUI;
 import art.arcane.iris.core.gui.VisionGUI;
 import art.arcane.iris.core.loader.IrisData;
 import art.arcane.iris.core.project.IrisProject;
+import art.arcane.iris.core.service.BoardSVC;
 import art.arcane.iris.core.service.StudioSVC;
 import art.arcane.iris.core.structure.BulkStructureImporter;
 import art.arcane.iris.core.structure.FeatureImporter;
@@ -193,6 +194,25 @@ public class CommandStudio implements DirectorExecutor {
         }));
     }
 
+    @Director(description = "Toggle your Studio debug scoreboard", aliases = {"board", "sidebar", "sb"}, origin = DirectorOrigin.PLAYER)
+    public void scoreboard() {
+        Player target = player();
+        VolmitSender commandSender = sender();
+        if (!J.runEntity(target, () -> {
+            PlatformChunkGenerator generator = IrisToolbelt.access(target.getWorld());
+            if (generator == null || !generator.isStudio()) {
+                commandSender.sendMessage(C.RED + "You must be in a Studio world to toggle the debug scoreboard.");
+                return;
+            }
+
+            boolean visible = Iris.service(BoardSVC.class).toggle(target);
+            commandSender.sendMessage((visible ? C.GREEN : C.YELLOW)
+                    + "Studio debug scoreboard " + (visible ? "enabled." : "disabled."));
+        })) {
+            commandSender.sendMessage(C.RED + "Could not update the Studio debug scoreboard right now.");
+        }
+    }
+
     @Director(description = "Create a new studio project", aliases = "+", sync = true)
     public void create(
             @Param(description = "The name of this new Iris Project.", defaultValue = "studio")
@@ -259,7 +279,7 @@ public class CommandStudio implements DirectorExecutor {
         Inventory inv = Bukkit.createInventory(null, 27 * 2);
 
         try {
-            EngineBukkitOps.addItems(engine(), true, inv, RNG.r, tables, InventorySlotType.STORAGE, player().getWorld(), player().getLocation().getBlockX(), player().getLocation().getBlockY(), player().getLocation().getBlockZ(), 1);
+            EngineBukkitOps.addItems(engine(), true, inv, tables, InventorySlotType.STORAGE, player().getWorld(), player().getLocation().getBlockX(), player().getLocation().getBlockY(), player().getLocation().getBlockZ());
         } catch (Throwable e) {
             Iris.reportError(e);
             sender().sendMessage(C.RED + "Cannot add items to virtual inventory because of: " + e.getMessage());
@@ -286,7 +306,7 @@ public class CommandStudio implements DirectorExecutor {
                 inv.clear();
             }
 
-            EngineBukkitOps.addItems(engine, true, inv, new RNG(RNG.r.imax()), tables, InventorySlotType.STORAGE, player.getWorld(), player.getLocation().getBlockX(), player.getLocation().getBlockY(), player.getLocation().getBlockZ(), 1);
+            EngineBukkitOps.addItems(engine, true, inv, tables, InventorySlotType.STORAGE, player.getWorld(), player.getLocation().getBlockX(), player.getLocation().getBlockY(), player.getLocation().getBlockZ());
         }, fast ? 5 : 35));
 
         sender().sendMessage(C.GREEN + "Opening inventory now!");
@@ -829,7 +849,7 @@ public class CommandStudio implements DirectorExecutor {
             sender().sendMessage(C.RED + "No studio world is open!");
             return true;
         }
-        if (!engine().isStudio()) {
+        if (!IrisToolbelt.isStudio(world())) {
             sender().sendMessage(C.RED + "You must be in a studio world!");
             return true;
         }

adapters/bukkit/plugin/src/test/java/art/arcane/iris/core/commands/BukkitNativeStructureLocatePolicyTest.java

@@ -1,32 +0,0 @@
-package art.arcane.iris.core.commands;
-
-import org.junit.Test;
-
-import static org.junit.Assert.assertFalse;
-import static org.junit.Assert.assertTrue;
-
-public class BukkitNativeStructureLocatePolicyTest {
-    @Test
-    public void nativeMonumentLocateIsUnavailable() {
-        assertTrue(BukkitNativeStructureLocatePolicy.isUnavailable("minecraft:monument"));
-        assertTrue(BukkitNativeStructureLocatePolicy.isUnavailable(" MINECRAFT:MONUMENT "));
-    }
-
-    @Test
-    public void unrelatedAndNonCanonicalKeysRemainAvailable() {
-        assertFalse(BukkitNativeStructureLocatePolicy.isUnavailable(null));
-        assertFalse(BukkitNativeStructureLocatePolicy.isUnavailable(""));
-        assertFalse(BukkitNativeStructureLocatePolicy.isUnavailable("minecraft:stronghold"));
-        assertFalse(BukkitNativeStructureLocatePolicy.isUnavailable("minecraft:ocean_monument"));
-        assertFalse(BukkitNativeStructureLocatePolicy.isUnavailable("minecraft:ocean_monuments"));
-    }
-
-    @Test
-    public void rejectionExplainsSafetyAndGenerationBehavior() {
-        String message = BukkitNativeStructureLocatePolicy.unavailableMessage().toLowerCase();
-
-        assertTrue(message.contains("unavailable"));
-        assertTrue(message.contains("stall the server thread"));
-        assertTrue(message.contains("generation is unaffected"));
-    }
-}

adapters/bukkit/plugin/src/test/java/art/arcane/iris/core/commands/IrisStructureLocateCommandContractTest.java

@@ -1,11 +1,14 @@
 package art.arcane.iris.core.commands;
 
+import art.arcane.iris.engine.framework.NativeStructureGenerationPolicy;
+import art.arcane.iris.engine.object.NativeStructureGenerationStatus;
 import org.junit.Test;
 
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertTrue;
 
@@ -21,6 +24,47 @@ public class IrisStructureLocateCommandContractTest {
         assertFalse(source.contains("at[2] + 8"));
     }
 
+    @Test
+    public void findRoutesOnlyExplicitNativeReplacementThroughIrisLocate() throws IOException {
+        String source = Files.readString(Path.of(System.getProperty("iris.commandFindSource")));
+        int methodStart = source.indexOf("public void structure(");
+        int methodEnd = source.indexOf("private static Structure resolveNativeStructure", methodStart);
+        String method = source.substring(methodStart, methodEnd);
+        int nativeResolution = method.indexOf("resolveNativeStructure(structureKey)");
+        int policyResolution = method.indexOf("NativeStructureGenerationPolicy.resolve(", nativeResolution);
+        int replacementCheck = method.indexOf(
+                "decision.status() == NativeStructureGenerationStatus.REPLACED_BY_IRIS", policyResolution);
+        int replacementLocate = method.indexOf("locateIrisStructure(e, structureKey, commandSender)", replacementCheck);
+        int capabilityCheck = method.indexOf("NativeStructureLocateCapability.isPaperUnavailable(structureKey)", replacementLocate);
+        int genericIrisLookup = method.indexOf(
+                "nativeStructure == null && IrisStructureLocator.isPlaced(e, structureKey)", capabilityCheck);
+        int nativeLocate = method.indexOf("targetWorld.locateNearestStructure(", genericIrisLookup);
+        assertTrue(nativeResolution >= 0);
+        assertTrue(policyResolution > nativeResolution);
+        assertTrue(replacementCheck > policyResolution);
+        assertTrue(replacementLocate > replacementCheck);
+        assertTrue(capabilityCheck > replacementLocate);
+        assertTrue(genericIrisLookup > capabilityCheck);
+        assertTrue(nativeLocate > policyResolution);
+        assertTrue(method.contains("decision.status() != NativeStructureGenerationStatus.REPLACED_BY_IRIS"));
+    }
+
+    @Test
+    public void findNativePolicyMessagesMatchModdedDiagnostics() {
+        assertEquals(
+                "Native structure minecraft:village_plains is disabled by this dimension's importedStructures settings.",
+                NativeStructureGenerationPolicy.generationStatusMessage(
+                        "minecraft:village_plains", NativeStructureGenerationStatus.DISABLED_BY_PACK));
+        assertEquals(
+                "Native structure minecraft:ancient_city is replaced by an Iris placement in this pack and locates through that explicit replacement.",
+                NativeStructureGenerationPolicy.generationStatusMessage(
+                        "minecraft:ancient_city", NativeStructureGenerationStatus.REPLACED_BY_IRIS));
+        assertEquals(
+                "Native structure minecraft:stronghold generates natively.",
+                NativeStructureGenerationPolicy.generationStatusMessage(
+                        "minecraft:stronghold", NativeStructureGenerationStatus.GENERATE_NATIVE));
+    }
+
     @Test
     public void structureVerifyReportsDensityLimitAndUsesExactLocatedOrigin() throws IOException {
         String source = Files.readString(Path.of(System.getProperty("iris.commandStructureSource")));
@@ -31,4 +75,21 @@ public class IrisStructureLocateCommandContractTest {
         assertFalse(source.contains("at[0] + 8"));
         assertFalse(source.contains("at[2] + 8"));
     }
+
+    @Test
+    public void structureVerifyPartitionsPolicyBeforeNativeReachability() throws IOException {
+        String source = Files.readString(Path.of(System.getProperty("iris.commandStructureSource")));
+        int methodStart = source.indexOf("private void runVerification(");
+        int methodEnd = source.indexOf("private void sendVerificationMessages(", methodStart);
+        String method = source.substring(methodStart, methodEnd);
+        int policyResolution = method.indexOf("NativeStructureGenerationPolicy.resolve(engine, keyName, false)");
+        int nativeRequirement = method.indexOf("requiresNativeReachability |= decision.generate()", policyResolution);
+        int reachabilityGuard = method.indexOf("if (requiresNativeReachability)", nativeRequirement);
+        int reachabilityLookup = method.indexOf("StructureReachability.reachableKeys(engine)", reachabilityGuard);
+
+        assertTrue(policyResolution >= 0);
+        assertTrue(nativeRequirement > policyResolution);
+        assertTrue(reachabilityGuard > nativeRequirement);
+        assertTrue(reachabilityLookup > reachabilityGuard);
+    }
 }

adapters/bukkit/plugin/src/test/java/art/arcane/iris/core/commands/StudioScoreboardCommandTest.java

@@ -0,0 +1,25 @@
+package art.arcane.iris.core.commands;
+
+import art.arcane.volmlib.util.director.DirectorOrigin;
+import art.arcane.volmlib.util.director.annotations.Director;
+import org.junit.Test;
+
+import java.lang.reflect.Method;
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class StudioScoreboardCommandTest {
+    @Test
+    public void scoreboardCommandIsPlayerScopedAndEntityScheduled() throws NoSuchMethodException {
+        Method command = CommandStudio.class.getDeclaredMethod("scoreboard");
+        Director director = command.getAnnotation(Director.class);
+
+        assertEquals(DirectorOrigin.PLAYER, director.origin());
+        assertFalse(director.sync());
+        assertTrue(List.of(director.aliases()).contains("board"));
+        assertTrue(List.of(director.aliases()).contains("sidebar"));
+    }
+}