feat(card-type-text): implement BaseLib-compatible card type text modifiers and localization support

BAKAOLC · BAKAOLC · commit eb504ee37ab6 · 2026-07-22T16:25:20.000+08:00
diff --git a/docs/pages/guide/content-authoring-toolkit.md b/docs/pages/guide/content-authoring-toolkit.md
@@ -346,6 +346,69 @@ base game class already reads `LocString` from its table.
 
 :::
 
+## Card Type Text{lang="en"}
+
+::: en
+
+The API mirrors BaseLib's type-text contracts and composition behavior. Implement `ICustomTypeTextCard` on a card when
+it modifies its own type plaque:
+
+```csharp
+IEnumerable<LocString> ICustomTypeTextCard.GetTypeModifiers()
+{
+    return
+    [
+        new LocString("my_mod_ui", "card_type.cursed"),
+    ];
+}
+```
+
+Implement `ICardTypeTextModifier.GetTypeModifiers(CardModel)` on a card capability, relic, power, or other model-owned
+effect. RitsuLib discovers model and capability implementations through the normal run/combat hook-listener order.
+Only genuinely process-wide effects should use `RitsuLibFramework.RegisterCardTypeTextModifier(...)`.
+
+Composition is intentionally identical to BaseLib:
+
+- A localized string containing `{Type}` wraps the selected base text.
+- A localized string without `{Type}` replaces the base text; the last replacement wins.
+- All replacements are selected before wrappers are applied. Wrappers retain their original source order.
+
+For example, `"Cursed {Type}"` turns `Attack` into `Cursed Attack`. When BaseLib is installed, its modifiers compose
+first, RitsuLib modifiers compose second, and the resulting `LocString` is formatted only once.
+
+:::
+
+## 卡牌类型文本{lang="zh-CN"}
+
+::: zh-CN
+
+该 API 镜像 BaseLib 的类型文本契约与组合行为。卡牌修改自身类型牌匾时，实现 `ICustomTypeTextCard`：
+
+```csharp
+IEnumerable<LocString> ICustomTypeTextCard.GetTypeModifiers()
+{
+    return
+    [
+        new LocString("my_mod_ui", "card_type.cursed"),
+    ];
+}
+```
+
+卡牌 capability、遗物、能力或其他模型所属效果实现
+`ICardTypeTextModifier.GetTypeModifiers(CardModel)`。RitsuLib 会按常规跑局/战斗 hook listener 顺序发现模型和
+capability 实现。只有真正的进程级效果才使用 `RitsuLibFramework.RegisterCardTypeTextModifier(...)`。
+
+组合行为有意保持与 BaseLib 完全一致：
+
+- 本地化文本包含 `{Type}` 时，包裹选定的基础文本。
+- 不包含 `{Type}` 时替换基础文本；最后一个 replacement 胜出。
+- 先选出全部 replacement，再应用 wrapper；wrapper 保持原始来源顺序。
+
+例如本地化值 `"诅咒{Type}"` 会把 `攻击` 变成 `诅咒攻击`。安装 BaseLib 时，先组合 BaseLib 修改器，再组合
+RitsuLib 修改器，最终得到的 `LocString` 只格式化一次。
+
+:::
+
 ## Entry Ids{lang="en"}
 
 ::: en
diff --git a/src/Cards/CardTypeTextHook.cs b/src/Cards/CardTypeTextHook.cs
@@ -0,0 +1,95 @@
+using MegaCrit.Sts2.Core.Localization;
+using MegaCrit.Sts2.Core.Models;
+using STS2RitsuLib.Models.Capabilities;
+
+namespace STS2RitsuLib.Cards
+{
+    /// <summary>
+    ///     Dispatches BaseLib-compatible card type text modifiers from cards, model capabilities, run/combat hook
+    ///     listeners, and registered global modifiers.
+    ///     从卡牌、模型能力、跑局/战斗 hook listener 和已注册的全局修改器分发与 BaseLib 兼容的卡牌类型文本修改。
+    /// </summary>
+    public static class CardTypeTextHook
+    {
+        private const string TypeArgumentName = "Type";
+        private static readonly ModelHookListenerRegistry<ICardTypeTextModifier> GlobalModifiers = new();
+
+        /// <summary>
+        ///     Registers a process-wide modifier. Model-owned effects should usually implement
+        ///     <see cref="ICardTypeTextModifier" /> directly.
+        ///     注册一个进程级修改器。模型所属效果通常应直接实现 <see cref="ICardTypeTextModifier" />。
+        /// </summary>
+        public static void RegisterGlobalModifier(ICardTypeTextModifier modifier)
+        {
+            GlobalModifiers.Register(modifier);
+        }
+
+        internal static LocString Apply(LocString originalPlaqueText, CardModel card)
+        {
+            var modifiers = GetTypeModifiers(card);
+            var modifiersByWrapMode = modifiers.ToLookup(ReferencesTypeArgument);
+
+            foreach (var modifier in modifiersByWrapMode[false])
+                originalPlaqueText = modifier;
+
+            var previousTypeText = originalPlaqueText;
+            foreach (var modifier in modifiersByWrapMode[true])
+            {
+                modifier.Add(TypeArgumentName, previousTypeText);
+                previousTypeText = modifier;
+            }
+
+            return previousTypeText;
+        }
+
+        private static IEnumerable<LocString> GetTypeModifiers(CardModel card)
+        {
+            if (card is ICustomTypeTextCard customTypeTextCard)
+                foreach (var modifier in customTypeTextCard.GetTypeModifiers())
+                    yield return modifier;
+
+            foreach (var capability in ModelCapabilityHost.GetCapabilities<ICardTypeTextModifier>(card))
+            foreach (var modifier in capability.GetTypeModifiers(card))
+                yield return modifier;
+
+            foreach (var source in IterateHookModifiers(card))
+            foreach (var modifier in source.GetTypeModifiers(card))
+                yield return modifier;
+        }
+
+        private static IEnumerable<ICardTypeTextModifier> IterateHookModifiers(CardModel card)
+        {
+            HashSet<ICardTypeTextModifier> seen = new(ReferenceEqualityComparer.Instance);
+            foreach (var capability in ModelCapabilityHost.GetCapabilities<ICardTypeTextModifier>(card))
+                seen.Add(capability);
+
+            if (card.RunState is { } runState)
+            {
+                foreach (var entry in ModelHookListenerDispatcher.FromRun(
+                             runState,
+                             card.CombatState,
+                             GlobalModifiers))
+                    if (seen.Add(entry.Listener))
+                        yield return entry.Listener;
+                yield break;
+            }
+
+            if (card.CombatState is { } combatState)
+            {
+                foreach (var entry in ModelHookListenerDispatcher.FromCombat(combatState, GlobalModifiers))
+                    if (seen.Add(entry.Listener))
+                        yield return entry.Listener;
+                yield break;
+            }
+
+            foreach (var modifier in GlobalModifiers.Snapshot())
+                if (seen.Add(modifier))
+                    yield return modifier;
+        }
+
+        private static bool ReferencesTypeArgument(LocString modifier)
+        {
+            return modifier.GetRawText().Contains("{" + TypeArgumentName + "}", StringComparison.Ordinal);
+        }
+    }
+}
diff --git a/src/Models/Capabilities/CardModelCapabilityContributors.cs b/src/Models/Capabilities/CardModelCapabilityContributors.cs
@@ -289,6 +289,37 @@ public interface ICardTitleContributor
         IEnumerable<CardTitleFragment> GetTitleFragments(CardTitleContext context);
     }
 
+    /// <summary>
+    ///     Optional card interface for visually modifying its own type text. Returned strings use the same composition
+    ///     contract as BaseLib: entries containing <c>{Type}</c> wrap the selected base text, while entries without it
+    ///     replace the base text.
+    ///     可选卡牌接口：修改自身显示的类型文本。返回文本使用与 BaseLib 相同的组合契约：包含 <c>{Type}</c> 的条目
+    ///     包裹选定的基础文本，不包含它的条目替换基础文本。
+    /// </summary>
+    public interface ICustomTypeTextCard
+    {
+        /// <summary>
+        ///     Returns localized type text modifiers in application order.
+        ///     按应用顺序返回本地化类型文本修改器。
+        /// </summary>
+        IEnumerable<LocString> GetTypeModifiers();
+    }
+
+    /// <summary>
+    ///     Optional model or model-capability hook for visually modifying cards' type text. The method signature and
+    ///     composition contract match BaseLib's <c>ICardTypeTextModifier</c>.
+    ///     可选模型或模型能力 hook：修改卡牌显示的类型文本。方法签名与组合契约和 BaseLib 的
+    ///     <c>ICardTypeTextModifier</c> 一致。
+    /// </summary>
+    public interface ICardTypeTextModifier
+    {
+        /// <summary>
+        ///     Returns localized type text modifiers for <paramref name="card" /> in application order.
+        ///     按应用顺序返回 <paramref name="card" /> 的本地化类型文本修改器。
+        /// </summary>
+        IEnumerable<LocString> GetTypeModifiers(CardModel card);
+    }
+
     /// <summary>
     ///     Optional model capability that contributes hand glow predicates.
     ///     可选能力：贡献手牌发光判定。
diff --git a/src/Models/Capabilities/Patches/CardModelCapabilityPatches.cs b/src/Models/Capabilities/Patches/CardModelCapabilityPatches.cs
@@ -11,8 +11,10 @@
 using MegaCrit.Sts2.Core.Helpers.Models;
 using MegaCrit.Sts2.Core.Hooks;
 using MegaCrit.Sts2.Core.HoverTips;
+using MegaCrit.Sts2.Core.Localization;
 using MegaCrit.Sts2.Core.Localization.DynamicVars;
 using MegaCrit.Sts2.Core.Models;
+using MegaCrit.Sts2.Core.Nodes.Cards;
 using MegaCrit.Sts2.Core.Nodes.CommonUi;
 using MegaCrit.Sts2.Core.Random;
 using MegaCrit.Sts2.Core.Saves.Runs;
@@ -104,6 +106,67 @@ private static string GetUpgradeSuffix(CardModel card)
             }
         }
 
+        /// <summary>
+        ///     Applies BaseLib-compatible type text modifiers before the plaque LocString is formatted.
+        ///     在类型牌匾 LocString 格式化前应用与 BaseLib 兼容的类型文本修改器。
+        /// </summary>
+        internal sealed class TypeTextPatch : IPatchMethod
+        {
+            public static string PatchId => "ritsulib_card_capability_type_text";
+
+            public static string Description => "Apply BaseLib-compatible card type text modifiers";
+
+            public static bool IsCritical => false;
+
+            public static ModPatchTarget[] GetTargets()
+            {
+                return [new(typeof(NCard), "UpdateTypePlaque")];
+            }
+
+            [HarmonyAfter(Const.BaseLibHarmonyId)]
+            public static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions)
+            {
+                var code = instructions.ToList();
+                var applyMethod = AccessTools.Method(
+                    typeof(CardTypeTextHook),
+                    nameof(CardTypeTextHook.Apply));
+                if (applyMethod == null || code.Any(instruction => instruction.Calls(applyMethod)))
+                    return code;
+
+                var toLocStringMethod = AccessTools.Method(
+                    typeof(CardTypeExtensions),
+                    nameof(CardTypeExtensions.ToLocString));
+                var getFormattedTextMethod = AccessTools.Method(
+                    typeof(LocString),
+                    nameof(LocString.GetFormattedText));
+                var modelGetter = AccessTools.PropertyGetter(typeof(NCard), nameof(NCard.Model));
+                if (toLocStringMethod == null || getFormattedTextMethod == null || modelGetter == null)
+                    return code;
+
+                var toLocStringIndex = code.FindIndex(instruction => instruction.Calls(toLocStringMethod));
+                var getFormattedTextIndex = toLocStringIndex < 0
+                    ? -1
+                    : code.FindIndex(
+                        toLocStringIndex + 1,
+                        instruction => instruction.Calls(getFormattedTextMethod));
+                if (getFormattedTextIndex < 0)
+                {
+                    RitsuLibFramework.Logger.Warn(
+                        "[ModelCapabilities] Card type text patch did not find the expected LocString formatting site.");
+                    return code;
+                }
+
+                code.InsertRange(
+                    getFormattedTextIndex,
+                    [
+                        CodeInstruction.LoadArgument(0),
+                        new(OpCodes.Call, modelGetter),
+                        new(OpCodes.Call, applyMethod),
+                    ]);
+                return code;
+            }
+        }
+
         internal sealed class CardTypePatch : IPatchMethod
         {
             public static string PatchId => "ritsulib_card_capability_type";
diff --git a/src/RitsuLibFramework.PatcherSetup.cs b/src/RitsuLibFramework.PatcherSetup.cs
@@ -405,6 +405,7 @@ private static void RegisterLifecyclePatches()
             patcher.RegisterPatch<OrbModelCapabilityPatches.AfterOrbEvokedHookPatch>();
             patcher.RegisterPatch<CardModelCapabilityPatches.UpdateDynamicVarPreviewPatch>();
             patcher.RegisterPatch<CardModelCapabilityPatches.TitlePatch>();
+            patcher.RegisterPatch<CardModelCapabilityPatches.TypeTextPatch>();
             patcher.RegisterPatch<CardModelCapabilityPatches.CardTypePatch>();
             patcher.RegisterPatch<CardModelCapabilityPatches.CardRarityPatch>();
             patcher.RegisterPatch<CardModelCapabilityPatches.TargetTypePatch>();
diff --git a/src/RitsuLibFramework.cs b/src/RitsuLibFramework.cs
@@ -875,6 +875,15 @@ public static void RegisterCardOnPlayHookListener(ICardOnPlayHookListener listen
             CardOnPlayHook.RegisterGlobalListener(listener);
         }
 
+        /// <summary>
+        ///     Registers a process-wide BaseLib-compatible card type text modifier through the framework.
+        ///     通过框架注册进程级、与 BaseLib 兼容的卡牌类型文本修改器。
+        /// </summary>
+        public static void RegisterCardTypeTextModifier(ICardTypeTextModifier modifier)
+        {
+            CardTypeTextHook.RegisterGlobalModifier(modifier);
+        }
+
         /// <summary>
         ///     Resolves the current max-hand-size value for <paramref name="player" />.
         ///     解析 <paramref name="player" /> 当前的最大手牌数值。
