Terrain-first hydrology

- Replace the river package with the hydrology planner, footprint compiler, cave containment and runtime
- Add the hydrology pack schema, validator, probes and tests
- Wire hydrology into IrisComplex, actuators, mantle, Vision and commands

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

@@ -28,6 +28,9 @@ 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.StructureReachability;
+import art.arcane.iris.engine.hydrology.HydrologyFeatureQuery;
+import art.arcane.iris.engine.hydrology.HydrologyFeatureRef;
+import art.arcane.iris.engine.hydrology.runtime.IrisHydrologyRuntime;
 import art.arcane.iris.engine.object.IrisBiome;
 import art.arcane.iris.engine.object.IrisNativeStructureDecision;
 import art.arcane.iris.engine.object.IrisRegion;
@@ -37,7 +40,9 @@ import art.arcane.iris.platform.bukkit.BukkitPlatform;
 import art.arcane.iris.spi.IrisPlatforms;
 import art.arcane.iris.spi.PlatformStructureHooks;
 import art.arcane.iris.util.common.director.DirectorExecutor;
+import art.arcane.iris.util.common.director.specialhandlers.HydrologyTypeHandler;
 import art.arcane.iris.util.common.director.specialhandlers.ObjectHandler;
+import art.arcane.iris.util.common.director.specialhandlers.ReachableBiomeHandler;
 import art.arcane.iris.util.common.director.specialhandlers.StructureHandler;
 import art.arcane.iris.util.common.format.C;
 import art.arcane.iris.util.common.plugin.VolmitSender;
@@ -68,7 +73,7 @@ import java.util.Set;
 public class CommandFind implements DirectorExecutor {
     @Director(description = "Find a biome", descriptionKey = "iris.director.commandfind.director.find_biome")
     public void biome(
-            @Param(description = "The biome to look for", descriptionKey = "iris.director.commandfind.param.biome_look")
+            @Param(description = "The biome to look for", descriptionKey = "iris.director.commandfind.param.biome_look", customHandler = ReachableBiomeHandler.class)
             IrisBiome biome,
             @Param(description = "Should you be teleported", descriptionKey = "iris.director.commandfind.param.should_you_be_teleported", defaultValue = "true")
             boolean teleport
@@ -116,6 +121,73 @@ public class CommandFind implements DirectorExecutor {
         EngineBukkitOps.gotoPOI(e, type, player(), teleport);
     }
 
+    @Director(description = "Find an accepted hydrology feature")
+    public void river(
+            @Param(description = "Feature type: surface, waterfall, underground, grotto, mouth, or a deep-fluid id", customHandler = HydrologyTypeHandler.class)
+            String type,
+            @Param(description = "Should you be teleported", defaultValue = "true")
+            boolean teleport
+    ) {
+        Engine activeEngine = engine();
+        VolmitSender commandSender = sender();
+        Player target = player();
+        if (activeEngine == null || commandSender == null || target == null) {
+            if (commandSender != null) {
+                commandSender.sendMessage(C.RED + "Run this command from an Iris world.");
+            }
+            return;
+        }
+        IrisHydrologyRuntime runtime = activeEngine.getComplex().getHydrologyRuntime();
+        if (runtime == null) {
+            commandSender.sendMessage(C.YELLOW + "Hydrology is not active in this world.");
+            return;
+        }
+        HydrologyFeatureQuery query;
+        try {
+            query = HydrologyFeatureQuery.parse(type);
+        } catch (IllegalArgumentException error) {
+            commandSender.sendMessage(C.RED + error.getMessage());
+            return;
+        }
+        Location origin = target.getLocation();
+        int requestedDistance = Math.min(8192, runtime.settings().routing().tileSize() * 15);
+        int maximumDistance = runtime.maximumFeatureSearchDistance(
+                origin.getBlockX(), origin.getBlockZ(), requestedDistance);
+        commandSender.sendMessage(C.GRAY + "Searching accepted hydrology plans for " + type + "...");
+        J.a(() -> {
+            try {
+                HydrologyFeatureRef feature = runtime.nearestFeature(
+                        query.types(),
+                        query.profileKey(),
+                        origin.getBlockX(),
+                        origin.getBlockZ(),
+                        maximumDistance
+                ).orElse(null);
+                if (feature == null) {
+                    sendStructureMessage(target, commandSender,
+                            C.YELLOW + "No accepted " + type + " hydrology feature found within "
+                                    + maximumDistance + " blocks.");
+                    return;
+                }
+                int worldY = feature.y() + activeEngine.getDimension().getMinHeight();
+                String label = type + " hydrology feature";
+                if (!teleport) {
+                    sendStructureMessage(target, commandSender,
+                            C.GREEN + "Found " + label + " at " + feature.x() + ", " + worldY + ", " + feature.z() + ".");
+                    return;
+                }
+                Location destination = new Location(
+                        target.getWorld(), feature.x(), worldY, feature.z());
+                prepareStructureTeleport(
+                        target, target.getWorld(), commandSender, label, destination, true);
+            } catch (Throwable error) {
+                sendStructureMessage(target, commandSender,
+                        C.RED + "Could not locate " + type + " hydrology: " + error.getClass().getSimpleName());
+                Iris.reportError("Could not locate accepted hydrology feature '" + type + "'.", error);
+            }
+        });
+    }
+
     @Director(description = "Find a structure (a vanilla key like minecraft:village_plains or minecraft:stronghold, or an imported iris structure key)", descriptionKey = "iris.director.commandfind.director.find_structure_vanilla_key_like_minecraft_village_plains_minecraft_stronghold_imported_iris", sync = true)
     public void structure(
             @Param(description = "The structure to look for (e.g. minecraft:village_plains, minecraft:stronghold, minecraft_ancient_city)", descriptionKey = "iris.director.commandfind.param.structure_look_e_g_minecraft_village_plains_minecraft_stronghold_minecraft_ancient_city", customHandler = StructureHandler.class)

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

@@ -25,7 +25,10 @@ import art.arcane.iris.core.pack.PackValidationCache;
 import art.arcane.iris.core.pack.PackValidationRegistry;
 import art.arcane.iris.core.pack.PackValidationResult;
 import art.arcane.iris.core.pack.PackValidator;
+import art.arcane.iris.core.service.StudioSVC;
+import art.arcane.iris.engine.object.IrisDimension;
 import art.arcane.iris.util.common.director.DirectorExecutor;
+import art.arcane.iris.util.common.director.handlers.DimensionHandler;
 import art.arcane.iris.util.common.plugin.VolmitSender;
 import art.arcane.volmlib.util.director.annotations.Director;
 import art.arcane.volmlib.util.director.annotations.Param;
@@ -90,6 +93,18 @@ public class CommandPack implements DirectorExecutor {
         persistValidationCache(packsRoot);
     }
 
+    @Director(description = "Package a validated dimension into a compressed format", descriptionKey = "iris.director.commandstudio.director.package_dimension_into_compressed_format", aliases = "package")
+    public void pkg(
+            @Param(name = "dimension", description = "The dimension pack to compress", descriptionKey = "iris.director.commandstudio.param.dimension_pack_compress", contextual = true, contextualOverride = true, defaultValue = "default", customHandler = DimensionHandler.class)
+            IrisDimension dimension,
+            @Param(name = "obfuscate", description = "Whether or not to obfuscate the pack", descriptionKey = "iris.director.commandstudio.param.whether_not_obfuscate_pack", defaultValue = "false")
+            boolean obfuscate,
+            @Param(name = "minify", description = "Whether or not to minify the pack", descriptionKey = "iris.director.commandstudio.param.whether_not_minify_pack", defaultValue = "true")
+            boolean minify
+    ) {
+        Iris.service(StudioSVC.class).compilePackage(sender(), dimension.getLoadKey(), obfuscate, minify);
+    }
+
     @Director(description = "Preview or apply unused-resource cleanup", descriptionKey = "iris.director.commandpack.director.preview_apply_unused_resource_cleanup", aliases = {"c"})
     public void cleanup(
             @Param(description = "The pack folder name to clean", descriptionKey = "iris.director.commandpack.param.pack_folder_name_clean")

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

@@ -420,18 +420,6 @@ public class CommandStudio implements DirectorExecutor {
         sender().sendMessage(IrisLanguage.text(BukkitCommandMessagesExtended.COMMAND_STUDIO_OPENING_MAP));
     }
 
-    @Director(description = "Package a dimension into a compressed format", descriptionKey = "iris.director.commandstudio.director.package_dimension_into_compressed_format", aliases = "package")
-    public void pkg(
-            @Param(name = "dimension", description = "The dimension pack to compress", descriptionKey = "iris.director.commandstudio.param.dimension_pack_compress", contextual = true, contextualOverride = true, defaultValue = "default", customHandler = DimensionHandler.class)
-            IrisDimension dimension,
-            @Param(name = "obfuscate", description = "Whether or not to obfuscate the pack", descriptionKey = "iris.director.commandstudio.param.whether_not_obfuscate_pack", defaultValue = "false")
-            boolean obfuscate,
-            @Param(name = "minify", description = "Whether or not to minify the pack", descriptionKey = "iris.director.commandstudio.param.whether_not_minify_pack", defaultValue = "true")
-            boolean minify
-    ) {
-        Iris.service(StudioSVC.class).compilePackage(sender(), dimension.getLoadKey(), obfuscate, minify);
-    }
-
     @Director(description = "Profiles the performance of a dimension", descriptionKey = "iris.director.commandstudio.director.profiles_performance_dimension", origin = DirectorOrigin.PLAYER)
     public void profile(
             @Param(description = "The dimension to profile", descriptionKey = "iris.director.commandstudio.param.dimension_profile", contextual = true, contextualOverride = true, defaultValue = "default", customHandler = DimensionHandler.class)

adapters/bukkit/plugin/src/main/java/art/arcane/iris/core/service/IrisTerrainSVC.java

@@ -15,12 +15,12 @@ import art.arcane.iris.core.service.terrain.IrisSampleLimits;
 import art.arcane.iris.core.service.terrain.IrisSurfaceClassifier;
 import art.arcane.iris.core.service.terrain.IrisWorldInfoFactory;
 import art.arcane.iris.engine.framework.Engine;
+import art.arcane.iris.engine.hydrology.HydrologyColumnLayer;
+import art.arcane.iris.engine.hydrology.HydrologyColumnSample;
 import art.arcane.iris.engine.object.InferredType;
 import art.arcane.iris.engine.object.IrisBiome;
 import art.arcane.iris.engine.object.IrisRegion;
 import art.arcane.iris.engine.platform.PlatformChunkGenerator;
-import art.arcane.iris.engine.river.RiverRouteState;
-import art.arcane.iris.engine.river.runtime.IrisRiverSurfaceSample;
 import art.arcane.iris.platform.bukkit.BukkitPlatform;
 import art.arcane.iris.spi.IrisLogging;
 import art.arcane.iris.spi.IrisServices;
@@ -105,14 +105,15 @@ public class IrisTerrainSVC implements IrisService, IrisTerrainService {
 
         try {
             int surface = engine.getHeight(blockX, blockZ);
-            IrisRiverSurfaceSample riverSurface = engine.getComplex().getRiverSurfaceStream().get(blockX, blockZ);
-            int fluid = (int) Math.round(riverSurface.waterSurfaceY());
+            HydrologyColumnSample hydrology = hydrologySample(engine, blockX, blockZ);
+            int fluid = (int) Math.round(
+                    engine.getComplex().getRiverWaterSurfaceStream().get(blockX, blockZ));
             InferredType inferredType = null;
             if (IrisSurfaceClassifier.requiresSurfaceBiome(surface, fluid)) {
                 IrisBiome biome = engine.getSurfaceBiome(blockX, blockZ);
                 inferredType = biome == null ? null : biome.getInferredType();
             }
-            return IrisSurfaceClassifier.classify(surface, fluid, inferredType, riverSurface);
+            return IrisSurfaceClassifier.classify(surface, fluid, inferredType, hydrology);
         } catch (Throwable error) {
             reportQueryFault("surfaceKind", world, error);
             return IrisSurfaceKind.UNKNOWN;
@@ -246,13 +247,13 @@ public class IrisTerrainSVC implements IrisService, IrisTerrainService {
                     return false;
                 }
 
-                IrisRiverSurfaceSample riverSurface = wantRiver
-                        ? engine.getComplex().getRiverSurfaceStream().get(blockX, blockZ)
+                HydrologyColumnSample hydrology = wantRiver
+                        ? hydrologySample(engine, blockX, blockZ)
                         : null;
                 int surface = wantHeight || wantKind ? engine.getHeight(blockX, blockZ) : 0;
-                int fluid = riverSurface == null
-                        ? engine.getDimension().getFluidHeight()
-                        : (int) Math.round(riverSurface.waterSurfaceY());
+                int fluid = wantRiver
+                        ? (int) Math.round(engine.getComplex().getRiverWaterSurfaceStream().get(blockX, blockZ))
+                        : engine.getDimension().getFluidHeight();
                 boolean needsBiome = wantBiome
                         || (wantKind && IrisSurfaceClassifier.requiresSurfaceBiome(surface, fluid));
                 IrisBiome biome = needsBiome ? engine.getSurfaceBiome(blockX, blockZ) : null;
@@ -261,26 +262,29 @@ public class IrisTerrainSVC implements IrisService, IrisTerrainService {
                                 surface,
                                 fluid,
                                 biome == null ? null : biome.getInferredType(),
-                                riverSurface
+                                hydrology
                         )
                         : IrisSurfaceKind.UNKNOWN;
                 String biomeKey = wantBiome && biome != null ? biome.getLoadKey() : null;
                 int natural = wantNaturalHeight
                         ? (int) Math.round(engine.getComplex().getNaturalHeightStream().get(blockX, blockZ)) + minHeight
                         : IrisColumnSample.UNAVAILABLE_HEIGHT;
-                boolean riverPresent = riverSurface != null && riverSurface.river().present();
-                IrisRiverState riverState = wantRiverState && riverSurface != null
-                        ? riverState(riverSurface)
+                HydrologyColumnLayer surfaceLayer = hydrology == null
+                        ? null
+                        : hydrology.primarySurfaceLayer().orElse(null);
+                boolean riverPresent = surfaceLayer != null;
+                IrisRiverState riverState = wantRiverState
+                        ? riverState(hydrology)
                         : IrisRiverState.NONE;
                 double riverDistance = wantRiverDistance && riverPresent
-                        ? riverSurface.river().distance()
+                        ? engine.getComplex().getRiverDistanceStream().get(blockX, blockZ)
                         : IrisColumnSample.UNAVAILABLE_RIVER_DISTANCE;
                 int riverFlow = wantRiverFlow && riverPresent
-                        ? riverSurface.river().flow()
+                        ? (int) Math.round(engine.getComplex().getRiverFlowStream().get(blockX, blockZ))
                         : IrisColumnSample.UNAVAILABLE_RIVER_FLOW;
                 int riverWaterSurfaceY = wantRiverWaterSurface
-                        && riverPresent
-                        && riverSurface.river().state() == RiverRouteState.WET
+                        && surfaceLayer != null
+                        && surfaceLayer.connectedFluid()
                         ? fluid + minHeight
                         : IrisColumnSample.UNAVAILABLE_HEIGHT;
                 sink.accept(new IrisColumnSample(
@@ -304,15 +308,21 @@ public class IrisTerrainSVC implements IrisService, IrisTerrainService {
         }
     }
 
-    static IrisRiverState riverState(IrisRiverSurfaceSample surface) {
-        if (!surface.river().present()) {
+    static IrisRiverState riverState(HydrologyColumnSample hydrology) {
+        HydrologyColumnLayer layer = hydrology == null
+                ? null
+                : hydrology.primarySurfaceLayer().orElse(null);
+        if (layer == null || !layer.channel()) {
             return IrisRiverState.NONE;
         }
-        return switch (surface.river().state()) {
-            case WET -> IrisRiverState.WET;
-            case DRY -> IrisRiverState.DRY;
-            case SUPPRESSED -> IrisRiverState.NONE;
-        };
+        return layer.connectedFluid() ? IrisRiverState.WET : IrisRiverState.DRY;
+    }
+
+    private static HydrologyColumnSample hydrologySample(Engine engine, int blockX, int blockZ) {
+        if (engine.getComplex().getHydrologyRuntime() == null) {
+            return null;
+        }
+        return engine.getComplex().getHydrologyRuntime().sample(blockX, blockZ).orElse(null);
     }
 
     private static Optional<String> key(IrisBiome biome) {

adapters/bukkit/plugin/src/main/java/art/arcane/iris/core/service/terrain/IrisSurfaceClassifier.java

@@ -1,10 +1,9 @@
 package art.arcane.iris.core.service.terrain;
 
 import art.arcane.iris.api.terrain.IrisSurfaceKind;
+import art.arcane.iris.engine.hydrology.HydrologyColumnLayer;
+import art.arcane.iris.engine.hydrology.HydrologyColumnSample;
 import art.arcane.iris.engine.object.InferredType;
-import art.arcane.iris.engine.river.RiverRouteState;
-import art.arcane.iris.engine.river.RiverSection;
-import art.arcane.iris.engine.river.runtime.IrisRiverSurfaceSample;
 
 public final class IrisSurfaceClassifier {
     private IrisSurfaceClassifier() {
@@ -30,25 +29,23 @@ public final class IrisSurfaceClassifier {
             int engineSurfaceHeight,
             int engineFluidHeight,
             InferredType inferredType,
-            IrisRiverSurfaceSample riverSurface
+            HydrologyColumnSample hydrology
     ) {
         if (engineSurfaceHeight <= 0) {
             return IrisSurfaceKind.VOID;
         }
-        if (riverSurface != null && riverSurface.river().present() && !riverSurface.subterranean()) {
-            if (riverSurface.river().state() == RiverRouteState.DRY) {
-                return riverSurface.river().section() == RiverSection.DRY_CHANNEL
-                        ? IrisSurfaceKind.DRY_CHANNEL
-                        : IrisSurfaceKind.LAND;
+        HydrologyColumnLayer layer = hydrology == null
+                ? null
+                : hydrology.primarySurfaceLayer().orElse(null);
+        if (layer != null) {
+            if (layer.shore()) {
+                return IrisSurfaceKind.RIVER_SHORE;
             }
-            if (riverSurface.river().state() == RiverRouteState.WET) {
-                RiverSection section = riverSurface.river().section();
-                if (section == RiverSection.BANK) {
-                    return IrisSurfaceKind.RIVER_SHORE;
-                }
-                if (section == RiverSection.CHANNEL || section == RiverSection.MOUTH) {
-                    return IrisSurfaceKind.RIVER;
-                }
+            if (layer.channel()) {
+                return layer.connectedFluid() ? IrisSurfaceKind.RIVER : IrisSurfaceKind.DRY_CHANNEL;
+            }
+            if (layer.grading()) {
+                return IrisSurfaceKind.LAND;
             }
         }
         return classify(engineSurfaceHeight, engineFluidHeight, inferredType);

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

@@ -0,0 +1,20 @@
+package art.arcane.iris.core.commands;
+
+import art.arcane.iris.engine.object.IrisBiome;
+import art.arcane.iris.util.common.director.specialhandlers.ReachableBiomeHandler;
+import art.arcane.volmlib.util.director.annotations.Param;
+import org.junit.Test;
+
+import java.lang.reflect.Method;
+
+import static org.junit.Assert.assertEquals;
+
+public class CommandFindBiomeContractTest {
+    @Test
+    public void biomeLookupUsesReachableBiomeHandler() throws Exception {
+        Method method = CommandFind.class.getMethod("biome", IrisBiome.class, boolean.class);
+        Param parameter = method.getParameters()[0].getAnnotation(Param.class);
+
+        assertEquals(ReachableBiomeHandler.class, parameter.customHandler());
+    }
+}

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

@@ -1,10 +1,12 @@
 package art.arcane.iris.core.commands;
 
+import art.arcane.iris.engine.object.IrisDimension;
 import art.arcane.volmlib.util.director.compat.DirectorAnnotationCompatibility;
 import art.arcane.volmlib.util.director.runtime.DirectorNodeDescriptor;
 import art.arcane.volmlib.util.director.runtime.DirectorParameterDescriptor;
 import org.junit.Test;
 
+import java.lang.reflect.Method;
 import java.util.List;
 
 import static org.junit.Assert.assertEquals;
@@ -52,8 +54,23 @@ public class CommandPackOptionalPackContractTest {
         assertFalse(CommandPack.wantsAllPacks("overworld"));
     }
 
-    private static java.lang.reflect.Method findMethod(String name) {
-        for (java.lang.reflect.Method method : CommandPack.class.getDeclaredMethods()) {
+    @Test
+    public void packageCommandIsOwnedByPackNamespace() throws Exception {
+        Method method = CommandPack.class.getDeclaredMethod(
+                "pkg",
+                IrisDimension.class,
+                boolean.class,
+                boolean.class
+        );
+        DirectorNodeDescriptor descriptor = DirectorAnnotationCompatibility.fromMethod(method).orElseThrow();
+        assertTrue(descriptor.getAliases().contains("package"));
+        for (Method studioMethod : CommandStudio.class.getDeclaredMethods()) {
+            assertFalse("Studio must not retain the package command", studioMethod.getName().equals("pkg"));
+        }
+    }
+
+    private static Method findMethod(String name) {
+        for (Method method : CommandPack.class.getDeclaredMethods()) {
             if (method.getName().equals(name)) {
                 return method;
             }

adapters/bukkit/plugin/src/test/java/art/arcane/iris/core/service/IrisTerrainSVCTest.java

@@ -5,12 +5,10 @@ import art.arcane.iris.api.terrain.IrisColumnQuery;
 import art.arcane.iris.api.terrain.IrisRiverState;
 import art.arcane.iris.api.terrain.IrisSurfaceKind;
 import art.arcane.iris.api.terrain.IrisTerrainService;
-import art.arcane.iris.engine.river.RiverEdgeId;
-import art.arcane.iris.engine.river.RiverNodeId;
-import art.arcane.iris.engine.river.RiverRouteState;
-import art.arcane.iris.engine.river.RiverSample;
-import art.arcane.iris.engine.river.RiverSection;
-import art.arcane.iris.engine.river.runtime.IrisRiverSurfaceSample;
+import art.arcane.iris.engine.hydrology.HydrologyColumnLayer;
+import art.arcane.iris.engine.hydrology.HydrologyColumnSample;
+import art.arcane.iris.engine.hydrology.HydrologyFeatureRef;
+import art.arcane.iris.engine.hydrology.HydrologyFeatureType;
 import art.arcane.iris.util.common.plugin.IrisService;
 import org.bukkit.World;
 import org.junit.Test;
@@ -19,6 +17,7 @@ import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.EnumSet;
+import java.util.List;
 import java.util.Optional;
 import java.util.OptionalInt;
 import java.util.concurrent.atomic.AtomicInteger;
@@ -104,36 +103,46 @@ public class IrisTerrainSVCTest {
     }
 
     @Test
-    public void riverRouteStatesMapToThePublicDiagnosticStates() {
-        assertEquals(IrisRiverState.NONE, IrisTerrainSVC.riverState(
-                new IrisRiverSurfaceSample(RiverSample.none(), 70D, 70D, 70D, false, false)
-        ));
-        assertEquals(IrisRiverState.WET, IrisTerrainSVC.riverState(river(RiverRouteState.WET)));
-        assertEquals(IrisRiverState.DRY, IrisTerrainSVC.riverState(river(RiverRouteState.DRY)));
-        assertEquals(IrisRiverState.NONE, IrisTerrainSVC.riverState(river(RiverRouteState.SUPPRESSED)));
+    public void acceptedHydrologyMapsToThePublicDiagnosticStates() {
+        assertEquals(IrisRiverState.NONE, IrisTerrainSVC.riverState(null));
+        assertEquals(IrisRiverState.WET, IrisTerrainSVC.riverState(river(true)));
+        assertEquals(IrisRiverState.DRY, IrisTerrainSVC.riverState(river(false)));
     }
 
-    private static IrisRiverSurfaceSample river(RiverRouteState state) {
-        RiverSection section = switch (state) {
-            case WET -> RiverSection.CHANNEL;
-            case DRY -> RiverSection.DRY_CHANNEL;
-            case SUPPRESSED -> RiverSection.NONE;
-        };
-        RiverSample sample = new RiverSample(
-                true,
-                state,
-                section,
-                0D,
-                0.5D,
-                1D,
+    private static HydrologyColumnSample river(boolean connectedFluid) {
+        HydrologyFeatureRef feature = new HydrologyFeatureRef(
+                1L,
+                HydrologyFeatureType.SURFACE_POOL,
+                2L,
+                3L,
+                0,
+                63,
+                0,
                 1,
-                1,
-                8D,
-                4D,
-                3D,
-                false,
-                RiverEdgeId.of(new RiverNodeId(0, 0), new RiverNodeId(1, 0))
+                0,
+                false
         );
-        return new IrisRiverSurfaceSample(sample, 70D, 60D, 63D, false, state == RiverRouteState.WET);
+        HydrologyColumnLayer layer = new HydrologyColumnLayer(
+                feature,
+                60,
+                63,
+                63,
+                true,
+                false,
+                false,
+                connectedFluid,
+                false,
+                false,
+                true,
+                connectedFluid,
+                false,
+                "water",
+                "river",
+                "mouth",
+                "shore",
+                "dry",
+                "cave"
+        );
+        return new HydrologyColumnSample(0, 0, 70, 63, false, "parent", List.of(layer));
     }
 }

adapters/bukkit/plugin/src/test/java/art/arcane/iris/core/service/terrain/IrisSurfaceClassifierTest.java

@@ -1,15 +1,15 @@
 package art.arcane.iris.core.service.terrain;
 
 import art.arcane.iris.api.terrain.IrisSurfaceKind;
+import art.arcane.iris.engine.hydrology.HydrologyColumnLayer;
+import art.arcane.iris.engine.hydrology.HydrologyColumnSample;
+import art.arcane.iris.engine.hydrology.HydrologyFeatureRef;
+import art.arcane.iris.engine.hydrology.HydrologyFeatureType;
 import art.arcane.iris.engine.object.InferredType;
-import art.arcane.iris.engine.river.RiverEdgeId;
-import art.arcane.iris.engine.river.RiverNodeId;
-import art.arcane.iris.engine.river.RiverRouteState;
-import art.arcane.iris.engine.river.RiverSample;
-import art.arcane.iris.engine.river.RiverSection;
-import art.arcane.iris.engine.river.runtime.IrisRiverSurfaceSample;
 import org.junit.Test;
 
+import java.util.List;
+
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertTrue;
@@ -59,91 +59,108 @@ public class IrisSurfaceClassifierTest {
 
             IrisSurfaceKind expected = IrisSurfaceClassifier.classify(surface, FLUID, null);
             for (InferredType inferredType : InferredType.values()) {
-                assertEquals("surface=" + surface + " type=" + inferredType,
-                        expected, IrisSurfaceClassifier.classify(surface, FLUID, inferredType));
+                assertEquals(
+                        "surface=" + surface + " type=" + inferredType,
+                        expected,
+                        IrisSurfaceClassifier.classify(surface, FLUID, inferredType)
+                );
             }
         }
     }
 
     @Test
-    public void activeRiverGeometryOverridesGenericOceanAndLandKinds() {
+    public void acceptedSurfaceRolesOverrideGenericOceanAndLandKinds() {
         assertEquals(IrisSurfaceKind.RIVER, IrisSurfaceClassifier.classify(
                 60,
                 63,
                 InferredType.SEA,
-                river(RiverRouteState.WET, RiverSection.CHANNEL)
+                hydrology(HydrologyFeatureType.SURFACE_POOL, true, false, true)
         ));
         assertEquals(IrisSurfaceKind.RIVER, IrisSurfaceClassifier.classify(
                 60,
                 63,
                 InferredType.SEA,
-                river(RiverRouteState.WET, RiverSection.MOUTH)
+                hydrology(HydrologyFeatureType.MOUTH, true, false, true)
         ));
         assertEquals(IrisSurfaceKind.RIVER_SHORE, IrisSurfaceClassifier.classify(
                 64,
                 63,
                 InferredType.SHORE,
-                river(RiverRouteState.WET, RiverSection.BANK)
+                hydrology(HydrologyFeatureType.SURFACE_POOL, false, true, false)
         ));
         assertEquals(IrisSurfaceKind.DRY_CHANNEL, IrisSurfaceClassifier.classify(
                 60,
                 60,
                 InferredType.LAND,
-                river(RiverRouteState.DRY, RiverSection.DRY_CHANNEL)
+                hydrology(HydrologyFeatureType.SURFACE_POOL, true, false, false)
         ));
         assertEquals(IrisSurfaceKind.LAND, IrisSurfaceClassifier.classify(
                 60,
                 60,
                 InferredType.LAND,
-                river(RiverRouteState.DRY, RiverSection.DRY_BANK)
+                hydrology(HydrologyFeatureType.SURFACE_POOL, false, false, false)
         ));
     }
 
     @Test
-    public void voidClassificationWinsOverRiverGeometry() {
-        for (RiverSection section : RiverSection.values()) {
-            if (section == RiverSection.NONE) {
-                continue;
-            }
-            RiverRouteState state = section == RiverSection.DRY_CHANNEL || section == RiverSection.DRY_BANK
-                    ? RiverRouteState.DRY
-                    : RiverRouteState.WET;
-            assertEquals(IrisSurfaceKind.VOID, IrisSurfaceClassifier.classify(
-                    0,
-                    63,
-                    InferredType.LAND,
-                    river(state, section)
-            ));
-        }
+    public void voidClassificationWinsOverAcceptedRiverGeometry() {
+        assertEquals(IrisSurfaceKind.VOID, IrisSurfaceClassifier.classify(
+                0,
+                63,
+                InferredType.LAND,
+                hydrology(HydrologyFeatureType.SURFACE_POOL, true, false, true)
+        ));
     }
 
     @Test
-    public void suppressedRoutesDoNotCreatePublicRiverSurfaceKinds() {
+    public void absentRejectedCandidatesDoNotCreatePublicRiverKinds() {
         assertEquals(IrisSurfaceKind.LAND, IrisSurfaceClassifier.classify(
                 64,
                 63,
                 InferredType.LAND,
-                river(RiverRouteState.SUPPRESSED, RiverSection.CHANNEL)
+                null
         ));
     }
 
-    private static IrisRiverSurfaceSample river(RiverRouteState state, RiverSection section) {
-        RiverSample sample = new RiverSample(
-                true,
-                state,
-                section,
-                0D,
-                0.5D,
-                1D,
+    private static HydrologyColumnSample hydrology(
+            HydrologyFeatureType type,
+            boolean channel,
+            boolean shore,
+            boolean connectedFluid
+    ) {
+        HydrologyFeatureRef feature = new HydrologyFeatureRef(
+                1L,
+                type,
+                2L,
+                3L,
+                0,
+                63,
+                0,
                 1,
-                1,
-                8D,
-                4D,
-                3D,
-                false,
-                RiverEdgeId.of(new RiverNodeId(0, 0), new RiverNodeId(1, 0))
+                0,
+                false
         );
-        double waterSurface = state == RiverRouteState.WET ? 63D : 60D;
-        return new IrisRiverSurfaceSample(sample, 70D, 60D, waterSurface, false, state == RiverRouteState.WET);
+        HydrologyColumnLayer layer = new HydrologyColumnLayer(
+                feature,
+                60,
+                63,
+                63,
+                channel,
+                shore,
+                !channel && !shore,
+                connectedFluid,
+                false,
+                false,
+                true,
+                connectedFluid && channel,
+                false,
+                "water",
+                "river",
+                "mouth",
+                "shore",
+                "dry",
+                "cave"
+        );
+        return new HydrologyColumnSample(0, 0, 70, 63, false, "parent", List.of(layer));
     }
 }