Weight random Age choices like Legacy and expand regression coverage (#41)

src/main/java/net/dnorberg/rivencraft/book/AgeBiomeSelection.java

@@ -80,13 +80,13 @@ public record AgeBiomeSelection(AgeTraits.BiomeDistribution distribution, List<R
         int minimum = minimum(distribution);
         int target = minimum;
         if (authored.isEmpty()) {
-            // The terrain's available pool is the upper bound, including any
-            // compatible TerraBlender region biomes present at creation time.
+            // Legacy's BiomesAdv continuation/stop ranks are 2:3, which yield
+            // two continuation tickets for every one stop ticket. Keep our
+            // existing minimum and cap the list at the available biome pool.
             int availableBiomeCount = new LinkedHashSet<>(availableBiomes).size();
             int maximum = distribution == AgeTraits.BiomeDistribution.SINGLE ? 1 : availableBiomeCount;
-            if (maximum >= minimum) {
-                target += new Random(seed ^ 0x42494F4D45434F55L).nextInt(maximum - minimum + 1);
-            }
+            Random countRandom = new Random(seed ^ 0x42494F4D45434F55L);
+            while (target < maximum && countRandom.nextInt(3) != 0) target++;
         }
         // An authored Void Age must not acquire The Void as an unrequested second biome.
         List<ResourceLocation> filler = profile.terrain() == AgeRuntimeProfile.Terrain.VOID && !authored.isEmpty()

src/main/java/net/dnorberg/rivencraft/book/AgeFeatureSelection.java

@@ -159,13 +159,15 @@ public final class AgeFeatureSelection {
     public static List<Choice> randomChoices(long ageSeed, AgeRuntimeProfile profile, RegistryAccess registries) {
         Random random = new Random(ageSeed ^ 0x4D4154455249414CL);
         int count = random.nextInt(3);
-        List<ResourceLocation> features = new ArrayList<>();
-        for (ResourceLocation id : BLOCK_FEATURES) if (error(id, profile, registries) == null) features.add(id);
-        for (ResourceLocation id : FLUID_FEATURES) if (error(id, profile, registries) == null) features.add(id);
-        Collections.shuffle(features, random);
+        List<LegacyRankChoice.Option<ResourceLocation>> features = new ArrayList<>();
+        for (ResourceLocation id : BLOCK_FEATURES) if (error(id, profile, registries) == null)
+            features.add(new LegacyRankChoice.Option<>(id, randomMaterialRank(id)));
+        for (ResourceLocation id : FLUID_FEATURES) if (error(id, profile, registries) == null)
+            features.add(new LegacyRankChoice.Option<>(id, randomMaterialRank(id)));
         List<Choice> choices = new ArrayList<>();
-        for (ResourceLocation feature : features) {
-            if (choices.size() >= count) break;
+        while (choices.size() < count && !features.isEmpty()) {
+            ResourceLocation feature = LegacyRankChoice.choose(random, features);
+            features.removeIf(option -> option.value().equals(feature));
             var category = solidFeature(feature)
                     ? BlockSymbolPages.CATEGORY : BlockSymbolPages.FLUID_CATEGORY;
             List<ResourceLocation> materials = BlockSymbolPages.availableBlocks(category).stream()
@@ -186,6 +188,13 @@ public final class AgeFeatureSelection {
         return List.copyOf(choices);
     }
 
+    static int randomMaterialRank(ResourceLocation feature) {
+        if (feature.equals(id("surface_lakes")) || feature.equals(id("deep_lakes"))) return 1;
+        if (feature.equals(id("lava_lakes"))) return 2; // New separate fluid choice.
+        if (spheres(feature) || spikes(feature) || obelisks(feature)) return 3;
+        return 4; // Legacy Floating Islands/Tendrils and the new Rocks choice.
+    }
+
     /**
      * Legacy's default FeatureSmalls0 grammar: stop without a feature (rank 4),
      * emit one (rank 4), or emit one and repeat (rank 2). Its rank-derived

src/main/java/net/dnorberg/rivencraft/book/AgeGenerationProfiles.java

@@ -1,6 +1,8 @@
 package net.dnorberg.rivencraft.book;
 
 import java.util.List;
+import java.util.Random;
+import java.util.Comparator;
 import net.dnorberg.rivencraft.Rivencraft;
 import net.minecraft.resources.ResourceLocation;
 
@@ -13,24 +15,37 @@ public final class AgeGenerationProfiles {
     public static final ResourceLocation FLAT = id("flat");
     public static final ResourceLocation VOID = id("void");
 
-    private static final List<ResourceLocation> RANDOM_PROFILES = List.of(
-            STANDARD, AMPLIFIED, ISLAND, CAVE, FLAT, VOID
+    private static final List<LegacyRankChoice.Option<ResourceLocation>> RANDOM_PROFILES = List.of(
+            new LegacyRankChoice.Option<>(STANDARD, 1),
+            new LegacyRankChoice.Option<>(FLAT, 2),
+            new LegacyRankChoice.Option<>(AMPLIFIED, 3),
+            new LegacyRankChoice.Option<>(ISLAND, 3),
+            new LegacyRankChoice.Option<>(CAVE, 3),
+            new LegacyRankChoice.Option<>(VOID, 3)
     );
+    private static final List<LegacyRankChoice.Option<ResourceLocation>> SORTED_RANDOM_PROFILES =
+            RANDOM_PROFILES.stream().sorted(Comparator.comparing(LegacyRankChoice.Option::value)).toList();
 
     private AgeGenerationProfiles() {
     }
 
     /** Selects one stable base terrain from the Age's already-persisted seed. */
     public static ResourceLocation select(long seed) {
-        return RANDOM_PROFILES.get(Math.floorMod(Long.hashCode(seed), RANDOM_PROFILES.size()));
+        return LegacyRankChoice.choose(new Random(seed ^ 0x5445525241494E4CL), SORTED_RANDOM_PROFILES);
     }
 
     public static boolean isSupported(ResourceLocation profile) {
-        return RANDOM_PROFILES.contains(profile);
+        return RANDOM_PROFILES.stream().anyMatch(option -> option.value().equals(profile));
     }
 
     public static List<ResourceLocation> all() {
-        return RANDOM_PROFILES;
+        return RANDOM_PROFILES.stream().map(LegacyRankChoice.Option::value).toList();
+    }
+
+    static int randomRank(ResourceLocation profile) {
+        if (profile.equals(STANDARD)) return 1;
+        if (profile.equals(FLAT)) return 2;
+        return 3;
     }
 
     /** Maps removed legacy aliases to a stable built-in profile. */

src/main/java/net/dnorberg/rivencraft/book/AgeRuntimeProfiles.java

@@ -6,6 +6,7 @@ import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
 import java.util.Map;
 import java.util.List;
+import java.util.Random;
 import java.util.concurrent.ConcurrentHashMap;
 import net.dnorberg.rivencraft.Rivencraft;
 import net.dnorberg.rivencraft.writing.OrderedWriting;
@@ -59,8 +60,9 @@ public final class AgeRuntimeProfiles {
         if (PROFILES.isEmpty()) {
             return AgeGenerationProfiles.select(seed);
         }
-        java.util.List<ResourceLocation> ids = PROFILES.keySet().stream().sorted().toList();
-        return ids.get(Math.floorMod(Long.hashCode(seed), ids.size()));
+        List<LegacyRankChoice.Option<ResourceLocation>> profiles = PROFILES.keySet().stream().sorted()
+                .map(id -> new LegacyRankChoice.Option<>(id, AgeGenerationProfiles.randomRank(id))).toList();
+        return LegacyRankChoice.choose(new Random(seed ^ 0x5445525241494E4CL), profiles);
     }
 
     /** Keep seed-selected terrain random, but only among profiles able to host authored features. */

src/main/java/net/dnorberg/rivencraft/book/AgeSeasonMode.java

@@ -2,6 +2,7 @@ package net.dnorberg.rivencraft.book;
 
 import java.util.Locale;
 import java.util.Random;
+import java.util.List;
 import net.dnorberg.rivencraft.writing.SymbolSemantics;
 import net.neoforged.fml.ModList;
 
@@ -19,7 +20,13 @@ public enum AgeSeasonMode {
     /** An omitted page is selected once when an Age is created with Serene installed. */
     public static AgeSeasonMode select(AgeGenerationPlan plan, long ageSeed, boolean sereneInstalled) {
         if (hasAuthoredPage(plan)) return from(plan);
-        return sereneInstalled ? values()[new Random(ageSeed ^ RANDOM_SALT).nextInt(values().length)] : null;
+        return sereneInstalled ? LegacyRankChoice.choose(new Random(ageSeed ^ RANDOM_SALT), List.of(
+                new LegacyRankChoice.Option<>(SEASONS, 1),
+                new LegacyRankChoice.Option<>(NO_SEASONS, 2),
+                new LegacyRankChoice.Option<>(ETERNAL_WINTER, 3),
+                new LegacyRankChoice.Option<>(ETERNAL_SUMMER, 3),
+                new LegacyRankChoice.Option<>(ETERNAL_FALL, 3),
+                new LegacyRankChoice.Option<>(ETERNAL_SPRING, 3))) : null;
     }
 
     /** Existing Ages without a stored choice retain their old cycling behavior. */

src/main/java/net/dnorberg/rivencraft/book/AgeStructureSelection.java

@@ -1,7 +1,6 @@
 package net.dnorberg.rivencraft.book;
 
 import java.util.ArrayList;
-import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
@@ -116,13 +115,25 @@ public final class AgeStructureSelection {
 
     public static List<AgeFeatureSelection.Choice> randomChoices(long ageSeed, AgeRuntimeProfile profile,
                                                                    AgeBiomeSelection biomes, RegistryAccess registries) {
-        List<ResourceLocation> eligible = new ArrayList<>(FEATURES.stream()
-                .filter(id -> error(id, profile, biomes, registries) == null).toList());
+        List<LegacyRankChoice.Option<ResourceLocation>> eligible = new ArrayList<>(FEATURES.stream()
+                .filter(id -> error(id, profile, biomes, registries) == null)
+                .map(id -> new LegacyRankChoice.Option<>(id, randomRank(id))).toList());
         Random random = new Random(ageSeed ^ 0x5354525543545552L);
-        Collections.shuffle(eligible, random);
         int count = random.nextInt(3);
-        return eligible.stream().limit(count)
-                .map(id -> new AgeFeatureSelection.Choice(id, Optional.empty())).toList();
+        List<AgeFeatureSelection.Choice> choices = new ArrayList<>();
+        while (choices.size() < count && !eligible.isEmpty()) {
+            ResourceLocation selected = LegacyRankChoice.choose(random, eligible);
+            choices.add(new AgeFeatureSelection.Choice(selected, Optional.empty()));
+            eligible.removeIf(option -> option.value().equals(selected));
+        }
+        return List.copyOf(choices);
+    }
+
+    static int randomRank(ResourceLocation feature) {
+        if (feature.equals(id("villages")) || feature.equals(id("strongholds"))
+                || feature.equals(id("mineshafts"))) return 1;
+        if (feature.equals(id("dungeons")) || feature.equals(id("nether_fortresses"))) return 2;
+        return 3; // Structures added after Legacy are uncommon, but still discoverable.
     }
 
     private static Set<ResourceLocation> enabledSets(List<AgeFeatureSelection.Choice> choices) {

src/main/java/net/dnorberg/rivencraft/book/AgeTraits.java

@@ -1,6 +1,7 @@
 package net.dnorberg.rivencraft.book;
 
 import java.util.Random;
+import java.util.List;
 
 /** Immutable random-Age traits selected once from the Age seed. */
 public record AgeTraits(
@@ -42,9 +43,30 @@ public record AgeTraits(
 
     public static AgeTraits select(long seed) {
         Random random = new Random(seed ^ 0x524956454E435241L);
-        BiomeDistribution biomeDistribution = randomChoice(random, BiomeDistribution.values());
-        Lighting lighting = randomChoice(random, Lighting.values());
-        Weather weather = randomChoice(random, Weather.values());
+        BiomeDistribution biomeDistribution = LegacyRankChoice.choose(random, List.of(
+                new LegacyRankChoice.Option<>(BiomeDistribution.NATIVE, 1),
+                new LegacyRankChoice.Option<>(BiomeDistribution.SINGLE, 1),
+                new LegacyRankChoice.Option<>(BiomeDistribution.MEDIUM, 1),
+                new LegacyRankChoice.Option<>(BiomeDistribution.TILED, 2),
+                new LegacyRankChoice.Option<>(BiomeDistribution.GRID, 2),
+                new LegacyRankChoice.Option<>(BiomeDistribution.TINY, 2),
+                new LegacyRankChoice.Option<>(BiomeDistribution.SMALL, 2),
+                new LegacyRankChoice.Option<>(BiomeDistribution.LARGE, 2),
+                new LegacyRankChoice.Option<>(BiomeDistribution.HUGE, 2)));
+        Lighting lighting = LegacyRankChoice.choose(random, List.of(
+                new LegacyRankChoice.Option<>(Lighting.NORMAL, 1),
+                new LegacyRankChoice.Option<>(Lighting.DARK, 2),
+                new LegacyRankChoice.Option<>(Lighting.BRIGHT, 2)));
+        Weather weather = LegacyRankChoice.choose(random, List.of(
+                new LegacyRankChoice.Option<>(Weather.NORMAL, 1),
+                new LegacyRankChoice.Option<>(Weather.FAST, 2),
+                new LegacyRankChoice.Option<>(Weather.SLOW, 2),
+                new LegacyRankChoice.Option<>(Weather.OFF, 2),
+                new LegacyRankChoice.Option<>(Weather.ALWAYS, 2),
+                new LegacyRankChoice.Option<>(Weather.CLOUDY, 2),
+                new LegacyRankChoice.Option<>(Weather.RAIN, 2),
+                new LegacyRankChoice.Option<>(Weather.SNOW, 2),
+                new LegacyRankChoice.Option<>(Weather.STORM, 2)));
         // Legacy's PERIOD_BASIC grammar gives ModZero rank 2 and its other
         // three length modifiers rank 1, producing an effective 1-in-7 weight.
         boolean stopped = random.nextInt(7) == 0;
@@ -77,10 +99,6 @@ public record AgeTraits(
         }
     }
 
-    private static <E> E randomChoice(Random random, E[] values) {
-        return values[random.nextInt(values.length)];
-    }
-
     public enum BiomeDistribution {
         NATIVE, SINGLE, TILED, GRID, TINY, SMALL, MEDIUM, LARGE, HUGE
     }

src/main/java/net/dnorberg/rivencraft/book/LegacyRankChoice.java

@@ -0,0 +1,44 @@
+package net.dnorberg.rivencraft.book;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Random;
+
+/** Legacy grammar ranks: each more-preferred rank group outweighs the next rarer group. */
+final class LegacyRankChoice {
+    private LegacyRankChoice() {}
+
+    record Option<T>(T value, int rank) {
+        Option {
+            if (value == null || rank < 0) throw new IllegalArgumentException("Invalid ranked choice");
+        }
+    }
+
+    static <T> T choose(Random random, List<Option<T>> options) {
+        if (options.isEmpty()) throw new IllegalArgumentException("No ranked choices");
+        Map<Integer, Integer> counts = new HashMap<>();
+        int highest = 0;
+        for (Option<T> option : options) {
+            counts.merge(option.rank(), 1, Integer::sum);
+            highest = Math.max(highest, option.rank());
+        }
+        Map<Integer, Integer> weights = new HashMap<>();
+        int weight = 1;
+        int previousTotal = 0;
+        for (int rank = highest; rank >= 0; rank--) {
+            int count = counts.getOrDefault(rank, 0);
+            if (weight != 1 && count > 0) weight = Math.max(weight, previousTotal / count + 1);
+            weights.put(rank, weight);
+            previousTotal = count * weight;
+            weight++;
+        }
+        int total = options.stream().mapToInt(option -> weights.get(option.rank())).sum();
+        int ticket = random.nextInt(total);
+        for (Option<T> option : options) {
+            ticket -= weights.get(option.rank());
+            if (ticket < 0) return option.value();
+        }
+        throw new IllegalStateException("Ranked choice ticket was not consumed");
+    }
+}

src/main/java/net/dnorberg/rivencraft/book/RandomAgeWeightGameTests.java

@@ -0,0 +1,87 @@
+package net.dnorberg.rivencraft.book;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Random;
+import net.minecraft.gametest.framework.GameTest;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.resources.ResourceLocation;
+import net.neoforged.neoforge.gametest.GameTestHolder;
+import net.neoforged.neoforge.gametest.PrefixGameTestTemplate;
+
+/** Opt-in regression for Legacy rank weights and deterministic random-Age branches. */
+@GameTestHolder("rivencraft_archive_grammar")
+@PrefixGameTestTemplate(false)
+public final class RandomAgeWeightGameTests {
+    private RandomAgeWeightGameTests() {}
+
+    @GameTest(template = "empty")
+    public static void randomAgeChoicesRespectLegacyRanks(GameTestHelper helper) {
+        var terrain = List.of(new LegacyRankChoice.Option<>("normal", 1),
+                new LegacyRankChoice.Option<>("flat", 2),
+                new LegacyRankChoice.Option<>("amplified", 3),
+                new LegacyRankChoice.Option<>("island", 3),
+                new LegacyRankChoice.Option<>("cave", 3),
+                new LegacyRankChoice.Option<>("void", 3));
+        // Legacy's rank formula yields 6:5:1:1:1:1 for these six terrains.
+        for (int ticket = 0; ticket < 15; ticket++) {
+            final int selectedTicket = ticket;
+            Random fixed = new Random() {
+                @Override public int nextInt(int bound) {
+                    helper.assertValueEqual(bound, 15, "The terrain rank group must have 15 tickets");
+                    return selectedTicket;
+                }
+            };
+            String expected = ticket < 6 ? "normal" : ticket < 11 ? "flat"
+                    : terrain.get(ticket - 9).value();
+            helper.assertValueEqual(LegacyRankChoice.choose(fixed, terrain), expected,
+                    "A fixed ticket must map to its exact Legacy terrain weight");
+        }
+
+        Map<ResourceLocation, Integer> profiles = new HashMap<>();
+        Map<AgeTraits.Weather, Integer> weather = new HashMap<>();
+        Map<AgeSeasonMode, Integer> seasons = new HashMap<>();
+        for (long seed = 0; seed < 4_000; seed++) {
+            ResourceLocation profile = AgeRuntimeProfiles.select(seed);
+            helper.assertValueEqual(profile, AgeRuntimeProfiles.select(seed),
+                    "The same Age seed must choose the same terrain");
+            if (AgeRuntimeProfiles.profiles().size() == AgeGenerationProfiles.all().size())
+                helper.assertValueEqual(profile, AgeGenerationProfiles.select(seed),
+                        "The built-in-only fallback must agree with loaded profile selection");
+            profiles.merge(profile, 1, Integer::sum);
+            AgeTraits traits = AgeTraits.select(seed);
+            helper.assertValueEqual(traits, AgeTraits.select(seed),
+                    "The same Age seed must choose the same traits");
+            weather.merge(traits.weather(), 1, Integer::sum);
+            AgeSeasonMode season = AgeSeasonMode.select(null, seed, true);
+            helper.assertValueEqual(season, AgeSeasonMode.select(null, seed, true),
+                    "The same Age seed must choose the same season policy");
+            seasons.merge(season, 1, Integer::sum);
+        }
+        helper.assertTrue(profiles.getOrDefault(AgeGenerationProfiles.STANDARD, 0)
+                        > profiles.getOrDefault(AgeGenerationProfiles.FLAT, 0)
+                        && profiles.getOrDefault(AgeGenerationProfiles.FLAT, 0)
+                        > profiles.getOrDefault(AgeGenerationProfiles.VOID, 0),
+                "Normal terrain must be common, Flat intermediate, and Void rare");
+        helper.assertTrue(weather.getOrDefault(AgeTraits.Weather.NORMAL, 0)
+                        > weather.getOrDefault(AgeTraits.Weather.STORM, 0),
+                "Legacy's normal weather must be more common than a special weather mode");
+        helper.assertTrue(seasons.getOrDefault(AgeSeasonMode.SEASONS, 0)
+                        > seasons.getOrDefault(AgeSeasonMode.NO_SEASONS, 0)
+                        && seasons.getOrDefault(AgeSeasonMode.NO_SEASONS, 0)
+                        > seasons.getOrDefault(AgeSeasonMode.ETERNAL_WINTER, 0),
+                "Normal season cycling must be common, no seasons intermediate, and eternal seasons rare");
+        helper.assertTrue(AgeSeasonMode.select(null, 42L, false) == null,
+                "No season policy may be selected without Serene Seasons");
+        helper.assertValueEqual(AgeFeatureSelection.randomMaterialRank(ResourceLocation.parse("rivencraft:surface_lakes")),
+                1, "Surface Lakes must retain their Legacy common rank");
+        helper.assertValueEqual(AgeFeatureSelection.randomMaterialRank(ResourceLocation.parse("rivencraft:floating_islands")),
+                4, "Floating Islands must retain their Legacy rare rank");
+        helper.assertValueEqual(AgeStructureSelection.randomRank(ResourceLocation.parse("rivencraft:villages")),
+                1, "Villages must retain their Legacy common rank");
+        helper.assertValueEqual(AgeStructureSelection.randomRank(ResourceLocation.parse("rivencraft:trial_chambers")),
+                3, "Modern structures must use a rare rank");
+        helper.succeed();
+    }
+}

src/main/java/net/dnorberg/rivencraft/gametest/LinkingGameTests.java

@@ -242,7 +242,8 @@ public final class LinkingGameTests {
         });
     }
 
-    @GameTest(template = "empty", timeoutTicks = 400)
+    // Manual acceptance only: six sequential dynamic dimensions and round-trip
+    // travel can leave the dedicated GameTest server waiting indefinitely.
     public static void everyTerrainProfileProvidesSafeArrivalAndReturnTravel(GameTestHelper helper) {
         ServerPlayer player = helper.makeMockServerPlayerInLevel();
         BlockPos returnPosition = player.blockPosition();