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

Author: BAKAOLC

Combat/HandSize/MaxHandSizePatchInstaller.cs

@@ -208,7 +208,7 @@ private static bool IsMaxHandSizeToken(CodeInstruction ins)
             return HarmonyIl.LoadsInt32(ins, DefaultMaxHandSize);
 #else
             return HarmonyIl.LoadsInt32(ins, DefaultMaxHandSize)
-                   || HarmonyIl.IsCallTo(ins, MaxCardsInHandGetter);
+                   || HarmonyIl.IsCall(MaxCardsInHandGetter)(ins);
 #endif
         }
 
@@ -259,7 +259,7 @@ private static IEnumerable<CodeInstruction> PlayerArg1Transpiler(IEnumerable<Cod
         private static IEnumerable<CodeInstruction> StateMachineTranspiler(IEnumerable<CodeInstruction> instructions)
         {
             var rewriter = HarmonyIlRewriter.From(instructions);
-            var loadPlayer = FindStateMachinePlayerLoad(rewriter.Code);
+            var loadPlayer = FindStateMachinePlayerLoad(rewriter);
             if (loadPlayer == null)
             {
                 RitsuLibFramework.Logger.Warn(
@@ -279,7 +279,7 @@ private static IEnumerable<CodeInstruction> StateMachineTranspiler(IEnumerable<C
         private static IEnumerable<CodeInstruction> CardOnPlayTranspiler(IEnumerable<CodeInstruction> instructions)
         {
             var rewriter = HarmonyIlRewriter.From(instructions);
-            var loadCard = FindStateMachineCardLoad(rewriter.Code);
+            var loadCard = FindStateMachineCardLoad(rewriter);
             if (loadCard == null)
             {
                 RitsuLibFramework.Logger.Warn(
@@ -296,35 +296,29 @@ private static IEnumerable<CodeInstruction> CardOnPlayTranspiler(IEnumerable<Cod
             return rewriter.InstructionsChecked("[MaxHandSize] Card OnPlay max-hand-size replacement");
         }
 
-        private static IReadOnlyList<CodeInstruction>? FindStateMachinePlayerLoad(IReadOnlyList<CodeInstruction> code)
+        private static IReadOnlyList<CodeInstruction>? FindStateMachinePlayerLoad(HarmonyIlRewriter rewriter)
         {
-            var pattern = HarmonyIlPattern.Sequence(HarmonyIl.IsLdarg(0), HarmonyIl.IsLdfld());
-            foreach (var match in pattern.FindAll(code))
-            {
-                var fieldInstruction = match.InstructionAt(code, 1);
-                if (fieldInstruction.operand is not FieldInfo field || field.FieldType != typeof(Player))
-                    continue;
-
-                return [match.InstructionAt(code, 0).Clone(), fieldInstruction.Clone()];
-            }
+            return FindStateMachineFieldLoad(rewriter, field => field.FieldType == typeof(Player),
+                "[MaxHandSize] state-machine Player field load");
+        }
 
-            return null;
+        private static IReadOnlyList<CodeInstruction>? FindStateMachineCardLoad(HarmonyIlRewriter rewriter)
+        {
+            return FindStateMachineFieldLoad(rewriter, field => typeof(CardModel).IsAssignableFrom(field.FieldType),
+                "[MaxHandSize] state-machine CardModel field load");
         }
 
-        private static IReadOnlyList<CodeInstruction>? FindStateMachineCardLoad(IReadOnlyList<CodeInstruction> code)
+        private static IReadOnlyList<CodeInstruction>? FindStateMachineFieldLoad(
+            HarmonyIlRewriter rewriter,
+            Func<FieldInfo, bool> fieldPredicate,
+            string description)
         {
             var pattern = HarmonyIlPattern.Sequence(HarmonyIl.IsLdarg(0), HarmonyIl.IsLdfld());
-            foreach (var match in pattern.FindAll(code))
-            {
-                var fieldInstruction = match.InstructionAt(code, 1);
-                if (fieldInstruction.operand is not FieldInfo field ||
-                    !typeof(CardModel).IsAssignableFrom(field.FieldType))
-                    continue;
-
-                return [match.InstructionAt(code, 0).Clone(), fieldInstruction.Clone()];
-            }
-
-            return null;
+            return (from match in rewriter.FindMatches(pattern, description).Items
+                    where fieldPredicate(match.GetFieldOperand(rewriter.Code, 1))
+                    select (IReadOnlyList<CodeInstruction>?)
+                        [match.InstructionAt(rewriter.Code, 0).Clone(), match.InstructionAt(rewriter.Code, 1).Clone()])
+                .FirstOrDefault();
         }
 
         // ReSharper disable InconsistentNaming
@@ -371,7 +365,7 @@ private static IEnumerable<CodeInstruction> StartCardPlayTranspiler(IEnumerable<
 
         private static bool ContainsCall(IReadOnlyList<CodeInstruction> code, MethodInfo method)
         {
-            return code.Any(instruction => HarmonyIl.IsCallTo(instruction, method));
+            return code.Any(HarmonyIl.IsCall(method));
         }
 
         private static void WarnIfRewriteUnsatisfied(HarmonyIlRewriteReport report)

Const.cs

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

Interactions/RightClick/IModRightClickHandler.cs

@@ -0,0 +1,21 @@
+namespace STS2RitsuLib.Interactions.RightClick
+{
+    /// <summary>
+    ///     Handles a local right-click request before the built-in model-interface handler.
+    ///     在内置模型接口 handler 之前处理本地右键请求。
+    /// </summary>
+    public interface IModRightClickHandler
+    {
+        /// <summary>
+        ///     Higher priority handlers run first.
+        ///     优先级越高越先运行。
+        /// </summary>
+        int Priority => 0;
+
+        /// <summary>
+        ///     Returns true when the request was accepted and should consume input.
+        ///     返回 true 表示请求已被接受，应消耗输入。
+        /// </summary>
+        bool TryHandle(ModRightClickContext context);
+    }
+}

Interactions/RightClick/IModRightClickableModel.cs

@@ -0,0 +1,36 @@
+namespace STS2RitsuLib.Interactions.RightClick
+{
+    /// <summary>
+    ///     Implement on a model to receive synced right-click actions through RitsuLib.
+    ///     在模型上实现此接口，即可通过 RitsuLib 接收同步右键动作。
+    /// </summary>
+    public interface IModRightClickableModel
+    {
+        /// <summary>
+        ///     Local preflight check. Returning false leaves the input unhandled.
+        ///     本地预检；返回 false 时不会消耗输入。
+        /// </summary>
+        bool CanHandleRightClickLocal(ModRightClickContext context)
+        {
+            return true;
+        }
+
+        /// <summary>
+        ///     Runs when the synced right-click action reaches the queue.
+        ///     当同步右键动作到达队列时运行。
+        /// </summary>
+        Task OnRightClick(ModRightClickExecutionContext context);
+    }
+
+    /// <inheritdoc />
+    public interface IModRightClickableCard : IModRightClickableModel;
+
+    /// <inheritdoc />
+    public interface IModRightClickableRelic : IModRightClickableModel;
+
+    /// <inheritdoc />
+    public interface IModRightClickablePower : IModRightClickableModel;
+
+    /// <inheritdoc />
+    public interface IModRightClickablePotion : IModRightClickableModel;
+}

Interactions/RightClick/ModRightClickContext.cs

@@ -0,0 +1,26 @@
+using MegaCrit.Sts2.Core.Entities.Players;
+using MegaCrit.Sts2.Core.Models;
+
+namespace STS2RitsuLib.Interactions.RightClick
+{
+    /// <summary>
+    ///     Local right-click dispatch context.
+    ///     本地右键分发上下文。
+    /// </summary>
+    /// <param name="Player">
+    ///     Local player that initiated the request.
+    ///     发起请求的本地玩家。
+    /// </param>
+    /// <param name="Model">
+    ///     Clicked model.
+    ///     被点击的模型。
+    /// </param>
+    /// <param name="Trigger">
+    ///     Input metadata.
+    ///     输入元数据。
+    /// </param>
+    public readonly record struct ModRightClickContext(
+        Player Player,
+        AbstractModel Model,
+        ModRightClickTrigger Trigger);
+}

Interactions/RightClick/ModRightClickExecutionContext.cs

@@ -0,0 +1,18 @@
+using MegaCrit.Sts2.Core.Entities.Players;
+using MegaCrit.Sts2.Core.GameActions;
+using MegaCrit.Sts2.Core.GameActions.Multiplayer;
+using MegaCrit.Sts2.Core.Models;
+
+namespace STS2RitsuLib.Interactions.RightClick
+{
+    /// <summary>
+    ///     Context passed when a synced right-click action reaches the action queue.
+    ///     当同步右键动作到达动作队列时传递的上下文。
+    /// </summary>
+    public readonly record struct ModRightClickExecutionContext(
+        Player Player,
+        AbstractModel Model,
+        ModRightClickTrigger Trigger,
+        GameActionPlayerChoiceContext? PlayerChoiceContext,
+        GenericHookGameAction? Action);
+}

Interactions/RightClick/ModRightClickModelKind.cs

@@ -0,0 +1,33 @@
+namespace STS2RitsuLib.Interactions.RightClick
+{
+    /// <summary>
+    ///     Model families supported by the built-in right-click node patches.
+    ///     内置右键节点 patch 支持的模型类别。
+    /// </summary>
+    public enum ModRightClickModelKind
+    {
+        /// <summary>
+        ///     Hand card.
+        ///     手牌。
+        /// </summary>
+        Card = 0,
+
+        /// <summary>
+        ///     Relic.
+        ///     遗物。
+        /// </summary>
+        Relic = 1,
+
+        /// <summary>
+        ///     Power.
+        ///     能力。
+        /// </summary>
+        Power = 2,
+
+        /// <summary>
+        ///     Potion.
+        ///     药水。
+        /// </summary>
+        Potion = 3,
+    }
+}