feat(compatibility): update API version handling and introduce new lifecycle events

- Enhanced compatibility definitions to support API versions 0.103.2, 0.104.0, and 0.105.0.
- Updated GetCompatBranchLabel method to return appropriate labels based on the API version.
- Introduced new lifecycle events: BeforeFlushEvent and CardsFlushedEvent, replacing the legacy CardRetainedEvent for API 0.105.0 and newer.
- Refactored various classes to utilize the new IsInfiniteHpDisplayed method for checking infinite HP display status.
- Improved documentation to reflect changes in lifecycle events and compatibility handling.

Author: BAKAOLC

Audio/Sts2SfxAlignedFmod.cs

@@ -40,15 +40,21 @@ public static void PlayOneShot(string eventPath, IReadOnlyDictionary<string, flo
         }
 
         /// <summary>
-        ///     Starts a guarded loop via <see cref="SfxCmd.PlayLoop" />.
+        ///     Starts a guarded loop via <see>
+        ///         <cref>SfxCmd.PlayLoop</cref>
+        ///     </see>
+        ///     .
         /// </summary>
         public static void PlayLoop(string eventPath, bool usesLoopParam = true)
         {
             SfxCmd.PlayLoop(eventPath, usesLoopParam);
         }
 
         /// <summary>
-        ///     Stops a loop via <see cref="SfxCmd.StopLoop" />.
+        ///     Stops a loop via <see>
+        ///         <cref>SfxCmd.StopLoop</cref>
+        ///     </see>
+        ///     .
         /// </summary>
         public static void StopLoop(string eventPath)
         {

Cards/FreePlay/FreePlayBindingRegistry.cs

@@ -1,4 +1,4 @@
-#if STS2_V_0_103_2
+#if !STS2_AT_LEAST_0_104_0
 using CombatStateLike = MegaCrit.Sts2.Core.Combat.CombatState;
 #else
 using CombatStateLike = MegaCrit.Sts2.Core.Combat.ICombatState;

Combat/CardTargeting/CardPlayUiFocus.cs

@@ -1,4 +1,4 @@
-#if STS2_V_0_103_2
+#if !STS2_AT_LEAST_0_104_0
 using MegaCrit.Sts2.Core.Nodes.GodotExtensions;
 using MegaCrit.Sts2.Core.Nodes.Rooms;
 #else
@@ -11,10 +11,9 @@ internal static class CardPlayUiFocus
     {
         internal static void AfterCardPlayFinished()
         {
-#if STS2_V_0_103_2
+#if !STS2_AT_LEAST_0_104_0
             NCombatRoom.Instance?.Ui.Hand.DefaultFocusedControl.TryGrabFocus();
 #else
-            // 0.104.0+: NCardPlay now restores focus via screen context instead of directly focusing the hand.
             ActiveScreenContext.Instance.FocusOnDefaultControl();
 #endif
         }

Combat/HandSize/MaxHandSizePatchInstaller.cs

@@ -38,7 +38,7 @@ internal static class MaxHandSizePatchInstaller
             ?? throw new MissingMethodException(typeof(MaxHandSizeCalculator).FullName,
                 nameof(MaxHandSizeCalculator.CalculateFromCardOwner));
 
-#if !STS2_V_0_103_2
+#if STS2_AT_LEAST_0_104_0
         private static readonly MethodInfo MaxCardsInHandGetter =
             AccessTools.PropertyGetter(typeof(CardPile), nameof(CardPile.MaxCardsInHand))
             ?? throw new MissingMethodException(typeof(CardPile).FullName, nameof(CardPile.MaxCardsInHand));
@@ -117,11 +117,14 @@ internal static void EnsurePatched()
                 }
 
                 _patched = true;
-#if STS2_V_0_103_2
+#if !STS2_AT_LEAST_0_104_0
                 RitsuLibFramework.Logger.Info("[MaxHandSize] RitsuLib hand-size patch set installed (compat 0.103.2 profile).");
+#elif !STS2_AT_LEAST_0_105_0
+                RitsuLibFramework.Logger.Info(
+                    "[MaxHandSize] RitsuLib hand-size patch set installed (compat 0.104.0 profile).");
 #else
                 RitsuLibFramework.Logger.Info(
-                    "[MaxHandSize] RitsuLib hand-size patch set installed (0.104.0 profile).");
+                    "[MaxHandSize] RitsuLib hand-size patch set installed (0.105.0 profile).");
 #endif
             }
         }
@@ -192,14 +195,10 @@ private static void TryAddAsyncMoveNextPatch(
 
         private static bool IsMaxHandSizeToken(CodeInstruction ins)
         {
-#if STS2_V_0_103_2
-            // 0.103.2 compatibility signatures keep most hand-limit checks as hard-coded constants.
-            // Match literal 10 only.
+#if !STS2_AT_LEAST_0_104_0
             return (ins.opcode == OpCodes.Ldc_I4_S && ins.operand is sbyte and DefaultMaxHandSize)
                    || (ins.opcode == OpCodes.Ldc_I4 && ins.operand is DefaultMaxHandSize);
 #else
-            // 0.104.0 switched many call sites to CardPile.MaxCardsInHand.
-            // Match both legacy literal 10 and property getter invocations.
             var isDefaultConst =
                 (ins.opcode == OpCodes.Ldc_I4_S && ins.operand is sbyte and DefaultMaxHandSize)
                 || (ins.opcode == OpCodes.Ldc_I4 && ins.operand is DefaultMaxHandSize);

Combat/HealthBars/IHealthBarForecastSource.cs

@@ -1,4 +1,4 @@
-#if STS2_V_0_103_2
+#if !STS2_AT_LEAST_0_104_0
 using CombatStateLike = MegaCrit.Sts2.Core.Combat.CombatState;
 #else
 using CombatStateLike = MegaCrit.Sts2.Core.Combat.ICombatState;

Combat/HealthBars/Patches/NHealthBarForecastPatches.cs

@@ -32,7 +32,7 @@ public static void RefreshForegroundOverlay(NHealthBar healthBar)
                 return;
 
             var creature = healthBar._creature;
-            if (creature.CurrentHp <= 0 || creature.ShowsInfiniteHp)
+            if (creature.CurrentHp <= 0 || creature.IsInfiniteHpDisplayed())
             {
                 HideAllCustomSegments(healthBar);
                 return;
@@ -193,7 +193,7 @@ public static void RefreshMiddlegroundOverlay(NHealthBar healthBar)
                 return;
 
             var creature = healthBar._creature;
-            if (creature.CurrentHp <= 0 || creature.ShowsInfiniteHp)
+            if (creature.CurrentHp <= 0 || creature.IsInfiniteHpDisplayed())
                 return;
 
             var hpMiddleground = healthBar._hpMiddleground;
@@ -220,7 +220,7 @@ public static void RefreshTextOverlay(NHealthBar healthBar)
                 return;
 
             var creature = healthBar._creature;
-            if (creature.CurrentHp <= 0 || creature.ShowsInfiniteHp)
+            if (creature.CurrentHp <= 0 || creature.IsInfiniteHpDisplayed())
                 return;
 
             var lethalColor = state.LastRender.LethalRightColor ?? state.LastRender.LethalLeftColor;

Combat/HealthBars/Patches/NHealthBarVisualGraftPatch.cs

@@ -19,7 +19,7 @@ public static void RefreshGraftOverlay(NHealthBar healthBar)
                 return;
 
             var creature = healthBar._creature;
-            if (creature.CurrentHp <= 0 || creature.ShowsInfiniteHp)
+            if (creature.CurrentHp <= 0 || creature.IsInfiniteHpDisplayed())
             {
                 ResetGraft(healthBar);
                 return;
@@ -60,7 +60,7 @@ public static void AfterForecastTouchup(NHealthBar healthBar)
                 return;
 
             var creature = healthBar._creature;
-            if (creature.CurrentHp <= 0 || creature.ShowsInfiniteHp)
+            if (creature.CurrentHp <= 0 || creature.IsInfiniteHpDisplayed())
                 return;
 
             var metrics = HealthBarVisualGraftRegistry.Aggregate(creature);

Combat/Powers/ModTemporaryPowerTemplate.cs

@@ -69,7 +69,12 @@ public abstract class ModTemporaryPowerTemplate : ModPowerTemplate, ITemporaryPo
         public override bool AllowNegative => true;
 
         /// <inheritdoc />
+#if !STS2_AT_LEAST_0_105_0
         public override bool IsInstanced => LastForXExtraTurns != 0;
+#else
+        public override PowerInstanceType InstanceType =>
+            LastForXExtraTurns != 0 ? PowerInstanceType.Instanced : PowerInstanceType.None;
+#endif
 
         /// <summary>
         ///     Remaining extra expiry cycles before removal.
@@ -136,7 +141,7 @@ await ApplyInternalPower(new ThrowingPlayerChoiceContext(), target, SignedAmount
         }
 
         /// <inheritdoc />
-#if STS2_V_0_103_2
+#if !STS2_AT_LEAST_0_104_0
         public override async Task AfterPowerAmountChanged(PowerModel power, decimal amount, Creature? applier,
             CardModel? cardSource)
 #else
@@ -154,7 +159,7 @@ public override async Task AfterPowerAmountChanged(PlayerChoiceContext choiceCon
                 return;
             }
 
-#if STS2_V_0_103_2
+#if !STS2_AT_LEAST_0_104_0
             await ApplyInternalPower(new ThrowingPlayerChoiceContext(), Owner, SignedAmount(amount), applier,
                 cardSource, true);
 #else
@@ -252,7 +257,7 @@ private static Task ApplyInternalPowerGeneric<TPower>(PlayerChoiceContext choice
             decimal amount,
             Creature? applier, CardModel? cardSource, bool silent) where TPower : PowerModel
         {
-#if STS2_V_0_103_2
+#if !STS2_AT_LEAST_0_104_0
             return PowerCmd.Apply<TPower>(target, amount, applier, cardSource, silent);
 #else
             return PowerCmd.Apply<TPower>(choiceContext, target, amount, applier, cardSource, silent);

Combat/Ui/ExtraCornerAmountLabels/ExtraCornerAmountLabelsRuntime.cs

@@ -224,8 +224,7 @@ private static IReadOnlyList<ExtraIconAmountLabelCorner> GetReservedCorners(Extr
         {
             return hostKind switch
             {
-                ExtraCornerHostKind.Power => [ExtraIconAmountLabelCorner.BottomRight],
-                ExtraCornerHostKind.Relic => [ExtraIconAmountLabelCorner.BottomRight],
+                ExtraCornerHostKind.Power or ExtraCornerHostKind.Relic => [ExtraIconAmountLabelCorner.BottomRight],
                 ExtraCornerHostKind.Intent => [ExtraIconAmountLabelCorner.BottomLeft],
                 _ => [],
             };

Lifecycle/CombatLifecycleContracts.cs

@@ -1,11 +1,12 @@
-#if STS2_V_0_103_2
+#if !STS2_AT_LEAST_0_104_0
 using CombatStateCompat = MegaCrit.Sts2.Core.Combat.CombatState;
 #else
 using CombatStateCompat = MegaCrit.Sts2.Core.Combat.ICombatState;
 #endif
 using MegaCrit.Sts2.Core.Combat;
 using MegaCrit.Sts2.Core.Entities.Cards;
 using MegaCrit.Sts2.Core.Entities.Creatures;
+using MegaCrit.Sts2.Core.Entities.Players;
 using MegaCrit.Sts2.Core.Models;
 using MegaCrit.Sts2.Core.Rooms;
 using MegaCrit.Sts2.Core.Runs;
@@ -161,15 +162,54 @@ DateTimeOffset OccurredAtUtc
     /// <summary>
     ///     A card was retained for the next turn.
     /// </summary>
+    /// <remarks>
+    ///     On host API 0.105.0 and newer the underlying <c>Hook.AfterCardRetained</c> callback no longer exists; this event
+    ///     is replayed per retained card from <c>Hook.AfterFlush</c> for backward compatibility. Subscribe to
+    ///     <see cref="CardsFlushedEvent" /> instead to also observe the matching flushed cards and the player.
+    /// </remarks>
     /// <param name="CombatState">Active combat state.</param>
     /// <param name="Card">Retained card.</param>
     /// <param name="OccurredAtUtc">When the event was raised.</param>
+    [Obsolete(
+        "Use CardsFlushedEvent. CardRetainedEvent is replayed from Hook.AfterFlush on host API 0.105.0 and newer.")]
     public readonly record struct CardRetainedEvent(
         CombatStateCompat CombatState,
         CardModel Card,
         DateTimeOffset OccurredAtUtc
     ) : IFrameworkLifecycleEvent;
 
+    /// <summary>
+    ///     A flush sequence is about to run for the given player. Mirrors <c>Hook.BeforeFlush</c>.
+    /// </summary>
+    /// <param name="CombatState">Active combat state.</param>
+    /// <param name="Player">Player whose hand is about to be flushed.</param>
+    /// <param name="OccurredAtUtc">When the event was raised.</param>
+    public readonly record struct BeforeFlushEvent(
+        CombatStateCompat CombatState,
+        Player Player,
+        DateTimeOffset OccurredAtUtc
+    ) : IFrameworkLifecycleEvent;
+
+    /// <summary>
+    ///     Hand flush completed for the given player.
+    /// </summary>
+    /// <remarks>
+    ///     Fired from <c>Hook.AfterFlush</c> on host API 0.105.0 and newer. On older host APIs <c>Hook.AfterFlush</c> does
+    ///     not exist and this event is not raised; use the legacy <see cref="CardRetainedEvent" /> there.
+    /// </remarks>
+    /// <param name="CombatState">Active combat state.</param>
+    /// <param name="Player">Player whose hand was flushed.</param>
+    /// <param name="FlushedCards">Cards that left the hand during flush (non-retained).</param>
+    /// <param name="RetainedCards">Cards that stayed in the hand (retain semantics).</param>
+    /// <param name="OccurredAtUtc">When the event was raised.</param>
+    public readonly record struct CardsFlushedEvent(
+        CombatStateCompat CombatState,
+        Player Player,
+        IReadOnlyCollection<CardModel> FlushedCards,
+        IReadOnlyCollection<CardModel> RetainedCards,
+        DateTimeOffset OccurredAtUtc
+    ) : IFrameworkLifecycleEvent;
+
     /// <summary>
     ///     A creature is dying (HP reached zero or equivalent).
     /// </summary>