feat(PortraitMaterials): add support for custom portrait materials in card assets

- Registered a new patch for handling card portrait materials, allowing mods to override portrait rendering.
- Updated relevant classes and interfaces to include portrait material paths and overrides.
- Enhanced documentation to reflect changes in asset profiles and patching mechanisms for portrait materials.

Author: BAKAOLC

RitsuLibFramework.PatcherSetup.cs

@@ -256,6 +256,7 @@ private static void RegisterContentAssetPatches()
             patcher.RegisterPatch<CardTextureOverridePatch>();
             patcher.RegisterPatch<CardFrameMaterialPatch>();
             patcher.RegisterPatch<CardPoolFrameMaterialPatch>();
+            patcher.RegisterPatch<CardPortraitMaterialPatch>();
             patcher.RegisterPatch<CardAllPortraitPathsPatch>();
             patcher.RegisterPatch<CardOverlayPathPatch>();
             patcher.RegisterPatch<CardOverlayAvailabilityPatch>();

Scaffolding/Characters/CharacterAssetProfile.cs

@@ -257,19 +257,19 @@ public sealed record CharacterVanillaPotionVisualOverride(string PotionModelIdEn
     /// <summary>
     ///     One entry in <see cref="CharacterAssetProfile.VanillaCardVisualOverrides" />: when this mod character
     ///     encounters or holds a card whose <c>ModelId.Entry</c> equals <paramref name="CardModelIdEntry" />
-    ///     (ordinal ignore-case), use <paramref name="Assets" /> for portrait/frame/banner/overlay paths.
+    ///     (ordinal ignore-case), use <paramref name="Assets" /> for portrait/frame/banner/overlay paths and materials.
     ///     <see cref="CharacterAssetProfile.VanillaCardVisualOverrides" /> 中的一个条目：当此 mod 角色
     ///     遇到或持有 <c>ModelId.Entry</c> 等于 <paramref name="CardModelIdEntry" />
-    ///     （ordinal ignore-case）的卡牌时，使用 <paramref name="Assets" /> 作为肖像/边框/banner/覆盖层路径。
+    ///     （ordinal ignore-case）的卡牌时，使用 <paramref name="Assets" /> 作为肖像/边框/banner/覆盖层路径和材质。
     /// </summary>
     /// <param name="CardModelIdEntry">
     ///     Stable card id (same string as <c>CardModel.Id.Entry</c>).
     ///     稳定卡牌 id（与 <c>CardModel.Id.Entry</c> 相同的字符串）。
     /// </param>
     /// <param name="Assets">
-    ///     Card portrait and frame/border/material/overlay/banner path bundle (same shape as
+    ///     Card portrait and frame/border/material/overlay/banner path and material bundle (same shape as
     ///     mod card <see cref="CardAssetProfile" />).
-    ///     卡牌肖像和框/边框/材质/覆盖层/banner 路径包（与
+    ///     卡牌肖像和框/边框/材质/覆盖层/banner 路径和材质包（与
     ///     mod 卡牌 <see cref="CardAssetProfile" /> 形态相同）。
     /// </param>
     public sealed record CharacterVanillaCardVisualOverride(string CardModelIdEntry, CardAssetProfile Assets);

Scaffolding/Characters/CharacterAssetProfiles.cs

@@ -361,7 +361,9 @@ internal static CardAssetProfile MergeCardAssetProfiles(CardAssetProfile fallbac
                 profile.BannerTexturePath ?? fallback.BannerTexturePath,
                 profile.BannerMaterialPath ?? fallback.BannerMaterialPath,
                 profile.FrameMaterial ?? fallback.FrameMaterial,
-                profile.BannerMaterial ?? fallback.BannerMaterial);
+                profile.BannerMaterial ?? fallback.BannerMaterial,
+                profile.PortraitMaterialPath ?? fallback.PortraitMaterialPath,
+                profile.PortraitMaterial ?? fallback.PortraitMaterial);
         }
 
         internal static CardAssetProfile? MergeCardAssetProfilesPreferSecond(CardAssetProfile? fallback,

Scaffolding/Content/ContentAssetProfiles.cs

@@ -5,8 +5,9 @@
 namespace STS2RitsuLib.Scaffolding.Content
 {
     /// <summary>
-    ///     Bundle of optional resource paths for mod card portraits, frames, energy icon, overlay scene, and banner.
-    ///     Mod 卡牌肖像、边框、能量图标、覆盖场景和横幅的可选ResourcePath集合。
+    ///     Bundle of optional resource paths and materials for mod card portraits, frames, energy icon, overlay scene,
+    ///     and banner.
+    ///     Mod 卡牌肖像、边框、能量图标、覆盖场景和横幅的可选ResourcePath和材质集合。
     /// </summary>
     /// <param name="PortraitPath">
     ///     Main card portrait image path.
@@ -52,6 +53,14 @@ namespace STS2RitsuLib.Scaffolding.Content
     ///     Direct banner material override.
     ///     直接覆盖横幅材质。
     /// </param>
+    /// <param name="PortraitMaterialPath">
+    ///     Material path for portrait rendering.
+    ///     卡图渲染使用的材质路径。
+    /// </param>
+    /// <param name="PortraitMaterial">
+    ///     Direct portrait material override.
+    ///     直接覆盖卡图材质。
+    /// </param>
     public sealed record CardAssetProfile(
         string? PortraitPath = null,
         string? BetaPortraitPath = null,
@@ -63,7 +72,9 @@ public sealed record CardAssetProfile(
         string? BannerTexturePath = null,
         string? BannerMaterialPath = null,
         Material? FrameMaterial = null,
-        Material? BannerMaterial = null)
+        Material? BannerMaterial = null,
+        string? PortraitMaterialPath = null,
+        Material? PortraitMaterial = null)
     {
         /// <summary>
         ///     Backward-compatible constructor preserving the original parameter list.
@@ -94,8 +105,40 @@ public CardAssetProfile(
         }
 
         /// <summary>
-        ///     Default empty profile (no custom paths).
-        ///     默认空 profile（无自定义路径）。
+        ///     Backward-compatible constructor preserving the direct material parameter list.
+        ///     保留直接材质参数列表的向后兼容构造函数。
+        /// </summary>
+        public CardAssetProfile(
+            string? PortraitPath,
+            string? BetaPortraitPath,
+            string? FramePath,
+            string? PortraitBorderPath,
+            string? EnergyIconPath,
+            string? FrameMaterialPath,
+            string? OverlayScenePath,
+            string? BannerTexturePath,
+            string? BannerMaterialPath,
+            Material? FrameMaterial,
+            Material? BannerMaterial)
+            : this(
+                PortraitPath,
+                BetaPortraitPath,
+                FramePath,
+                PortraitBorderPath,
+                EnergyIconPath,
+                FrameMaterialPath,
+                OverlayScenePath,
+                BannerTexturePath,
+                BannerMaterialPath,
+                FrameMaterial,
+                BannerMaterial,
+                null)
+        {
+        }
+
+        /// <summary>
+        ///     Default empty profile (no custom paths or materials).
+        ///     默认空 profile（无自定义路径或材质）。
         /// </summary>
         public static CardAssetProfile Empty { get; } = new();
     }

Scaffolding/Content/ModCardTemplate.cs

@@ -29,7 +29,7 @@ public abstract class ModCardTemplate(
         TargetType target,
         bool showInCardLibrary = true)
         : CardModel(baseCost, type, rarity, target, showInCardLibrary), IModCardAssetOverrides,
-            IModCardFrameMaterialOverride, IModCardBannerMaterialOverride
+            IModCardPortraitMaterialOverride, IModCardFrameMaterialOverride, IModCardBannerMaterialOverride
     {
         /// <summary>
         ///     Legacy constructor overload; <paramref name="autoAdd" /> is ignored.
@@ -91,6 +91,9 @@ protected ModCardTemplate(
         /// <inheritdoc />
         public virtual string? CustomBetaPortraitPath => AssetProfile.BetaPortraitPath;
 
+        /// <inheritdoc />
+        public virtual string? CustomPortraitMaterialPath => AssetProfile.PortraitMaterialPath;
+
         /// <inheritdoc />
         public virtual string? CustomFramePath => AssetProfile.FramePath;
 
@@ -118,6 +121,9 @@ protected ModCardTemplate(
         /// <inheritdoc />
         public virtual Material? CustomFrameMaterial => AssetProfile.FrameMaterial;
 
+        /// <inheritdoc />
+        public virtual Material? CustomPortraitMaterial => AssetProfile.PortraitMaterial;
+
         /// <summary>
         ///     Internal accessor for the mod-keyword seeding patch.
         ///     供 mod 关键词种入补丁使用的内部访问器。

Scaffolding/Content/Patches/ContentAssetOverridePatches.cs

@@ -2,13 +2,17 @@
 using Godot;
 using HarmonyLib;
 using MegaCrit.Sts2.Core.Assets;
+using MegaCrit.Sts2.Core.Entities.Cards;
+using MegaCrit.Sts2.Core.Entities.UI;
 using MegaCrit.Sts2.Core.Events;
 using MegaCrit.Sts2.Core.Helpers;
 using MegaCrit.Sts2.Core.Models;
+using MegaCrit.Sts2.Core.Nodes.Cards;
 using MegaCrit.Sts2.Core.Runs;
 using MegaCrit.Sts2.Core.Timeline;
 using STS2RitsuLib.Patching.Models;
 using STS2RitsuLib.Scaffolding.Characters;
+using STS2RitsuLib.Timeline.Scaffolding;
 using STS2RitsuLib.Utils;
 
 namespace STS2RitsuLib.Scaffolding.Content.Patches
@@ -282,8 +286,8 @@ internal static bool TryUseCompressedTextureAsTexture2DOverride<TOverrides>(
     }
 
     /// <summary>
-    ///     Optional card art paths consumed by content asset Harmony patches on <see cref="CardModel" />.
-    ///     由 <see cref="CardModel" /> 上的 content asset Harmony 补丁使用的可选卡牌美术路径。
+    ///     Optional card art paths and materials consumed by content asset Harmony patches.
+    ///     由 content asset Harmony 补丁使用的可选卡牌美术路径和材质。
     /// </summary>
     public interface IModCardAssetOverrides
     {
@@ -305,6 +309,12 @@ public interface IModCardAssetOverrides
         /// </summary>
         string? CustomBetaPortraitPath { get; }
 
+        /// <summary>
+        ///     Override for card portrait <see cref="Material" /> resource path.
+        ///     卡图 <see cref="Material" /> 资源路径覆盖。
+        /// </summary>
+        string? CustomPortraitMaterialPath => AssetProfile.PortraitMaterialPath;
+
         /// <summary>
         ///     Override for card frame texture path.
         ///     卡牌边框纹理路径覆盖。
@@ -348,6 +358,23 @@ public interface IModCardAssetOverrides
         string? CustomBannerMaterialPath { get; }
     }
 
+    /// <summary>
+    ///     Optional direct portrait <see cref="Material" /> override for cards.
+    ///     This is applied to the portrait TextureRect after <see cref="NCard" /> reloads its vanilla visuals.
+    ///     用于卡牌的可选直接卡图 <see cref="Material" /> 覆盖。
+    ///     会在 <see cref="NCard" /> 重载原版视觉后应用到卡图 TextureRect。
+    /// </summary>
+    public interface IModCardPortraitMaterialOverride
+    {
+        /// <summary>
+        ///     Direct portrait material override.
+        ///     Return <c>null</c> to continue with other override layers.
+        ///     直接的卡图材质覆盖。
+        ///     返回 <c>null</c> 以继续使用其它覆盖层。
+        /// </summary>
+        Material? CustomPortraitMaterial => null;
+    }
+
     /// <summary>
     ///     Optional direct frame <see cref="Material" /> override for cards.
     ///     This bypasses resource-path loading and is checked before
@@ -733,8 +760,9 @@ public static ModPatchTarget[] GetTargets()
         /// <summary>
         ///     Suppresses the vanilla placeholder label for mod epochs with custom artwork.
         /// </summary>
-        // ReSharper disable once InconsistentNaming
+        // ReSharper disable InconsistentNaming
         public static bool Prefix(EpochModel __instance, ref bool __result)
+            // ReSharper restore InconsistentNaming
         {
             if (__instance is IModEpochAssetOverrides overrides &&
                 !string.IsNullOrWhiteSpace(overrides.CustomBigPortraitPath) &&
@@ -757,12 +785,10 @@ public static bool Prefix(EpochModel __instance, ref bool __result)
         private static bool IsCharacterUnlockEpochTemplate(Type type)
         {
             for (var current = type; current != null; current = current.BaseType)
-            {
                 if (current.IsGenericType &&
                     current.GetGenericTypeDefinition() ==
-                    typeof(STS2RitsuLib.Timeline.Scaffolding.CharacterUnlockEpochTemplate<>))
+                    typeof(CharacterUnlockEpochTemplate<>))
                     return true;
-            }
 
             return false;
         }
@@ -1079,6 +1105,76 @@ public static bool Prefix(CardPoolModel __instance, ref Material __result)
         }
     }
 
+    /// <summary>
+    ///     Applies custom portrait <see cref="Material" /> overrides after <see cref="NCard" /> reloads vanilla visuals.
+    ///     在 <see cref="NCard" /> 重载原版视觉后应用自定义卡图 <see cref="Material" /> 覆盖。
+    /// </summary>
+    public class CardPortraitMaterialPatch : IPatchMethod
+    {
+        /// <inheritdoc cref="IPatchMethod.PatchId" />
+        public static string PatchId => "content_asset_override_card_portrait_material";
+
+        /// <inheritdoc cref="IPatchMethod.Description" />
+        public static string Description => "Allow mod cards to override the NCard portrait material";
+
+        /// <inheritdoc cref="IPatchMethod.IsCritical" />
+        public static bool IsCritical => false;
+
+        /// <inheritdoc cref="IPatchMethod.GetTargets" />
+        public static ModPatchTarget[] GetTargets()
+        {
+            return [new(typeof(NCard), "Reload")];
+        }
+
+        // ReSharper disable InconsistentNaming
+        /// <summary>
+        ///     Reapplies the custom material because vanilla <c>Reload</c> clears portrait materials for visible cards.
+        ///     重新应用自定义材质，因为原版 <c>Reload</c> 会清空可见卡牌的卡图材质。
+        /// </summary>
+        public static void Postfix(NCard __instance)
+            // ReSharper restore InconsistentNaming
+        {
+            var model = __instance.Model;
+            if (model == null || __instance.Visibility != ModelVisibility.Visible)
+                return;
+
+            if (!TryGetPortraitMaterial(model, out var material))
+                return;
+
+            var portrait = GetPortraitNode(__instance, model);
+            if (portrait == null)
+                return;
+
+            portrait.Material = material;
+        }
+
+        private static TextureRect? GetPortraitNode(NCard card, CardModel model)
+        {
+            var path = model.Rarity == CardRarity.Ancient ? "%AncientPortrait" : "%Portrait";
+            return card.GetNodeOrNull<TextureRect>(path);
+        }
+
+        private static bool TryGetPortraitMaterial(CardModel card, out Material material)
+        {
+            material = null!;
+            if (!ContentAssetOverridePatchHelper.TryUseDirectMaterialOverride<IModCardPortraitMaterialOverride>(
+                    card, ref material, static o => o.CustomPortraitMaterial))
+                return true;
+
+            if (ExternalCardMaterialOverrideRegistry.TryGetPortraitMaterial(card, out material))
+                return true;
+
+            if (!ModCharacterOwnedVisualOverrideHelper.TryCardPortraitMaterial(card, ref material))
+                return true;
+
+            return !ContentAssetOverridePatchHelper.TryUseMaterialOverride<IModCardAssetOverrides>(
+                card,
+                ref material,
+                static o => o.CustomPortraitMaterialPath,
+                nameof(IModCardAssetOverrides.CustomPortraitMaterialPath));
+        }
+    }
+
     /// <summary>
     ///     Patches <see cref="CardModel.AllPortraitPaths" /> so custom portrait/beta paths participate in preload lists.
     ///     修补<see cref="CardModel.AllPortraitPaths" />，使自定义 portrait/beta 路径 participate in 预加载 列表。