feat(CardAssets): Add ancient banner support to card asset profiles

BAKAOLC · BAKAOLC · commit aae3aead725e · 2026-06-13T23:28:56.000+08:00
- Introduced new properties for ancient banner texture and material paths in `CardAssetProfile`.
- Updated `ModCardTemplate` and related interfaces to include ancient banner material overrides.
- Enhanced visual override logic to support ancient banner textures and materials in card nodes.
- Improved documentation to reflect the addition of ancient banner fields and their usage in asset profiles.
diff --git a/Scaffolding/Characters/CharacterAssetProfiles.cs b/Scaffolding/Characters/CharacterAssetProfiles.cs
@@ -373,7 +373,10 @@ internal static CardAssetProfile MergeCardAssetProfiles(CardAssetProfile fallbac
                 profile.AncientBorderMaterialPath ?? fallback.AncientBorderMaterialPath,
                 profile.AncientBorderMaterial ?? fallback.AncientBorderMaterial,
                 profile.AncientTextBgMaterialPath ?? fallback.AncientTextBgMaterialPath,
-                profile.AncientTextBgMaterial ?? fallback.AncientTextBgMaterial);
+                profile.AncientTextBgMaterial ?? fallback.AncientTextBgMaterial,
+                profile.AncientBannerPath ?? fallback.AncientBannerPath,
+                profile.AncientBannerMaterialPath ?? fallback.AncientBannerMaterialPath,
+                profile.AncientBannerMaterial ?? fallback.AncientBannerMaterial);
         }
 
         internal static CardAssetProfile? MergeCardAssetProfilesPreferSecond(CardAssetProfile? fallback,
diff --git a/Scaffolding/Content/ContentAssetProfiles.cs b/Scaffolding/Content/ContentAssetProfiles.cs
@@ -102,6 +102,18 @@ namespace STS2RitsuLib.Scaffolding.Content
     ///     Direct ancient card text background material override.
     ///     直接覆盖 Ancient 卡牌文本背景材质。
     /// </param>
+    /// <param name="AncientBannerPath">
+    ///     Ancient card title banner texture path.
+    ///     Ancient 卡牌卡名横幅贴图路径。
+    /// </param>
+    /// <param name="AncientBannerMaterialPath">
+    ///     Material path for ancient card title banner rendering.
+    ///     Ancient 卡牌卡名横幅渲染使用的材质路径。
+    /// </param>
+    /// <param name="AncientBannerMaterial">
+    ///     Direct ancient card title banner material override.
+    ///     直接覆盖 Ancient 卡牌卡名横幅材质。
+    /// </param>
     public sealed record CardAssetProfile(
         string? PortraitPath = null,
         string? BetaPortraitPath = null,
@@ -125,7 +137,10 @@ public sealed record CardAssetProfile(
         string? AncientBorderMaterialPath = null,
         Material? AncientBorderMaterial = null,
         string? AncientTextBgMaterialPath = null,
-        Material? AncientTextBgMaterial = null)
+        Material? AncientTextBgMaterial = null,
+        string? AncientBannerPath = null,
+        string? AncientBannerMaterialPath = null,
+        Material? AncientBannerMaterial = null)
     {
         /// <summary>
         ///     Backward-compatible constructor preserving the original parameter list.
@@ -223,6 +238,62 @@ public CardAssetProfile(
         {
         }
 
+        /// <summary>
+        ///     Backward-compatible constructor preserving the ancient texture/material parameter list.
+        ///     保留 ancient 贴图/材质参数列表的向后兼容构造函数。
+        /// </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,
+            string? PortraitMaterialPath,
+            Material? PortraitMaterial,
+            string? AncientBorderPath,
+            string? AncientTextBgPath,
+            string? PortraitBorderMaterialPath,
+            Material? PortraitBorderMaterial,
+            string? EnergyIconMaterialPath,
+            Material? EnergyIconMaterial,
+            string? AncientBorderMaterialPath,
+            Material? AncientBorderMaterial,
+            string? AncientTextBgMaterialPath,
+            Material? AncientTextBgMaterial)
+            : this(
+                PortraitPath,
+                BetaPortraitPath,
+                FramePath,
+                PortraitBorderPath,
+                EnergyIconPath,
+                FrameMaterialPath,
+                OverlayScenePath,
+                BannerTexturePath,
+                BannerMaterialPath,
+                FrameMaterial,
+                BannerMaterial,
+                PortraitMaterialPath,
+                PortraitMaterial,
+                AncientBorderPath,
+                AncientTextBgPath,
+                PortraitBorderMaterialPath,
+                PortraitBorderMaterial,
+                EnergyIconMaterialPath,
+                EnergyIconMaterial,
+                AncientBorderMaterialPath,
+                AncientBorderMaterial,
+                AncientTextBgMaterialPath,
+                AncientTextBgMaterial,
+                null)
+        {
+        }
+
         /// <summary>
         ///     Default empty profile (no custom paths or materials).
         ///     默认空 profile（无自定义路径或材质）。
@@ -656,8 +727,9 @@ public static CardAssetProfile Card(string poolEntry, string cardEntry)
         }
 
         /// <summary>
-        ///     Builds default portrait, overlay, ancient border, and ancient text background paths for an ancient card.
-        ///     为 ancient 卡牌构建默认肖像、覆盖层、ancient 边框和 ancient 文本背景路径。
+        ///     Builds default portrait, overlay, ancient border, ancient title banner, and ancient text background paths
+        ///     for an ancient card.
+        ///     为 ancient 卡牌构建默认肖像、覆盖层、ancient 边框、ancient 卡名横幅和 ancient 文本背景路径。
         /// </summary>
         public static CardAssetProfile AncientCard(string poolEntry, string cardEntry, CardType cardType)
         {
@@ -674,7 +746,8 @@ public static CardAssetProfile AncientCard(string poolEntry, string cardEntry, C
                 AncientBorderPath: ImageHelper.GetImagePath(
                     "atlases/compressed_atlas.sprites/ancient_card_border.png.tres"),
                 AncientTextBgPath: ImageHelper.GetImagePath(
-                    $"atlases/compressed_atlas.sprites/ancient_text_bg_{normalizedType}.png.tres"));
+                    $"atlases/compressed_atlas.sprites/ancient_text_bg_{normalizedType}.png.tres"),
+                AncientBannerPath: ImageHelper.GetImagePath("atlases/ui_atlas.sprites/card/ancient_banner.tres"));
         }
 
         /// <summary>
diff --git a/Scaffolding/Content/ModCardTemplate.cs b/Scaffolding/Content/ModCardTemplate.cs
@@ -31,7 +31,8 @@ public abstract class ModCardTemplate(
         : CardModel(baseCost, type, rarity, target, showInCardLibrary), IModCardAssetOverrides,
             IModCardPortraitMaterialOverride, IModCardFrameMaterialOverride, IModCardBannerMaterialOverride,
             IModCardPortraitBorderMaterialOverride, IModCardEnergyIconMaterialOverride,
-            IModCardAncientBorderMaterialOverride, IModCardAncientTextBgMaterialOverride
+            IModCardAncientBorderMaterialOverride, IModCardAncientTextBgMaterialOverride,
+            IModCardAncientBannerMaterialOverride
     {
         /// <summary>
         ///     Legacy constructor overload; <paramref name="autoAdd" /> is ignored.
@@ -84,6 +85,9 @@ protected ModCardTemplate(
         /// <inheritdoc />
         protected sealed override IEnumerable<IHoverTip> ExtraHoverTips => AdditionalHoverTips.ToArray();
 
+        /// <inheritdoc />
+        public virtual Material? CustomAncientBannerMaterial => AssetProfile.AncientBannerMaterial;
+
         /// <inheritdoc />
         public virtual Material? CustomAncientBorderMaterial => AssetProfile.AncientBorderMaterial;
 
@@ -117,6 +121,9 @@ protected ModCardTemplate(
         /// <inheritdoc />
         public virtual string? CustomAncientTextBgPath => AssetProfile.AncientTextBgPath;
 
+        /// <inheritdoc />
+        public virtual string? CustomAncientBannerPath => AssetProfile.AncientBannerPath;
+
         /// <inheritdoc />
         public virtual string? CustomFrameMaterialPath => AssetProfile.FrameMaterialPath;
 
@@ -132,6 +139,9 @@ protected ModCardTemplate(
         /// <inheritdoc />
         public virtual string? CustomAncientTextBgMaterialPath => AssetProfile.AncientTextBgMaterialPath;
 
+        /// <inheritdoc />
+        public virtual string? CustomAncientBannerMaterialPath => AssetProfile.AncientBannerMaterialPath;
+
         /// <inheritdoc />
         public virtual string? CustomOverlayScenePath => AssetProfile.OverlayScenePath;
 
diff --git a/Scaffolding/Content/Patches/ContentAssetModelVisualOverridePatches.cs b/Scaffolding/Content/Patches/ContentAssetModelVisualOverridePatches.cs
@@ -528,15 +528,15 @@ private static bool TryGetPortraitMaterial(CardModel card, out Material material
     }
 
     /// <summary>
-    ///     Applies custom <see cref="Material" /> overrides for card subnodes that do not expose model material getters.
-    ///     为没有 model 材质 getter 的卡牌子节点应用自定义 <see cref="Material" /> 覆盖。
+    ///     Applies custom visual overrides for card subnodes that do not expose model getters.
+    ///     为没有 model getter 的卡牌子节点应用自定义视觉覆盖。
     /// </summary>
     internal class CardNodeMaterialPatch : IPatchMethod
     {
         public static string PatchId => "content_asset_override_card_node_material";
 
         public static string Description =>
-            "Allow mod cards to override portrait border, energy icon, and ancient node materials";
+            "Allow mod cards to override portrait border, energy icon, and ancient node visuals";
 
         public static bool IsCritical => false;
 
@@ -551,6 +551,22 @@ public static void Postfix(NCard __instance)
             if (model == null || __instance.Visibility != ModelVisibility.Visible)
                 return;
 
+            ApplyTexture(
+                __instance,
+                model,
+                "%AncientBorder",
+                static o => o.CustomAncientBorderPath,
+                nameof(IModCardAssetOverrides.CustomAncientBorderPath),
+                ModCharacterOwnedVisualOverrideHelper.TryCardAncientBorderTexture);
+
+            ApplyTexture(
+                __instance,
+                model,
+                "%AncientBanner",
+                static o => o.CustomAncientBannerPath,
+                nameof(IModCardAssetOverrides.CustomAncientBannerPath),
+                ModCharacterOwnedVisualOverrideHelper.TryCardAncientBannerTexture);
+
             ApplyMaterial<IModCardPortraitBorderMaterialOverride>(
                 __instance,
                 model,
@@ -586,6 +602,33 @@ public static void Postfix(NCard __instance)
                 static o => o.CustomAncientTextBgMaterialPath,
                 nameof(IModCardAssetOverrides.CustomAncientTextBgMaterialPath),
                 ModCharacterOwnedVisualOverrideHelper.TryCardAncientTextBgMaterial);
+
+            ApplyMaterial<IModCardAncientBannerMaterialOverride>(
+                __instance,
+                model,
+                "%AncientBanner",
+                static o => o.CustomAncientBannerMaterial,
+                static o => o.CustomAncientBannerMaterialPath,
+                nameof(IModCardAssetOverrides.CustomAncientBannerMaterialPath),
+                ModCharacterOwnedVisualOverrideHelper.TryCardAncientBannerMaterial);
+        }
+
+        private static void ApplyTexture(
+            NCard card,
+            CardModel model,
+            NodePath nodePath,
+            Func<IModCardAssetOverrides, string?> pathSelector,
+            string memberName,
+            TryCharacterOwnedTextureOverride tryCharacterOwned)
+        {
+            if (!TryGetTexture(model, pathSelector, memberName, tryCharacterOwned, out var texture))
+                return;
+
+            var node = card.GetNodeOrNull<TextureRect>(nodePath);
+            if (node == null)
+                return;
+
+            node.Texture = texture;
         }
 
         private static void ApplyMaterial<TDirectOverride>(
@@ -632,7 +675,27 @@ private static bool TryGetMaterial<TDirectOverride>(
                 memberName);
         }
 
+        private static bool TryGetTexture(
+            CardModel model,
+            Func<IModCardAssetOverrides, string?> pathSelector,
+            string memberName,
+            TryCharacterOwnedTextureOverride tryCharacterOwned,
+            out Texture2D texture)
+        {
+            texture = null!;
+            if (!tryCharacterOwned(model, ref texture))
+                return true;
+
+            return !ContentAssetOverridePatchHelper.TryUseTextureOverride(
+                model,
+                ref texture,
+                pathSelector,
+                memberName);
+        }
+
         private delegate bool TryCharacterOwnedMaterialOverride(CardModel model, ref Material material);
+
+        private delegate bool TryCharacterOwnedTextureOverride(CardModel model, ref Texture2D texture);
     }
 
     /// <summary>
diff --git a/Scaffolding/Content/Patches/ContentAssetOverridePatches.cs b/Scaffolding/Content/Patches/ContentAssetOverridePatches.cs
@@ -429,6 +429,12 @@ public interface IModCardAssetOverrides
         /// </summary>
         string? CustomAncientTextBgPath => AssetProfile.AncientTextBgPath;
 
+        /// <summary>
+        ///     Override for ancient card title banner texture path.
+        ///     Ancient 卡牌卡名横幅纹理路径覆盖。
+        /// </summary>
+        string? CustomAncientBannerPath => AssetProfile.AncientBannerPath;
+
         /// <summary>
         ///     Override for frame <see cref="Material" /> resource path.
         ///     边框 <see cref="Material" /> 资源路径覆盖。
@@ -459,6 +465,12 @@ public interface IModCardAssetOverrides
         /// </summary>
         string? CustomAncientTextBgMaterialPath => AssetProfile.AncientTextBgMaterialPath;
 
+        /// <summary>
+        ///     Override for ancient card title banner <see cref="Material" /> resource path.
+        ///     Ancient 卡牌卡名横幅 <see cref="Material" /> 资源路径覆盖。
+        /// </summary>
+        string? CustomAncientBannerMaterialPath => AssetProfile.AncientBannerMaterialPath;
+
         /// <summary>
         ///     Override for built-in overlay packed scene path.
         ///     内置覆盖层 packed scene路径覆盖。
@@ -574,6 +586,21 @@ public interface IModCardAncientTextBgMaterialOverride
         Material? CustomAncientTextBgMaterial => null;
     }
 
+    /// <summary>
+    ///     Optional direct ancient card title banner <see cref="Material" /> override for cards.
+    ///     用于 ancient 卡牌的可选直接卡名横幅 <see cref="Material" /> 覆盖。
+    /// </summary>
+    public interface IModCardAncientBannerMaterialOverride
+    {
+        /// <summary>
+        ///     Direct ancient card title banner material override.
+        ///     Return <c>null</c> to continue with other override layers.
+        ///     直接的 ancient 卡牌卡名横幅材质覆盖。
+        ///     返回 <c>null</c> 以继续使用其它覆盖层。
+        /// </summary>
+        Material? CustomAncientBannerMaterial => null;
+    }
+
     /// <summary>
     ///     Optional direct banner <see cref="Material" /> override for cards.
     ///     This bypasses resource-path loading and is checked before
diff --git a/Scaffolding/Content/Patches/ModCharacterOwnedRelicVisualOverrideHelper.cs b/Scaffolding/Content/Patches/ModCharacterOwnedRelicVisualOverrideHelper.cs
@@ -206,14 +206,16 @@ internal static void InvalidateCachesForCharacterEntry(string normalizedCharacte
                     string.IsNullOrWhiteSpace(a.EnergyIconPath) && string.IsNullOrWhiteSpace(a.FrameMaterialPath) &&
                     string.IsNullOrWhiteSpace(a.AncientBorderPath) &&
                     string.IsNullOrWhiteSpace(a.AncientTextBgPath) &&
+                    string.IsNullOrWhiteSpace(a.AncientBannerPath) &&
                     string.IsNullOrWhiteSpace(a.OverlayScenePath) && string.IsNullOrWhiteSpace(a.BannerTexturePath) &&
                     string.IsNullOrWhiteSpace(a.BannerMaterialPath) && a.FrameMaterial == null &&
                     a.BannerMaterial == null && string.IsNullOrWhiteSpace(a.PortraitMaterialPath) &&
                     a.PortraitMaterial == null &&
                     string.IsNullOrWhiteSpace(a.PortraitBorderMaterialPath) && a.PortraitBorderMaterial == null &&
                     string.IsNullOrWhiteSpace(a.EnergyIconMaterialPath) && a.EnergyIconMaterial == null &&
                     string.IsNullOrWhiteSpace(a.AncientBorderMaterialPath) && a.AncientBorderMaterial == null &&
-                    string.IsNullOrWhiteSpace(a.AncientTextBgMaterialPath) && a.AncientTextBgMaterial == null)
+                    string.IsNullOrWhiteSpace(a.AncientTextBgMaterialPath) && a.AncientTextBgMaterial == null &&
+                    string.IsNullOrWhiteSpace(a.AncientBannerMaterialPath) && a.AncientBannerMaterial == null)
                     return null;
 
                 return a;
@@ -615,6 +617,44 @@ internal static bool TryCardAncientTextBgMaterial(CardModel instance, ref Materi
             return false;
         }
 
+        internal static bool TryCardAncientBannerMaterial(CardModel instance, ref Material result)
+        {
+            var overrides = TryGetOwningCharacterOverrides(instance);
+            var profile = overrides?.TryGetVanillaCardVisualOverrideForContext(instance);
+            if (profile == null)
+                return true;
+
+            if (profile.AncientBannerMaterial != null)
+            {
+                result = profile.AncientBannerMaterial;
+                return false;
+            }
+
+            var path = profile.AncientBannerMaterialPath;
+            if (string.IsNullOrWhiteSpace(path) ||
+                !AssetPathDiagnostics.Exists(path, instance, nameof(CardAssetProfile.AncientBannerMaterialPath)))
+                return true;
+
+            result = ResourceLoader.Load<Material>(path);
+            return false;
+        }
+
+        internal static bool TryCardAncientBannerTexture(CardModel instance, ref Texture2D result)
+        {
+            var overrides = TryGetOwningCharacterOverrides(instance);
+            var profile = overrides?.TryGetVanillaCardVisualOverrideForContext(instance);
+            if (profile == null)
+                return true;
+
+            var path = profile.AncientBannerPath;
+            if (string.IsNullOrWhiteSpace(path) ||
+                !AssetPathDiagnostics.Exists(path, instance, nameof(CardAssetProfile.AncientBannerPath)))
+                return true;
+
+            result = ResourceLoader.Load<Texture2D>(path);
+            return false;
+        }
+
         internal static bool TryCardOverlayPath(CardModel instance, ref string result)
         {
             var overrides = TryGetOwningCharacterOverrides(instance);
diff --git a/docs/pages/guide/asset-profiles-and-fallbacks.md b/docs/pages/guide/asset-profiles-and-fallbacks.md
