feat(OrbManagement): introduce mod orb random pool and value display policies

BAKAOLC · BAKAOLC · commit 402db009a482 · 2026-05-23T17:19:53.000+08:00
- Added interfaces for controlling orb selection in random generation and value label display.
- Implemented patches to integrate mod orbs into the random orb pool and manage their display modes.
- Enhanced the ModOrbTemplate class to support new policies, allowing for greater customization of orb behavior.
- Updated documentation to reflect the new features and their usage in modding scenarios.
diff --git a/RitsuLibFramework.PatcherSetup.cs b/RitsuLibFramework.PatcherSetup.cs
@@ -279,6 +279,7 @@ private static void RegisterContentAssetPatches()
             patcher.RegisterPatch<OrbIconPatch>();
             patcher.RegisterPatch<OrbSpritePathPatch>();
             patcher.RegisterPatch<OrbAssetPathsPatch>();
+            patcher.RegisterPatch<NOrbValueDisplayPolicyPatch>();
 
             patcher.RegisterPatch<PotionImagePathPatch>();
             patcher.RegisterPatch<PotionTexturePatch>();
@@ -402,6 +403,7 @@ private static void RegisterContentRegistryPatches()
             patcher.RegisterPatch<RelicCollectionActListPatch>();
             patcher.RegisterPatch<AllPowersPatch>();
             patcher.RegisterPatch<AllOrbsPatch>();
+            patcher.RegisterPatch<OrbModelRandomPoolPolicyPatch>();
             patcher.RegisterPatch<AllSharedCardPoolsPatch>();
             patcher.RegisterPatch<AllSharedEventsPatch>();
             patcher.RegisterPatch<AllEventsPatch>();
diff --git a/Scaffolding/Content/ModOrbTemplate.cs b/Scaffolding/Content/ModOrbTemplate.cs
@@ -1,3 +1,4 @@
+using System.Globalization;
 using Godot;
 using MegaCrit.Sts2.Core.HoverTips;
 using MegaCrit.Sts2.Core.Models;
@@ -6,13 +7,103 @@
 
 namespace STS2RitsuLib.Scaffolding.Content
 {
+    /// <summary>
+    ///     Controls whether an orb can be selected by vanilla random-orb generation such as <c>OrbModel.GetRandomOrb</c>.
+    ///     控制充能球是否可被原版随机充能球生成（例如 <c>OrbModel.GetRandomOrb</c>）选中。
+    /// </summary>
+    public interface IModOrbRandomPoolPolicy
+    {
+        /// <summary>
+        ///     When true, RitsuLib adds this registered orb to the random-orb candidate pool. Defaults to false on
+        ///     <see cref="ModOrbTemplate" /> so custom orbs do not appear in random effects unless the author opts in.
+        ///     为 true 时，RitsuLib 会把此已注册充能球加入随机充能球候选池。<see cref="ModOrbTemplate" />
+        ///     默认为 false，因此自定义充能球不会在作者未选择加入时出现在随机效果中。
+        /// </summary>
+        bool AllowInRandomOrbPool { get; }
+    }
+
+    /// <summary>
+    ///     Value-label display mode for combat orb nodes. RitsuLib uses the vanilla <c>%PassiveAmount</c> and
+    ///     <c>%EvokeAmount</c> labels without repositioning them; a single visible label uses the vanilla single-value
+    ///     layout, while two visible labels use the vanilla stacked layout.
+    ///     战斗充能球节点的数值标签显示模式。RitsuLib 使用原版 <c>%PassiveAmount</c> 与
+    ///     <c>%EvokeAmount</c> 标签，不重新定位；单个可见标签使用原版单数值布局，两个可见标签使用原版堆叠布局。
+    /// </summary>
+    public enum ModOrbValueDisplayMode
+    {
+        /// <summary>
+        ///     Keep the base game's built-in type checks.
+        ///     保留游戏内建的类型判定。
+        /// </summary>
+        Vanilla = 0,
+
+        /// <summary>
+        ///     Hide both passive and evoke value labels.
+        ///     隐藏被动和激发两个数值标签。
+        /// </summary>
+        Hidden = 1,
+
+        /// <summary>
+        ///     Match the normal vanilla orb behavior: show the passive value normally and the evoke value while the orb is
+        ///     previewed as evoking. Only one label is visible at a time, so it uses the vanilla single-value layout.
+        ///     匹配普通原版充能球行为：平时显示被动值；当充能球被预览为激发时显示激发值。一次只显示一个标签，
+        ///     因此使用原版单数值布局。
+        /// </summary>
+        Contextual = 2,
+
+        /// <summary>
+        ///     Always show only the passive value text in the vanilla single-value layout.
+        ///     始终在原版单数值布局中显示被动值文本。
+        /// </summary>
+        SinglePassive = 3,
+
+        /// <summary>
+        ///     Always show only the evoke value text in the vanilla single-value layout.
+        ///     始终在原版单数值布局中显示激发值文本。
+        /// </summary>
+        SingleEvoke = 4,
+
+        /// <summary>
+        ///     Match the vanilla <c>DarkOrb</c> behavior: show passive and evoke value labels together in the vanilla
+        ///     stacked layout.
+        ///     匹配原版 <c>DarkOrb</c> 行为：在原版堆叠布局中同时显示被动值和激发值标签。
+        /// </summary>
+        Both = 5,
+    }
+
+    /// <summary>
+    ///     Controls the passive/evoke value labels rendered on an orb node.
+    ///     控制充能球节点上渲染的被动/激发数值标签。
+    /// </summary>
+    public interface IModOrbValueDisplayPolicy
+    {
+        /// <summary>
+        ///     Label visibility behavior. Use <see cref="ModOrbValueDisplayMode.Vanilla" /> to leave the game decision intact.
+        ///     标签可见性行为。使用 <see cref="ModOrbValueDisplayMode.Vanilla" /> 可保留游戏原判定。
+        /// </summary>
+        ModOrbValueDisplayMode ValueDisplayMode { get; }
+
+        /// <summary>
+        ///     Text rendered in the passive label when it is visible.
+        ///     被动标签可见时渲染的文本。
+        /// </summary>
+        string PassiveValueDisplayText { get; }
+
+        /// <summary>
+        ///     Text rendered in the evoke label when it is visible.
+        ///     激发标签可见时渲染的文本。
+        /// </summary>
+        string EvokeValueDisplayText { get; }
+    }
+
     /// <summary>
     ///     Base <see cref="OrbModel" /> for mods: keyword hover tips, dimmed UI color default, and
     ///     <see cref="IModOrbAssetOverrides" /> paths and optional <see cref="TryCreateOrbSprite" />.
     ///     Mod 充能球的基础 <see cref="OrbModel" />：提供关键词悬浮提示、变暗 UI 颜色默认值、
     ///     <see cref="IModOrbAssetOverrides" /> 路径，以及可选的 <see cref="TryCreateOrbSprite" />。
     /// </summary>
-    public abstract class ModOrbTemplate : OrbModel, IModOrbAssetOverrides, IModOrbSpriteFactory
+    public abstract class ModOrbTemplate : OrbModel, IModOrbAssetOverrides, IModOrbSpriteFactory,
+        IModOrbRandomPoolPolicy, IModOrbValueDisplayPolicy
     {
         /// <summary>
         ///     Keyword ids surfaced on this orb's hover tips. <b>Display-only</b>: unlike
@@ -52,11 +143,23 @@ public abstract class ModOrbTemplate : OrbModel, IModOrbAssetOverrides, IModOrbS
         /// <inheritdoc />
         public virtual string? CustomVisualsScenePath => AssetProfile.VisualsScenePath;
 
+        /// <inheritdoc />
+        public virtual bool AllowInRandomOrbPool => false;
+
         Node2D? IModOrbSpriteFactory.TryCreateOrbSprite()
         {
             return TryCreateOrbSprite();
         }
 
+        /// <inheritdoc />
+        public virtual ModOrbValueDisplayMode ValueDisplayMode => ModOrbValueDisplayMode.Vanilla;
+
+        /// <inheritdoc />
+        public virtual string PassiveValueDisplayText => PassiveVal.ToString("0", CultureInfo.InvariantCulture);
+
+        /// <inheritdoc />
+        public virtual string EvokeValueDisplayText => EvokeVal.ToString("0", CultureInfo.InvariantCulture);
+
         /// <summary>
         ///     Non-null node replaces the scene from <see cref="CustomVisualsScenePath" />; provide Spine and animations
         ///     compatible with <c>CreateSprite</c> callers if required.
diff --git a/Scaffolding/Content/Patches/ModOrbPolicyPatches.cs b/Scaffolding/Content/Patches/ModOrbPolicyPatches.cs
@@ -0,0 +1,173 @@
+using System.Reflection;
+using HarmonyLib;
+using MegaCrit.Sts2.addons.mega_text;
+using MegaCrit.Sts2.Core.Models;
+using MegaCrit.Sts2.Core.Nodes.Orbs;
+using MegaCrit.Sts2.Core.Random;
+using STS2RitsuLib.Patching.Models;
+
+namespace STS2RitsuLib.Scaffolding.Content.Patches
+{
+    internal static class ModOrbRandomPoolPolicyRuntime
+    {
+        private static readonly FieldInfo? VanillaValidOrbsField = AccessTools.Field(typeof(OrbModel), "_validOrbs");
+
+        public static bool HasModdedCandidates()
+        {
+            var vanillaIds = GetVanillaRandomOrbIds();
+            return vanillaIds.Length != 0 && ModelDb.Orbs.Any(orb => ShouldAddFromModelDbOrbs(vanillaIds, orb));
+        }
+
+        public static bool TryGetRandomOrb(Rng rng, out OrbModel orb)
+        {
+            var vanillaIds = GetVanillaRandomOrbIds();
+            if (vanillaIds.Length == 0)
+            {
+                orb = null!;
+                return false;
+            }
+
+            var candidates = BuildCandidates(vanillaIds);
+            var selected = rng.NextItem(candidates);
+            if (selected == null)
+            {
+                orb = null!;
+                return false;
+            }
+
+            orb = selected;
+            return true;
+        }
+
+        private static ModelId[] GetVanillaRandomOrbIds()
+        {
+            return VanillaValidOrbsField?.GetValue(null) as ModelId[] ?? [];
+        }
+
+        private static OrbModel[] BuildCandidates(IReadOnlyCollection<ModelId> vanillaIds)
+        {
+            return vanillaIds
+                .Select(static id => ModelDb.GetByIdOrNull<OrbModel>(id))
+                .OfType<OrbModel>()
+                .Concat(ModelDb.Orbs.Where(orb => ShouldAddFromModelDbOrbs(vanillaIds, orb)))
+                .DistinctBy(static orb => orb.Id)
+                .ToArray();
+        }
+
+        private static bool ShouldAddFromModelDbOrbs(IReadOnlyCollection<ModelId> vanillaIds, OrbModel orb)
+        {
+            return !vanillaIds.Contains(orb.Id) &&
+                   orb is IModOrbRandomPoolPolicy { AllowInRandomOrbPool: true };
+        }
+    }
+
+    /// <summary>
+    ///     Replaces <see cref="OrbModel.GetRandomOrb" /> only when registered mod orbs opt in to the random pool.
+    ///     仅当已注册 mod 充能球选择加入随机池时替换 <see cref="OrbModel.GetRandomOrb" />。
+    /// </summary>
+    public sealed class OrbModelRandomPoolPolicyPatch : IPatchMethod
+    {
+        /// <inheritdoc />
+        public static string PatchId => "orb_model_random_pool_policy";
+
+        /// <inheritdoc />
+        public static bool IsCritical => false;
+
+        /// <inheritdoc />
+        public static string Description => "Include opt-in mod orbs in OrbModel.GetRandomOrb";
+
+        /// <inheritdoc />
+        public static ModPatchTarget[] GetTargets()
+        {
+            return [new(typeof(OrbModel), nameof(OrbModel.GetRandomOrb), [typeof(Rng)])];
+        }
+
+        /// <summary>
+        ///     Uses the vanilla random pool plus registered <see cref="IModOrbRandomPoolPolicy" /> opt-in candidates.
+        ///     使用原版随机池，加上已注册且通过 <see cref="IModOrbRandomPoolPolicy" /> 选择加入的候选项。
+        /// </summary>
+        [HarmonyAfter(Const.BaseLibHarmonyId, Const.FrameworkContentRegistryHarmonyId)]
+        [HarmonyPriority(Priority.Last)]
+        // ReSharper disable once InconsistentNaming
+        public static bool Prefix(Rng rng, ref OrbModel __result)
+        {
+            if (!ModOrbRandomPoolPolicyRuntime.HasModdedCandidates())
+                return true;
+
+            if (!ModOrbRandomPoolPolicyRuntime.TryGetRandomOrb(rng, out var orb))
+                return true;
+
+            __result = orb;
+            return false;
+        }
+    }
+
+    internal static class ModOrbValueDisplayPolicyRuntime
+    {
+        private static readonly FieldInfo? PassiveLabelField = AccessTools.Field(typeof(NOrb), "_passiveLabel");
+        private static readonly FieldInfo? EvokeLabelField = AccessTools.Field(typeof(NOrb), "_evokeLabel");
+
+        public static void Apply(NOrb node, bool isEvoking)
+        {
+            if (node.Model is not IModOrbValueDisplayPolicy policy ||
+                policy.ValueDisplayMode == ModOrbValueDisplayMode.Vanilla)
+                return;
+
+            var passiveLabel = PassiveLabelField?.GetValue(node) as MegaLabel;
+            var evokeLabel = EvokeLabelField?.GetValue(node) as MegaLabel;
+            if (passiveLabel == null || evokeLabel == null)
+                return;
+
+            var (showPassive, showEvoke) = policy.ValueDisplayMode switch
+            {
+                ModOrbValueDisplayMode.Hidden => (false, false),
+                ModOrbValueDisplayMode.Contextual => (!isEvoking, isEvoking),
+                ModOrbValueDisplayMode.SinglePassive => (true, false),
+                ModOrbValueDisplayMode.SingleEvoke => (false, true),
+                ModOrbValueDisplayMode.Both => (true, true),
+                _ => (passiveLabel.Visible, evokeLabel.Visible),
+            };
+
+            passiveLabel.Visible = showPassive;
+            evokeLabel.Visible = showEvoke;
+            if (showPassive)
+                passiveLabel.SetTextAutoSize(policy.PassiveValueDisplayText);
+            if (showEvoke)
+                evokeLabel.SetTextAutoSize(policy.EvokeValueDisplayText);
+        }
+    }
+
+    /// <summary>
+    ///     Applies <see cref="IModOrbValueDisplayPolicy" /> after vanilla orb visual refresh.
+    ///     在原版充能球视觉刷新之后应用 <see cref="IModOrbValueDisplayPolicy" />。
+    /// </summary>
+    public sealed class NOrbValueDisplayPolicyPatch : IPatchMethod
+    {
+        /// <inheritdoc />
+        public static string PatchId => "norb_value_display_policy";
+
+        /// <inheritdoc />
+        public static bool IsCritical => false;
+
+        /// <inheritdoc />
+        public static string Description => "Allow mod orbs to control passive/evoke value labels";
+
+        /// <inheritdoc />
+        public static ModPatchTarget[] GetTargets()
+        {
+            return [new(typeof(NOrb), nameof(NOrb.UpdateVisuals), [typeof(bool)])];
+        }
+
+        /// <summary>
+        ///     Reconciles labels with the mod orb's requested display mode.
+        ///     按 mod 充能球请求的显示模式同步标签。
+        /// </summary>
+        [HarmonyAfter(Const.BaseLibHarmonyId)]
+        [HarmonyPriority(Priority.Last)]
+        // ReSharper disable once InconsistentNaming
+        public static void Postfix(NOrb __instance, bool isEvoking)
+        {
+            ModOrbValueDisplayPolicyRuntime.Apply(__instance, isEvoking);
+        }
+    }
+}
