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

Author: BAKAOLC

STS2-RitsuLib.csproj

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

mod_manifest.json

@@ -4,7 +4,7 @@
   "name": "RitsuLib",
   "author": "OLC",
   "description": "A shared Slay the Spire 2 mod framework library providing reusable patching, persistence, lifecycle, localization, and utility APIs for other mods.",
-  "version": "0.4.53",
+  "version": "0.4.54",
   "has_pck": false,
   "has_dll": true,
   "affects_gameplay": false,

src/Combat/HandSize/MaxHandSizePatchInstaller.cs

@@ -74,19 +74,21 @@ internal static void EnsurePatched()
                 TryAddAsyncMoveNextPatch(builder, AccessTools.Method(typeof(CardPileCmd), nameof(CardPileCmd.Draw),
                         [typeof(PlayerChoiceContext), typeof(decimal), typeof(Player), typeof(bool)]),
                     transpilerStateMachine, "Patch CardPileCmd.Draw state machine max-hand-size constants");
-                TryAddAsyncMoveNextPatch(builder, AccessTools.Method(typeof(CardPileCmd), nameof(CardPileCmd.Add),
-                    [
-                        typeof(IEnumerable<CardModel>), typeof(CardPile), typeof(CardPilePosition),
-                        typeof(AbstractModel), typeof(bool),
-                    ]),
+                TryAddAsyncMoveNextPatch(builder, ResolveCardPileCmdAddMethod(),
                     transpilerStateMachine, "Patch CardPileCmd.Add state machine max-hand-size constants");
 
                 TryAddAsyncMoveNextPatch(builder, AccessTools.Method(typeof(Scrawl), "OnPlay",
                         [typeof(PlayerChoiceContext), typeof(CardPlay)]),
                     cardOnPlayTranspiler, "Patch Scrawl.OnPlay hand-size constant");
+                TryAddAsyncMoveNextPatch(builder, AccessTools.Method(typeof(Anointed), "OnPlay",
+                        [typeof(PlayerChoiceContext), typeof(CardPlay)]),
+                    cardOnPlayTranspiler, "Patch Anointed.OnPlay hand-size constant");
                 TryAddAsyncMoveNextPatch(builder, AccessTools.Method(typeof(Dredge), "OnPlay",
                         [typeof(PlayerChoiceContext), typeof(CardPlay)]),
                     cardOnPlayTranspiler, "Patch Dredge.OnPlay hand-size constant");
+                TryAddAsyncMoveNextPatch(builder, AccessTools.Method(typeof(NeowsFury), "OnPlay",
+                        [typeof(PlayerChoiceContext), typeof(CardPlay)]),
+                    cardOnPlayTranspiler, "Patch NeowsFury.OnPlay hand-size constant");
                 TryAddAsyncMoveNextPatch(builder, AccessTools.Method(typeof(CrashLanding), "OnPlay",
                         [typeof(PlayerChoiceContext), typeof(CardPlay)]),
                     cardOnPlayTranspiler, "Patch CrashLanding.OnPlay hand-size constant");
@@ -131,6 +133,20 @@ internal static void EnsurePatched()
             }
         }
 
+        private static MethodInfo? ResolveCardPileCmdAddMethod()
+        {
+            return AccessTools.Method(typeof(CardPileCmd), nameof(CardPileCmd.Add),
+                   [
+                       typeof(IEnumerable<CardModel>), typeof(CardPile), typeof(CardPilePosition),
+                       typeof(AbstractModel), typeof(bool), typeof(bool),
+                   ])
+                   ?? AccessTools.Method(typeof(CardPileCmd), nameof(CardPileCmd.Add),
+                   [
+                       typeof(IEnumerable<CardModel>), typeof(CardPile), typeof(CardPilePosition),
+                       typeof(AbstractModel), typeof(bool),
+                   ]);
+        }
+
         private static HarmonyMethod FromMethodAfterBaseLib(string methodName)
         {
             var method = DynamicPatchBuilder.FromMethod(typeof(MaxHandSizePatchInstaller), methodName);

src/Const.cs

@@ -22,7 +22,7 @@ public static class Const
         ///     Assembly / manifest version string.
         ///     程序集/清单版本字符串。
         /// </summary>
-        public const string Version = "0.4.53";
+        public const string Version = "0.4.54";
 
         /// <summary>
         ///     Steam Workshop item id for the official RitsuLib release.

src/Patching/Builders/DynamicPatchBuilder.cs

@@ -200,6 +200,83 @@ public DynamicPatchBuilder AddMethod(
                 patchId);
         }
 
+        /// <summary>
+        ///     Attempts to resolve and append a method patch. Returns false when the target type is null or the target method
+        ///     is missing, instead of throwing. Use this for optional compatibility patches against another mod or a
+        ///     version-varying game API.
+        ///     尝试解析并追加方法 patch。目标类型为 null 或目标方法缺失时返回 false，而不是抛出异常。
+        ///     适用于针对其他 mod 或跨版本游戏 API 的可选兼容 patch。
+        /// </summary>
+        public bool TryAddMethod(
+            Type? targetType,
+            string methodName,
+            Type[]? parameterTypes = null,
+            HarmonyMethod? prefix = null,
+            HarmonyMethod? postfix = null,
+            HarmonyMethod? transpiler = null,
+            HarmonyMethod? finalizer = null,
+            bool isCritical = false,
+            string? description = null,
+            string? patchId = null,
+            MethodType harmonyMethodType = MethodType.Normal)
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(methodName);
+
+            if (targetType == null)
+                return false;
+
+            var method = PatchTargetMethodResolver.Resolve(targetType, methodName, parameterTypes, harmonyMethodType);
+            if (method == null)
+                return false;
+
+            Add(
+                method,
+                prefix,
+                postfix,
+                transpiler,
+                finalizer,
+                isCritical,
+                description ?? $"Patch method {targetType.Name}.{methodName}",
+                patchId);
+            return true;
+        }
+
+        /// <summary>
+        ///     Attempts to resolve <paramref name="targetTypeName" /> with Harmony <see cref="AccessTools.TypeByName" /> and
+        ///     append a method patch. Returns false when the type or method is absent. This keeps optional inter-mod patches
+        ///     from needing their own reflection boilerplate.
+        ///     使用 Harmony <see cref="AccessTools.TypeByName" /> 尝试解析 <paramref name="targetTypeName" /> 并追加方法
+        ///     patch。类型或方法不存在时返回 false，用于减少可选跨 mod patch 的反射样板代码。
+        /// </summary>
+        public bool TryAddMethodByName(
+            string targetTypeName,
+            string methodName,
+            Type[]? parameterTypes = null,
+            HarmonyMethod? prefix = null,
+            HarmonyMethod? postfix = null,
+            HarmonyMethod? transpiler = null,
+            HarmonyMethod? finalizer = null,
+            bool isCritical = false,
+            string? description = null,
+            string? patchId = null,
+            MethodType harmonyMethodType = MethodType.Normal)
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(targetTypeName);
+
+            return TryAddMethod(
+                AccessTools.TypeByName(targetTypeName),
+                methodName,
+                parameterTypes,
+                prefix,
+                postfix,
+                transpiler,
+                finalizer,
+                isCritical,
+                description,
+                patchId,
+                harmonyMethodType);
+        }
+
         /// <summary>
         ///     Wraps a static patch method on <paramref name="patchType" /> as a <see cref="HarmonyMethod" />.
         ///     将 <paramref name="patchType" /> 上的静态 patch 方法包装为 <see cref="HarmonyMethod" />。

src/Patching/Core/ModPatcher.cs

@@ -289,6 +289,96 @@ public void ApplyLateStaticPatches(ReadOnlySpan<ModPatchInfo> patches)
             }
         }
 
+        /// <summary>
+        ///     Removes Harmony patches owned by another Harmony id from a resolved target method. This is intended for narrow
+        ///     compatibility fixes where a dependency's patch is unsafe on the current game version and the caller replaces it
+        ///     with a safe patch through this patcher.
+        ///     从已解析的目标方法上移除另一个 Harmony id 拥有的 Harmony patch。用于依赖 mod 的 patch 在当前游戏版本
+        ///     不安全、调用方需要用本 patcher 的安全 patch 替换它的窄范围兼容修复。
+        /// </summary>
+        /// <param name="originalMethod">
+        ///     Original method whose patch list should be inspected.
+        ///     要检查 patch 列表的原始方法。
+        /// </param>
+        /// <param name="owner">
+        ///     Harmony owner id to remove.
+        ///     要移除的 Harmony owner id。
+        /// </param>
+        /// <param name="patchDeclaringType">
+        ///     Optional declaring type filter for the patch method.
+        ///     可选的 patch 方法声明类型过滤器。
+        /// </param>
+        /// <param name="patchMethodName">
+        ///     Optional patch method name filter.
+        ///     可选的 patch 方法名过滤器。
+        /// </param>
+        /// <param name="patchType">
+        ///     Harmony patch kind to inspect; <see cref="HarmonyPatchType.All" /> checks every kind.
+        ///     要检查的 Harmony patch 类型；<see cref="HarmonyPatchType.All" /> 会检查所有类型。
+        /// </param>
+        /// <returns>
+        ///     Number of patch methods removed.
+        ///     已移除的 patch 方法数量。
+        /// </returns>
+        public int UnpatchExternalPatches(
+            MethodBase originalMethod,
+            string owner,
+            Type? patchDeclaringType = null,
+            string? patchMethodName = null,
+            HarmonyPatchType patchType = HarmonyPatchType.All)
+        {
+            ArgumentNullException.ThrowIfNull(originalMethod);
+            ArgumentException.ThrowIfNullOrWhiteSpace(owner);
+
+            var patchInfo = Harmony.GetPatchInfo(originalMethod);
+            if (patchInfo == null)
+            {
+                logger.Info($"{_logPrefix}No Harmony patches found on {FormatMethod(originalMethod)}");
+                return 0;
+            }
+
+            var patches = EnumeratePatches(patchInfo, patchType)
+                .Where(patch => MatchesPatch(patch, owner, patchDeclaringType, patchMethodName))
+                .ToArray();
+
+            foreach (var patch in patches) _harmony.Unpatch(originalMethod, patch.PatchMethod);
+
+            logger.Info(
+                $"{_logPrefix}Removed {patches.Length} external patch(es) from {FormatMethod(originalMethod)} owned by '{owner}'");
+            return patches.Length;
+        }
+
+        /// <summary>
+        ///     Resolves <paramref name="target" /> and removes matching external Harmony patches. Missing targets can be
+        ///     ignored for optional compatibility paths.
+        ///     解析 <paramref name="target" /> 并移除匹配的外部 Harmony patch。可选兼容路径可以忽略缺失目标。
+        /// </summary>
+        public int UnpatchExternalPatches(
+            ModPatchTarget target,
+            string owner,
+            Type? patchDeclaringType = null,
+            string? patchMethodName = null,
+            HarmonyPatchType patchType = HarmonyPatchType.All,
+            bool ignoreIfTargetMissing = true)
+        {
+            ArgumentNullException.ThrowIfNull(target);
+
+            var originalMethod = PatchTargetMethodResolver.Resolve(target);
+            if (originalMethod != null)
+                return UnpatchExternalPatches(
+                    originalMethod,
+                    owner,
+                    patchDeclaringType,
+                    patchMethodName,
+                    patchType);
+
+            var message = $"{_logPrefix}External unpatch target not found: {target}";
+            if (!ignoreIfTargetMissing && !target.IgnoreIfMissing)
+                throw new MissingMethodException(target.TargetType.FullName, target.MethodName);
+            logger.Info(message);
+            return 0;
+        }
+
         /// <summary>
         ///     Removes all applied patches tracked by this instance from the underlying Harmony id.
         ///     从底层 Harmony id 移除此实例跟踪的所有已应用补丁。
@@ -498,6 +588,46 @@ private bool ProcessPatchResults(ReadOnlySpan<ModPatchResult> results)
             );
         }
 
+        private static IEnumerable<Patch> EnumeratePatches(Patches patchInfo, HarmonyPatchType patchType)
+        {
+            if (patchType is HarmonyPatchType.All or HarmonyPatchType.Prefix)
+                foreach (var patch in patchInfo.Prefixes)
+                    yield return patch;
+
+            if (patchType is HarmonyPatchType.All or HarmonyPatchType.Postfix)
+                foreach (var patch in patchInfo.Postfixes)
+                    yield return patch;
+
+            if (patchType is HarmonyPatchType.All or HarmonyPatchType.Transpiler)
+                foreach (var patch in patchInfo.Transpilers)
+                    yield return patch;
+
+            // ReSharper disable once InvertIf
+            if (patchType is HarmonyPatchType.All or HarmonyPatchType.Finalizer)
+                foreach (var patch in patchInfo.Finalizers)
+                    yield return patch;
+        }
+
+        private static bool MatchesPatch(
+            Patch patch,
+            string owner,
+            Type? patchDeclaringType,
+            string? patchMethodName)
+        {
+            if (patch.owner != owner)
+                return false;
+
+            if (patchDeclaringType != null && patch.PatchMethod.DeclaringType != patchDeclaringType)
+                return false;
+
+            return string.IsNullOrEmpty(patchMethodName) || patch.PatchMethod.Name == patchMethodName;
+        }
+
+        private static string FormatMethod(MethodBase method)
+        {
+            return $"{method.DeclaringType?.FullName}.{method.Name}";
+        }
+
         /// <summary>
         ///     Validate that patch type implements IPatchMethod interface (optional but recommended)
         ///     验证 patch 类型是否实现 IPatchMethod 接口（可选但推荐）

src/Scaffolding/Godot/NodeFactories/RitsuNEnergyCounterNodeFactory.cs

@@ -68,11 +68,11 @@ protected override void GenerateNode(NEnergyCounter target, IRitsuGodotNodeSlot
                     target.AddChild(CreateDefaultLabel());
                     break;
                 case "%RotationLayers":
-                    {
-                        var control = CreateFullRectControl(null);
-                        target.AddUniqueChild(control, "RotationLayers");
-                        break;
-                    }
+                {
+                    var control = CreateFullRectControl(null);
+                    target.AddUniqueChild(control, "RotationLayers");
+                    break;
+                }
                 case "%EnergyVfxBack":
                     target.AddUniqueChild(CreateParticlesContainer(null, "EnergyVfxBack"));
                     break;
@@ -131,18 +131,18 @@ private static NParticlesContainer CreateParticlesContainer(Node? source, String
             if (source is CanvasItem sourceCanvas)
                 CopyCanvasItemProperties(container, sourceCanvas);
 
-            if (source is GpuParticles2D singleParticle)
+            switch (source)
             {
-                container.AddChild(singleParticle);
-                singleParticle.Owner = container;
-                return container;
+                case GpuParticles2D singleParticle:
+                    container.AddChild(singleParticle);
+                    singleParticle.Owner = container;
+                    return container;
+                case null:
+                    return container;
             }
 
-            if (source != null)
-            {
-                source.GetParent()?.RemoveChild(source);
-                container.AddChild(source);
-            }
+            source.GetParent()?.RemoveChild(source);
+            container.AddChild(source);
 
             return container;
         }