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

Author: BAKAOLC

Cards/Patches/ModKeywordCardDescriptionPatches.cs

@@ -0,0 +1,45 @@
+using MegaCrit.Sts2.Core.Entities.Cards;
+using MegaCrit.Sts2.Core.Entities.Creatures;
+using MegaCrit.Sts2.Core.Models;
+using STS2RitsuLib.Keywords;
+using STS2RitsuLib.Patching.Models;
+
+namespace STS2RitsuLib.Cards.Patches
+{
+    /// <summary>
+    ///     Postfixes vanilla card description builders so mod keywords with
+    ///     <see cref="ModKeywordDefinition.CardDescriptionPlacement" /> inject BBCode like vanilla keywords.
+    /// </summary>
+    public sealed class ModKeywordCardDescriptionPatches : IPatchMethod
+    {
+        /// <inheritdoc />
+        public static string PatchId => "card_mod_keyword_description";
+
+        /// <inheritdoc />
+        public static string Description => "Inject mod keyword BBCode into CardModel description rendering";
+
+        /// <inheritdoc />
+        public static bool IsCritical => false;
+
+        /// <inheritdoc />
+        public static ModPatchTarget[] GetTargets()
+        {
+            return
+            [
+                new(typeof(CardModel), nameof(CardModel.GetDescriptionForPile),
+                    [typeof(PileType), typeof(Creature)]),
+                new(typeof(CardModel), nameof(CardModel.GetDescriptionForUpgradePreview), Type.EmptyTypes),
+            ];
+        }
+
+        // ReSharper disable InconsistentNaming
+        /// <summary>
+        ///     Appends or prepends keyword fragments after vanilla description composition.
+        /// </summary>
+        public static void Postfix(CardModel __instance, ref string __result)
+        {
+            ModKeywordCardDescriptionInjector.AppendFragments(__instance, ref __result);
+        }
+        // ReSharper restore InconsistentNaming
+    }
+}

Combat/HealthBars/BaseLibHealthBarForecastBridge.cs

@@ -0,0 +1,179 @@
+using System.Reflection;
+using MegaCrit.Sts2.Core.Entities.Creatures;
+using STS2RitsuLib.Compat;
+
+namespace STS2RitsuLib.Combat.HealthBars
+{
+    /// <summary>
+    ///     When BaseLib is loaded, registers <see cref="HealthBarForecastRegistry.GetSegments" /> with BaseLib's
+    ///     <c>HealthBarForecastRegistry.RegisterForeign</c> so a single renderer can consume Ritsu-typed segments.
+    /// </summary>
+    /// <remarks>
+    ///     <see cref="ShouldRitsuRendererStandDown" /> becomes true after a successful bridge so duplicate overlays are
+    ///     not drawn.
+    /// </remarks>
+    internal static class BaseLibHealthBarForecastBridge
+    {
+        private const string SourceId = "ritsulib.registry";
+        private static bool _registered;
+        private static bool _baselibSupportsForecastInterop;
+        private static bool _loggedMissingInterop;
+        private static bool _loggedMissingRegisterForeign;
+        private static bool _primaryAttemptIssued;
+        private static bool _secondaryAttemptIssued;
+
+        /// <summary>
+        ///     When <see langword="true" />, Ritsu's <c>NHealthBar</c> forecast postfixes should skip drawing because BaseLib
+        ///     already merged this mod's segments.
+        /// </summary>
+        public static bool ShouldRitsuRendererStandDown()
+        {
+            return _registered && _baselibSupportsForecastInterop;
+        }
+
+        /// <summary>
+        ///     Attempts foreign registration from <c>NHealthBar._Ready</c> (early load path).
+        /// </summary>
+        public static void TryRegisterPrimary()
+        {
+            if (_primaryAttemptIssued || _registered)
+                return;
+            _primaryAttemptIssued = true;
+            TryRegisterCore();
+        }
+
+        /// <summary>
+        ///     Attempts foreign registration from forecast render path if <see cref="TryRegisterPrimary" /> did not run yet.
+        /// </summary>
+        public static void TryRegisterSecondary()
+        {
+            if (_secondaryAttemptIssued || _registered)
+                return;
+            _secondaryAttemptIssued = true;
+            TryRegisterCore();
+        }
+
+        /// <summary>
+        ///     Alias for <see cref="TryRegisterPrimary" />.
+        /// </summary>
+        public static void TryRegister()
+        {
+            TryRegisterPrimary();
+        }
+
+        private static void TryRegisterCore()
+        {
+            if (_registered)
+                return;
+            if (!IsBaseLibLoaded())
+                return;
+
+            try
+            {
+                var registryType = ResolveBaseLibRegistryType();
+                if (registryType == null)
+                    return;
+
+                var registerForeign = registryType.GetMethod(
+                    "RegisterForeign",
+                    BindingFlags.Public | BindingFlags.Static,
+                    null,
+                    [typeof(string), typeof(string), typeof(Func<Creature, IEnumerable<object>>)],
+                    null);
+
+                if (registerForeign == null)
+                {
+                    _baselibSupportsForecastInterop = false;
+                    if (!_loggedMissingRegisterForeign)
+                    {
+                        _loggedMissingRegisterForeign = true;
+                        RitsuLibFramework.Logger.Warn(
+                            $"[HealthBarForecast] BaseLib registry type '{registryType.FullName}' does not expose " +
+                            "RegisterForeign(string, string, Func<Creature, IEnumerable<object>>); forecast interop unavailable.");
+                    }
+
+                    return;
+                }
+
+                var provider = GetSegmentsForCreature;
+                registerForeign.Invoke(null, [Const.ModId, SourceId, provider]);
+                _registered = true;
+                _baselibSupportsForecastInterop = true;
+                RitsuLibFramework.Logger.Info("[HealthBarForecast] Registered BaseLib bridge provider.");
+            }
+            catch (Exception ex)
+            {
+                RitsuLibFramework.Logger.Warn($"[HealthBarForecast] Failed to register BaseLib bridge provider: {ex}");
+            }
+        }
+
+        private static IEnumerable<object> GetSegmentsForCreature(Creature creature)
+        {
+            return HealthBarForecastRegistry.GetSegments(creature)
+                .Select(registered => (object)registered.Segment)
+                .ToArray();
+        }
+
+        private static Type? ResolveBaseLibRegistryType()
+        {
+            var registryType = ResolveRegistryTypeFromLoadedAssemblies();
+            _baselibSupportsForecastInterop = registryType != null;
+
+            if (!_baselibSupportsForecastInterop)
+            {
+                if (_loggedMissingInterop)
+                    return null;
+                _loggedMissingInterop = true;
+                RitsuLibFramework.Logger.Info(
+                    "[HealthBarForecast] BaseLib detected but forecast interop API is unavailable.");
+                return null;
+            }
+
+            _loggedMissingInterop = false;
+
+            return registryType;
+        }
+
+        private static bool IsBaseLibLoaded()
+        {
+            foreach (var mod in Sts2ModManagerCompat.EnumerateLoadedModsWithAssembly())
+            {
+                var assembly = mod.assembly;
+                if (assembly == null)
+                    continue;
+                if (assembly.GetType("BaseLib.Hooks.HealthBarForecastRegistry") != null)
+                    return true;
+            }
+
+            return false;
+        }
+
+        private static Type? ResolveRegistryTypeFromLoadedAssemblies()
+        {
+            var byQualifiedName = Type.GetType("BaseLib.Hooks.HealthBarForecastRegistry, BaseLib");
+            if (byQualifiedName != null)
+                return byQualifiedName;
+
+            var loadedWithAssembly = Sts2ModManagerCompat.EnumerateLoadedModsWithAssembly();
+            foreach (var mod in loadedWithAssembly)
+            {
+                var assembly = mod.assembly;
+                if (assembly == null)
+                    continue;
+
+                var type = assembly.GetType("BaseLib.Hooks.HealthBarForecastRegistry");
+                if (type != null)
+                    return type;
+            }
+
+            foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())
+            {
+                var type = assembly.GetType("BaseLib.Hooks.HealthBarForecastRegistry");
+                if (type != null)
+                    return type;
+            }
+
+            return null;
+        }
+    }
+}

Combat/HealthBars/HealthBarForecastRegistry.cs

@@ -24,19 +24,56 @@ public enum HealthBarForecastGrowthDirection
     ///     One forecast overlay segment for a creature health bar.
     /// </summary>
     /// <param name="Amount">HP amount represented by this segment.</param>
-    /// <param name="Color">Overlay tint.</param>
+    /// <param name="Color">
+    ///     Lethal HP label theming; also used as the forecast nine-patch <see cref="CanvasItem.SelfModulate" /> when
+    ///     <see cref="OverlaySelfModulate" /> is null.
+    /// </param>
     /// <param name="Direction">Which edge the segment grows from.</param>
     /// <param name="Order">
     ///     Lower values are rendered earlier in the chain.
     ///     For <see cref="HealthBarForecastGrowthDirection.FromRight" />, earlier segments stay closer to the current HP
     ///     edge; for <see cref="HealthBarForecastGrowthDirection.FromLeft" />, earlier segments stay closer to the empty
     ///     edge.
     /// </param>
+    /// <param name="OverlayMaterial">
+    ///     Optional Godot material (e.g. shader like vanilla doom). When null, only <see cref="Color" /> tint applies.
+    /// </param>
+    /// <param name="OverlaySelfModulate">
+    ///     Optional <see cref="CanvasItem.SelfModulate" /> for the forecast nine-patch. When null, <see cref="Color" /> is
+    ///     used
+    ///     for both overlay tint and lethal HP label; when set, <see cref="Color" /> is still used for lethal label theming.
+    /// </param>
     public readonly record struct HealthBarForecastSegment(
         int Amount,
         Color Color,
         HealthBarForecastGrowthDirection Direction,
-        int Order = 0);
+        int Order,
+        Material? OverlayMaterial,
+        Color? OverlaySelfModulate = null)
+    {
+        /// <summary>
+        ///     Initializes a segment without overlay material or separate overlay modulate.
+        /// </summary>
+        public HealthBarForecastSegment(int amount, Color color, HealthBarForecastGrowthDirection direction,
+            int order = 0)
+            : this(amount, color, direction, order, null, null)
+        {
+        }
+
+        /// <summary>
+        ///     Initializes a segment with an optional <see cref="OverlayMaterial" /> and default overlay modulate.
+        /// </summary>
+        // ReSharper disable once RedundantOverload.Global
+        public HealthBarForecastSegment(
+            int amount,
+            Color color,
+            HealthBarForecastGrowthDirection direction,
+            int order,
+            Material? overlayMaterial)
+            : this(amount, color, direction, order, overlayMaterial, null)
+        {
+        }
+    }
 
     /// <summary>
     ///     Helpers for common turn-relative ordering of forecast segments.
@@ -74,6 +111,9 @@ public static class HealthBarForecastRegistry
         /// <summary>
         ///     Registers or replaces a forecast provider for <paramref name="modId" />.
         /// </summary>
+        /// <typeparam name="TSource">Concrete <see cref="IHealthBarForecastSource" /> with a parameterless constructor.</typeparam>
+        /// <param name="modId">Owning mod identifier.</param>
+        /// <param name="sourceId">Optional unique id; defaults to the type full name.</param>
         public static void Register<TSource>(string modId, string? sourceId = null)
             where TSource : IHealthBarForecastSource, new()
         {
@@ -83,6 +123,9 @@ public static void Register<TSource>(string modId, string? sourceId = null)
         /// <summary>
         ///     Registers or replaces a forecast source instance for <paramref name="modId" />.
         /// </summary>
+        /// <param name="modId">Owning mod identifier.</param>
+        /// <param name="sourceId">Unique id for this source within the mod.</param>
+        /// <param name="source">Provider instance.</param>
         public static void Register(
             string modId,
             string sourceId,
@@ -106,6 +149,9 @@ public static void Register(
         /// <summary>
         ///     Removes a previously registered provider.
         /// </summary>
+        /// <param name="modId">Mod identifier used at registration.</param>
+        /// <param name="sourceId">Source id used at registration.</param>
+        /// <returns><see langword="true" /> if an entry was removed.</returns>
         public static bool Unregister(string modId, string sourceId)
         {
             ArgumentException.ThrowIfNullOrWhiteSpace(modId);
@@ -117,6 +163,10 @@ public static bool Unregister(string modId, string sourceId)
             }
         }
 
+        /// <summary>
+        ///     Collects segments from powers implementing <see cref="IHealthBarForecastSource" /> and registered providers.
+        /// </summary>
+        /// <param name="creature">Creature whose bar is being evaluated.</param>
         internal static IReadOnlyList<RegisteredHealthBarForecastSegment> GetSegments(Creature creature)
         {
             ArgumentNullException.ThrowIfNull(creature);
@@ -176,6 +226,11 @@ where segment.Amount > 0
             }
         }
 
+        /// <summary>
+        ///     Segment plus a sequence key for stable ordering when <see cref="HealthBarForecastSegment.Order" /> ties.
+        /// </summary>
+        /// <param name="Segment">Forecast data.</param>
+        /// <param name="SequenceOrder">Monotonic key (powers first, then registered sources).</param>
         internal readonly record struct RegisteredHealthBarForecastSegment(
             HealthBarForecastSegment Segment,
             long SequenceOrder);