chore(release): merge dev into main for v0.3.10

Author: BAKAOLC

Const.cs

@@ -22,7 +22,7 @@ public static class Const
         ///     Assembly / manifest version string.
         ///     程序集/清单版本字符串。
         /// </summary>
-        public const string Version = "0.3.9";
+        public const string Version = "0.3.10";
 
         /// <summary>
         ///     Root key for RitsuLib JSON settings under the mod’s user folder.

Content/DynamicActContentPatcher.cs

@@ -35,6 +35,9 @@ internal static void EnsurePatched()
                     DynamicPatchBuilder.FromMethod(typeof(DynamicActContentPatcher), nameof(AllAncientsPostfix));
                 var encountersPostfix =
                     DynamicPatchBuilder.FromMethod(typeof(DynamicActContentPatcher), nameof(AllEncountersPostfix));
+                var bossDiscoveryOrderPostfix = DynamicPatchBuilder.FromMethod(
+                    typeof(DynamicActContentPatcher),
+                    nameof(BossDiscoveryOrderPostfix));
                 var unlockedAncientsPostfix = DynamicPatchBuilder.FromMethod(
                     typeof(DynamicActContentPatcher),
                     nameof(GetUnlockedAncientsPostfix));
@@ -43,6 +46,12 @@ internal static void EnsurePatched()
                 {
                     TryAddPropertyGetterPatch(builder, actType, nameof(ActModel.AllEvents), eventsPostfix, logger);
                     TryAddPropertyGetterPatch(builder, actType, nameof(ActModel.AllAncients), ancientsPostfix, logger);
+                    TryAddPropertyGetterPatch(
+                        builder,
+                        actType,
+                        nameof(ActModel.BossDiscoveryOrder),
+                        bossDiscoveryOrderPostfix,
+                        logger);
                     TryAddMethodPatch(
                         builder,
                         actType,
@@ -133,8 +142,17 @@ private static void AllAncientsPostfix(ActModel __instance, ref IEnumerable<Anci
         private static void AllEncountersPostfix(ActModel __instance, ref IEnumerable<EncounterModel> __result)
             // ReSharper restore InconsistentNaming
         {
-            __result = ModContentRegistry.AppendGlobalEncounters(
-                ModContentRegistry.AppendActEncounters(__instance, __result));
+            __result = ModEncounterActValidityFilter.FilterForAct(
+                __instance,
+                ModContentRegistry.AppendGlobalEncounters(
+                    ModContentRegistry.AppendActEncounters(__instance, __result)));
+        }
+
+        // ReSharper disable InconsistentNaming
+        private static void BossDiscoveryOrderPostfix(ActModel __instance, ref IEnumerable<EncounterModel> __result)
+            // ReSharper restore InconsistentNaming
+        {
+            __result = ModEncounterActValidityFilter.FilterForAct(__instance, __result);
         }
 
         // ReSharper disable InconsistentNaming

Content/Patches/ActContentPatches.cs

@@ -16,7 +16,7 @@ public class DynamicActContentPatchBootstrap : IPatchMethod
 
         /// <inheritdoc />
         public static string Description =>
-            "Dynamically patch all loaded ActModel implementations for registered events and ancients";
+            "Dynamically patch all loaded ActModel implementations for registered events, ancients, and encounters";
 
         /// <inheritdoc />
         public static bool IsCritical => true;

Diagnostics/Commands/SelfCheckConsoleCommands.cs

@@ -1,6 +1,7 @@
 using MegaCrit.Sts2.Core.DevConsole;
 using MegaCrit.Sts2.Core.DevConsole.ConsoleCommands;
 using MegaCrit.Sts2.Core.Entities.Players;
+using STS2RitsuLib.Settings;
 
 namespace STS2RitsuLib.Diagnostics.Commands
 {
@@ -10,17 +11,19 @@ namespace STS2RitsuLib.Diagnostics.Commands
     /// </summary>
     public sealed class RitsuLibConsoleCmd : AbstractConsoleCmd
     {
-        private static readonly string[] RootCommands = ["selfcheck"];
+        private static readonly string[] RootCommands = ["selfcheck", "settings"];
         private static readonly string[] SelfCheckActions = ["run", "open-output"];
+        private static readonly string[] SettingsActions = ["open"];
 
         /// <inheritdoc />
         public override string CmdName => "ritsulib";
 
         /// <inheritdoc />
-        public override string Args => "selfcheck run|open-output";
+        public override string Args =>
+            "selfcheck run|open-output OR settings open <modId> [pageId] [sectionId] [entryId]";
 
         /// <inheritdoc />
-        public override string Description => "RitsuLib tools: selfcheck run/open-output.";
+        public override string Description => "RitsuLib tools: selfcheck run/open-output; settings open.";
 
         /// <inheritdoc />
         public override bool IsNetworked => false;
@@ -34,6 +37,9 @@ public override CompletionResult GetArgumentCompletions(Player? player, string[]
                 return CompleteArgument(RootCommands, [], partial, CompletionType.Subcommand);
             }
 
+            if (args[0].Equals("settings", StringComparison.OrdinalIgnoreCase))
+                return CompleteSettingsArguments(args);
+
             if (!args[0].Equals("selfcheck", StringComparison.OrdinalIgnoreCase))
                 return base.GetArgumentCompletions(player, args);
             {
@@ -46,8 +52,11 @@ public override CompletionResult GetArgumentCompletions(Player? player, string[]
         /// <inheritdoc />
         public override CmdResult Process(Player? issuingPlayer, string[] args)
         {
+            if (args.Length >= 1 && args[0].Equals("settings", StringComparison.OrdinalIgnoreCase))
+                return ProcessSettings(args);
+
             if (args.Length < 2 || !args[0].Equals("selfcheck", StringComparison.OrdinalIgnoreCase))
-                return new(false, "Usage: ritsulib selfcheck run|open-output");
+                return new(false, UsageText());
 
             if (args[1].Equals("run", StringComparison.OrdinalIgnoreCase))
             {
@@ -56,9 +65,144 @@ public override CmdResult Process(Player? issuingPlayer, string[] args)
             }
 
             if (!args[1].Equals("open-output", StringComparison.OrdinalIgnoreCase))
-                return new(false, "Usage: ritsulib selfcheck run|open-output");
+                return new(false, UsageText());
             SelfCheckBundleCoordinator.TryOpenOutputFolderFromSettings();
             return new(true, "Requested to open RitsuLib self-check output folder.");
         }
+
+        private static CmdResult ProcessSettings(string[] args)
+        {
+            if (args.Length < 3 || args.Length > 6 || !args[1].Equals("open", StringComparison.OrdinalIgnoreCase))
+                return new(false, UsageText());
+
+            var result = ModSettingsNavigator.RequestOpenByIds(
+                args[2],
+                GetOptionalArg(args, 3),
+                GetOptionalArg(args, 4),
+                GetOptionalArg(args, 5));
+            return new(result.Success, result.Message);
+        }
+
+        private CompletionResult CompleteSettingsArguments(string[] args)
+        {
+            var partial = args[^1];
+            var completed = args.Take(args.Length - 1).ToArray();
+            if (args.Length <= 2)
+                return CompleteArgument(SettingsActions, completed, partial, CompletionType.Subcommand);
+
+            if (!args[1].Equals("open", StringComparison.OrdinalIgnoreCase))
+                return base.GetArgumentCompletions(null, args);
+
+            return args.Length switch
+            {
+                3 => CompleteArgument(GetModIdCandidates(), completed, partial),
+                4 => CompleteArgument(GetPageIdCandidates(args[2]), completed, partial),
+                5 => CompleteArgument(GetSectionIdCandidates(args[2], args[3]), completed, partial),
+                6 => CompleteArgument(GetEntryIdCandidates(args[2], args[3], args[4]), completed, partial),
+                _ => base.GetArgumentCompletions(null, args),
+            };
+        }
+
+        private static string? GetOptionalArg(string[] args, int index)
+        {
+            return args.Length <= index || string.IsNullOrWhiteSpace(args[index]) ? null : args[index];
+        }
+
+        private static string UsageText()
+        {
+            return
+                "Usage: ritsulib selfcheck run|open-output OR ritsulib settings open <modId> [pageId] [sectionId] [entryId]";
+        }
+
+        private static string[] GetModIdCandidates()
+        {
+            RefreshSettingsPagesForCompletion();
+            return ModSettingsRegistry.GetPages()
+                .Where(IsPageVisible)
+                .Select(static page => page.ModId)
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .Order(StringComparer.OrdinalIgnoreCase)
+                .ToArray();
+        }
+
+        private static string[] GetPageIdCandidates(string modId)
+        {
+            RefreshSettingsPagesForCompletion();
+            return ModSettingsRegistry.GetPages()
+                .Where(page => string.Equals(page.ModId, modId, StringComparison.OrdinalIgnoreCase))
+                .Where(IsPageVisible)
+                .Select(static page => page.Id)
+                .Order(StringComparer.OrdinalIgnoreCase)
+                .ToArray();
+        }
+
+        private static string[] GetSectionIdCandidates(string modId, string pageId)
+        {
+            RefreshSettingsPagesForCompletion();
+            return ModSettingsRegistry.TryGetPage(modId, pageId, out var page) && page != null && IsPageVisible(page)
+                ? page.Sections.Where(IsSectionVisible).Select(static section => section.Id)
+                    .Order(StringComparer.OrdinalIgnoreCase).ToArray()
+                : [];
+        }
+
+        private static string[] GetEntryIdCandidates(string modId, string pageId, string sectionId)
+        {
+            RefreshSettingsPagesForCompletion();
+            if (!ModSettingsRegistry.TryGetPage(modId, pageId, out var page) || page == null || !IsPageVisible(page))
+                return [];
+
+            var section = page.Sections.FirstOrDefault(s => string.Equals(s.Id, sectionId,
+                StringComparison.OrdinalIgnoreCase));
+            return section == null || !IsSectionVisible(section)
+                ? []
+                : section.Entries.Where(IsEntryVisible).Select(static entry => entry.Id)
+                    .Order(StringComparer.OrdinalIgnoreCase).ToArray();
+        }
+
+        private static void RefreshSettingsPagesForCompletion()
+        {
+            try
+            {
+                RitsuLibModSettingsBootstrap.EnsureFrameworkPagesRegistered();
+                ModSettingsMirrorRegistrarBootstrap.TryRegisterMirroredPages();
+                RitsuLibModSettingsBootstrap.RefreshDynamicPages();
+            }
+            catch
+            {
+                // Completion is best-effort; command execution reports concrete failures.
+            }
+        }
+
+        private static bool IsPageVisible(ModSettingsPage page)
+        {
+            return ModSettingsHostSurfaceResolver.IsVisibleOnCurrentHost(page.VisibleOnHostSurfaces) &&
+                   SafePredicate(page.VisibleWhen);
+        }
+
+        private static bool IsSectionVisible(ModSettingsSection section)
+        {
+            return ModSettingsHostSurfaceResolver.IsVisibleOnCurrentHost(section.VisibleOnHostSurfaces) &&
+                   SafePredicate(section.VisibleWhen);
+        }
+
+        private static bool IsEntryVisible(ModSettingsEntryDefinition entry)
+        {
+            return SafePredicate(entry.VisibilityPredicate);
+        }
+
+        private static bool SafePredicate(Func<bool>? predicate)
+        {
+            if (predicate == null)
+                return true;
+
+            try
+            {
+                return predicate();
+            }
+            catch
+            {
+                return true;
+            }
+        }
     }
 }

STS2-RitsuLib.csproj

@@ -33,7 +33,7 @@
 
     <PropertyGroup Label="NuGet package">
         <IsPackable>true</IsPackable>
-        <Version>0.3.9</Version>
+        <Version>0.3.10</Version>
         <Authors>OLC</Authors>
         <Description>Shared framework library for Slay the Spire 2 mods.</Description>
         <PackageReadmeFile>README.md</PackageReadmeFile>

Scaffolding/Content/IModEncounterActValidity.cs

@@ -0,0 +1,19 @@
+using MegaCrit.Sts2.Core.Models;
+
+namespace STS2RitsuLib.Scaffolding.Content
+{
+    /// <summary>
+    ///     Optional gate for whether a mod <see cref="EncounterModel" /> may enter an act's encounter pool for a given
+    ///     <see cref="ActModel" /> during room generation. Implement on
+    ///     <see cref="ModEncounterTemplate" /> or your encounter type; the framework applies it in
+    ///     <see cref="ModEncounterActValidityFilter" />.
+    /// </summary>
+    public interface IModEncounterActValidity
+    {
+        /// <summary>
+        ///     When false, this encounter is excluded from <see cref="ActModel.GenerateAllEncounters" /> results for
+        ///     <paramref name="act" />. This covers monster, elite, and boss encounter pools.
+        /// </summary>
+        bool IsValidForAct(ActModel act);
+    }
+}

Scaffolding/Content/ModEncounterActValidityFilter.cs

@@ -0,0 +1,35 @@
+using MegaCrit.Sts2.Core.Models;
+
+namespace STS2RitsuLib.Scaffolding.Content
+{
+    /// <summary>
+    ///     Applies <see cref="IModEncounterActValidity" /> when building per-act encounter candidate pools.
+    /// </summary>
+    public static class ModEncounterActValidityFilter
+    {
+        /// <summary>
+        ///     Returns whether <paramref name="encounter" /> may appear for <paramref name="act" />.
+        ///     Encounters that do not implement <see cref="IModEncounterActValidity" /> are always allowed.
+        /// </summary>
+        public static bool IsValidForAct(ActModel act, EncounterModel encounter)
+        {
+            ArgumentNullException.ThrowIfNull(act);
+            ArgumentNullException.ThrowIfNull(encounter);
+
+            return encounter is not IModEncounterActValidity validity || validity.IsValidForAct(act);
+        }
+
+        /// <summary>
+        ///     Keeps only encounters that pass <see cref="IsValidForAct" /> for <paramref name="act" />.
+        /// </summary>
+        public static IEnumerable<EncounterModel> FilterForAct(
+            ActModel act,
+            IEnumerable<EncounterModel> encounters)
+        {
+            ArgumentNullException.ThrowIfNull(act);
+            ArgumentNullException.ThrowIfNull(encounters);
+
+            return encounters.Where(encounter => IsValidForAct(act, encounter));
+        }
+    }
+}

Scaffolding/Content/ModEncounterTemplate.cs

@@ -8,7 +8,8 @@ namespace STS2RitsuLib.Scaffolding.Content
 {
     /// <summary>
     ///     Base <see cref="EncounterModel" /> for mods: <see cref="IModEncounterAssetOverrides" /> (combat scene path,
-    ///     backgrounds, boss node, map-node preload, extra paths), optional <see cref="TryCreateEncounterCombatScene" />.
+    ///     backgrounds, boss node, map-node preload, extra paths), optional <see cref="TryCreateEncounterCombatScene" />,
+    ///     and <see cref="IModEncounterActValidity" /> for act-specific spawn gating.
     ///     The background pipeline matches vanilla <c>EncounterModel.HasCustomBackground</c> semantics, with an explicit
     ///     switch to keep using the act’s combat
     ///     background when desired. For disk-free backgrounds, set <see cref="UseProgrammaticCombatBackground" /> and
@@ -37,7 +38,7 @@ namespace STS2RitsuLib.Scaffolding.Content
     ///     <para />
     /// </summary>
     public abstract class ModEncounterTemplate : EncounterModel, IModEncounterAssetOverrides,
-        IModEncounterCombatSceneFactory
+        IModEncounterCombatSceneFactory, IModEncounterActValidity
     {
         private BackgroundAssets? _programmaticCombatBackgroundSlot;
 
@@ -91,6 +92,12 @@ public abstract class ModEncounterTemplate : EncounterModel, IModEncounterAssetO
         /// </summary>
         protected virtual bool SuppliesEncounterCombatSceneFromFactory => false;
 
+        /// <inheritdoc />
+        public virtual bool IsValidForAct(ActModel act)
+        {
+            return true;
+        }
+
         /// <inheritdoc />
         public virtual EncounterAssetProfile AssetProfile => EncounterAssetProfile.Empty;
 

Settings/Localization/ModSettingsUi/eng.json

@@ -430,6 +430,8 @@
   "button.actionsShort": "Actions",
   "button.actionsGlyph": "\u22ee",
   "button.resetDefault": "Reset to default",
+  "button.resetPageDefaults": "Reset page to defaults",
+  "button.resetSectionDefaults": "Reset section to defaults",
   "color.title": "Color Editor",
   "color.mode.rgb": "RGB",
   "color.mode.hsv": "HSV",

Settings/Localization/ModSettingsUi/zhs.json

@@ -430,6 +430,8 @@
   "button.actionsShort": "操作",
   "button.actionsGlyph": "\u22ee",
   "button.resetDefault": "还原默认值",
+  "button.resetPageDefaults": "还原本页默认值",
+  "button.resetSectionDefaults": "还原本分组默认值",
   "color.title": "颜色编辑器",
   "color.mode.rgb": "RGB",
   "color.mode.hsv": "HSV",