feat(card piles): add FlightStartPositionResolver for dynamic shuffle fly visuals

- Introduced `FlightStartPositionResolver` to `ModCardPileDefinition`, enabling mods to specify dynamic start positions for shuffle-style fly visuals.
- Added `ModCardPileFlightStartContext` to encapsulate context for the resolver, including source and target piles.
- Updated relevant methods in `ModCardPileLayout` and `ModCardPileSpec` to support the new functionality, enhancing flexibility in visual animations.
- Registered a new patch, `ModCardPileShuffleVfxStartPositionPatch`, to override start positions for shuffle fly visuals based on the resolver.

Author: BAKAOLC

CardPiles/ModCardPileDefinition.cs

@@ -44,6 +44,9 @@ public sealed record ModCardPileDefinition
         /// <param name="flightTargetPositionResolver">
         ///     Optional dynamic fly-in target resolver (see <see cref="FlightTargetPositionResolver" />).
         /// </param>
+        /// <param name="flightStartPositionResolver">
+        ///     Optional dynamic fly-out source/start resolver (see <see cref="FlightStartPositionResolver" />).
+        /// </param>
         public ModCardPileDefinition(
             string modId,
             string id,
@@ -58,7 +61,8 @@ public ModCardPileDefinition(
             Vector2 hoverTipScreenOffset,
             ModCardPileHoverTipPlacement hoverTipPlacement,
             Func<ModCardPileVisibilityContext, bool>? visibleWhen,
-            Func<ModCardPileFlightTargetContext, Vector2?>? flightTargetPositionResolver)
+            Func<ModCardPileFlightTargetContext, Vector2?>? flightTargetPositionResolver,
+            Func<ModCardPileFlightStartContext, Vector2?>? flightStartPositionResolver)
         {
             ModId = modId;
             Id = id;
@@ -74,6 +78,7 @@ public ModCardPileDefinition(
             HoverTipPlacement = hoverTipPlacement;
             VisibleWhen = visibleWhen;
             FlightTargetPositionResolver = flightTargetPositionResolver;
+            FlightStartPositionResolver = flightStartPositionResolver;
         }
 
         /// <summary>
@@ -94,7 +99,30 @@ public ModCardPileDefinition(
             ModCardPileHoverTipPlacement hoverTipPlacement,
             Func<ModCardPileVisibilityContext, bool>? visibleWhen)
             : this(modId, id, pileType, scope, style, anchor, iconPath, hotkeys, cardShouldBeVisible, onOpen,
-                hoverTipScreenOffset, hoverTipPlacement, visibleWhen, null)
+                hoverTipScreenOffset, hoverTipPlacement, visibleWhen, null, null)
+        {
+        }
+
+        /// <summary>
+        ///     Compatibility overload that omitted <see cref="FlightStartPositionResolver" />; forwards with null.
+        /// </summary>
+        public ModCardPileDefinition(
+            string modId,
+            string id,
+            PileType pileType,
+            ModCardPileScope scope,
+            ModCardPileUiStyle style,
+            ModCardPileAnchor anchor,
+            string? iconPath,
+            string[]? hotkeys,
+            bool cardShouldBeVisible,
+            Action<ModCardPileOpenContext>? onOpen,
+            Vector2 hoverTipScreenOffset,
+            ModCardPileHoverTipPlacement hoverTipPlacement,
+            Func<ModCardPileVisibilityContext, bool>? visibleWhen,
+            Func<ModCardPileFlightTargetContext, Vector2?>? flightTargetPositionResolver)
+            : this(modId, id, pileType, scope, style, anchor, iconPath, hotkeys, cardShouldBeVisible, onOpen,
+                hoverTipScreenOffset, hoverTipPlacement, visibleWhen, flightTargetPositionResolver, null)
         {
         }
 
@@ -115,7 +143,7 @@ public ModCardPileDefinition(
             Vector2 hoverTipScreenOffset,
             ModCardPileHoverTipPlacement hoverTipPlacement)
             : this(modId, id, pileType, scope, style, anchor, iconPath, hotkeys, cardShouldBeVisible, onOpen,
-                hoverTipScreenOffset, hoverTipPlacement, null, null)
+                hoverTipScreenOffset, hoverTipPlacement, null, null, null)
         {
         }
 
@@ -272,5 +300,10 @@ public ModCardPileDefinition(
         ///     Optional resolver invoked for each fly-in targeting request to this pile.
         /// </summary>
         public Func<ModCardPileFlightTargetContext, Vector2?>? FlightTargetPositionResolver { get; }
+
+        /// <summary>
+        ///     Optional resolver invoked when a shuffle-style fly visual starts from this pile.
+        /// </summary>
+        public Func<ModCardPileFlightStartContext, Vector2?>? FlightStartPositionResolver { get; }
     }
 }

CardPiles/ModCardPileFlightStartContext.cs

@@ -0,0 +1,36 @@
+using Godot;
+using MegaCrit.Sts2.Core.Entities.Cards;
+
+namespace STS2RitsuLib.CardPiles
+{
+    /// <summary>
+    ///     Context passed to <see cref="ModCardPileSpec.FlightStartPositionResolver" /> when shuffle-style fly
+    ///     visuals need a source/start position for a mod pile.
+    /// </summary>
+    public sealed class ModCardPileFlightStartContext
+    {
+        internal ModCardPileFlightStartContext(
+            ModCardPileDefinition definition,
+            CardPile startPile,
+            CardPile targetPile,
+            Vector2 defaultStartPosition)
+        {
+            Definition = definition;
+            StartPile = startPile;
+            TargetPile = targetPile;
+            DefaultStartPosition = defaultStartPosition;
+        }
+
+        /// <summary>Definition of the source pile.</summary>
+        public ModCardPileDefinition Definition { get; }
+
+        /// <summary>Source pile for this shuffle fly visual.</summary>
+        public CardPile StartPile { get; }
+
+        /// <summary>Destination pile for this shuffle fly visual.</summary>
+        public CardPile TargetPile { get; }
+
+        /// <summary>Ritsulib's default start position for this request.</summary>
+        public Vector2 DefaultStartPosition { get; }
+    }
+}

CardPiles/ModCardPileLayout.cs

@@ -1,5 +1,6 @@
 using Godot;
 using MegaCrit.Sts2.Core.Combat;
+using MegaCrit.Sts2.Core.Entities.Cards;
 using MegaCrit.Sts2.Core.Nodes;
 using MegaCrit.Sts2.Core.Nodes.Cards;
 using MegaCrit.Sts2.Core.Nodes.Rooms;
@@ -32,6 +33,20 @@ public static Vector2 GetTargetPosition(ModCardPileDefinition definition, NCard?
             return resolver(context) ?? defaultPosition;
         }
 
+        public static Vector2 GetShuffleStartPosition(
+            ModCardPileDefinition definition,
+            CardPile startPile,
+            CardPile targetPile)
+        {
+            var defaultPosition = GetDefaultTargetPosition(definition, null);
+            var resolver = definition.FlightStartPositionResolver;
+            if (resolver == null)
+                return defaultPosition;
+
+            var context = new ModCardPileFlightStartContext(definition, startPile, targetPile, defaultPosition);
+            return resolver(context) ?? defaultPosition;
+        }
+
         private static Vector2 GetDefaultTargetPosition(ModCardPileDefinition definition, NCard? node)
         {
             var fallback = FallbackPosition();

CardPiles/ModCardPileRegistry.cs

@@ -237,7 +237,8 @@ private ModCardPileDefinition RegisterCore(string id, ModCardPileSpec spec)
                 spec.HoverTipScreenOffset,
                 spec.HoverTipPlacement,
                 spec.VisibleWhen,
-                spec.FlightTargetPositionResolver);
+                spec.FlightTargetPositionResolver,
+                spec.FlightStartPositionResolver);
 
             lock (SyncRoot)
             {

CardPiles/ModCardPileSpec.cs

@@ -108,5 +108,11 @@ public ModCardPileSpec()
         ///     target position for the tail/trail endpoint. Return null to use the default layout position.
         /// </summary>
         public Func<ModCardPileFlightTargetContext, Vector2?>? FlightTargetPositionResolver { get; init; }
+
+        /// <summary>
+        ///     Optional resolver called when a shuffle-style fly visual starts from this pile, allowing mods to
+        ///     provide a dynamic source/start position. Return null to use the default layout position.
+        /// </summary>
+        public Func<ModCardPileFlightStartContext, Vector2?>? FlightStartPositionResolver { get; init; }
     }
 }

CardPiles/Patches/ModCardPileShuffleVfxStartPositionPatch.cs

@@ -0,0 +1,51 @@
+using System.Reflection;
+using HarmonyLib;
+using MegaCrit.Sts2.Core.Entities.Cards;
+using MegaCrit.Sts2.Core.Nodes.Vfx;
+using STS2RitsuLib.Patching.Models;
+
+namespace STS2RitsuLib.CardPiles.Patches
+{
+    /// <summary>
+    ///     Overrides the source/start position for shuffle fly visuals when the source pile is a mod pile and
+    ///     that pile registered a <see cref="ModCardPileSpec.FlightStartPositionResolver" />.
+    /// </summary>
+    public sealed class ModCardPileShuffleVfxStartPositionPatch : IPatchMethod
+    {
+        private static readonly FieldInfo? StartPositionField =
+            AccessTools.Field(typeof(NCardFlyShuffleVfx), "_startPos");
+
+        /// <inheritdoc />
+        public static string PatchId => "ritsulib_mod_pile_shuffle_vfx_start_position";
+
+        /// <inheritdoc />
+        public static string Description =>
+            "Allow mod card piles to customize shuffle-fly source positions";
+
+        /// <inheritdoc />
+        public static bool IsCritical => false;
+
+        /// <inheritdoc />
+        public static ModPatchTarget[] GetTargets()
+        {
+            return [new(typeof(NCardFlyShuffleVfx), nameof(NCardFlyShuffleVfx.Create))];
+        }
+
+        // ReSharper disable InconsistentNaming
+        /// <summary>
+        ///     Rewrites the freshly created shuffle-vfx start position when <paramref name="startPile" /> is a
+        ///     mod pile and it provided a custom start resolver.
+        /// </summary>
+        public static void Postfix(CardPile startPile, CardPile targetPile, ref NCardFlyShuffleVfx? __result)
+        {
+            if (__result == null || StartPositionField == null)
+                return;
+            if (!ModCardPileRegistry.TryGetByPileType(startPile.Type, out var definition))
+                return;
+
+            var resolved = ModCardPileLayout.GetShuffleStartPosition(definition, startPile, targetPile);
+            StartPositionField.SetValue(__result, resolved);
+        }
+        // ReSharper restore InconsistentNaming
+    }
+}

RitsuLibFramework.PatcherSetup.cs

@@ -145,6 +145,7 @@ private static void RegisterLifecyclePatches()
             patcher.RegisterPatch<ModCardPileGetPatch>();
             patcher.RegisterPatch<ModCardPileIsCombatPatch>();
             patcher.RegisterPatch<ModCardPileGetTargetPositionPatch>();
+            patcher.RegisterPatch<ModCardPileShuffleVfxStartPositionPatch>();
             patcher.RegisterPatch<ModCardPileAllPilesPatch>();
             patcher.RegisterPatch<ModCardPileFindOnTablePatch>();
             patcher.RegisterPatch<ModCardPileCombatPilesContainerReadyPatch>();