[Feature] 为卡牌组件添加类似附魔的徽标外观

[FuYnAloft]

模块范围

Public API（公开 API）

动机 / 使用场景

希望卡牌组件可以有类似附魔的外观，即卡牌左上角徽标，有图标，支持显示数字。
最好支持类似能力的多参数，可以在图标的四个角都显示数字而不是像原版只能右下角显示一个。

如果有多个组件都有徽标，那么会按顺序从上往下依次放置。
兼容附魔的徽标，当有附魔徽标的时候，组件徽标需要下移一格。

方案设想

加个 IEnchanmentDisplayCardComponent 接口

支持声名 EnchantmentIconPath, EnchanmentDisplayAmount 等属性

替代方案

No response

其他补充

No response

[ritsukage-local-analyzer]

Warning

此分析由 AI 自动生成，仅供开发者参考，最终判断请以人工确认为准。如有疑问建议结合本地环境进一步复现确认。

摘要

这是一个 Public API 的 feature request：希望为卡牌模型组件添加类似原版附魔的徽标（badge）外观——卡牌左上角显示图标与数字，支持四角独立数值，多个组件徽标垂直堆叠，并与原版附魔徽标共存（向下偏移）。当前卡片组件能力系统（ICardDescriptionComponent、ICardGlowComponent 等）覆盖了描述、悬停提示、发光等抽象层面，但尚无任何视觉徽标/贴花渲染能力接口，因此该需求填补了一个明确的空白，建议接受为有效 feature。

重点结论

项目	内容
简单介绍	请求为 CardModel 的模型组件增加一个可选的 "徽标渲染" 能力接口，使组件能在卡牌左上角显示带图标和数字的徽标，类似原版附魔外观。
可能原因	当前 CardModelComponentCapabilityHost 仅将组件能力桥接到卡牌描述、悬停提示、发光判定——这些全是文本或抽象视觉反馈；卡牌表面的贴花/徽标渲染没有任何组件接口可挂载。
可能解决方案	在 CardModelComponentCapabilities.cs 中新增 ICardDisplayBadgeComponent 接口（而非报错拼写 IEnchanmentDisplayCardComponent），定义 IconPath、Amount（或四角 dict）、GetDisplayBadges(CardModel) 返回按 priority 排序的徽标列表；然后在卡牌 UI 渲染侧新增一个 Harmony patch 注入组件徽标节点。
需要补充	报错者仅给出零散接口名建议，未明确四角数值的数据结构、多组件排序规则、以及与附魔共存时的"下移一格"具体像素/布局定义。需在实现前与报错者确认接口契约细节。

展开详细分析、证据与验证

问题描述

期望行为

• 卡牌左上角显示类似附魔的徽标，含图标和数字。
• 支持一个图标在四个角各显示独立数值（而非原版仅右下角一个数字）。
• 多个组件带有 IEnchanmentDisplayCardComponent 能力时，徽标从上往下依次排列。
• 与原版附魔徽标共存时，组件徽标整体下移，避免重叠。

实际行为

• 当前卡片组件能力系统（Models/Capabilities/CardModelComponentCapabilities.cs）定义了三个接口：ICardDescriptionComponent（描述片段）、ICardHoverTipComponent（悬停提示）、ICardGlowComponent（手牌发光）。无任何视觉徽标相关接口。
• 现有的 ModEnchantmentTemplate（Scaffolding/Content/ModEnchantmentTemplate.cs）和 ExternalAssetOverrideRegistry 处理的是附魔自身的图标路径，与卡牌组件徽标无关。

复现步骤

Feature request，不适用。

环境与版本

不适用（feature request，无运行日志或版本号）。

日志、附件与原文摘录

无附加日志或截图。

详细分析依据

1. 现有组件能力体系：CardModelComponentCapabilities.cs:102-367 定义了 CardModelComponentCapabilityHost 内部类，通过 ModelComponentCapabilityHost.GetCapabilities<TCapability>(card) 遍历已附加组件并调用对应接口方法。该 host 已处理以下能力：

   • ICardDescriptionComponent → 卡牌描述文本注入
   • ICardHoverTipComponent → 悬停提示追加
   • ICardGlowComponent → 手牌金色/红色发光判定
   • IModelDynamicVarComponent → 动态变量更新（card 生命周期内）

2. 桥接层：CardModelComponentCapabilityPatches.cs 包含 10 个 Harmony patch，全部聚焦于描述渲染、hover tip、glow 判定、升级/降级/变形生命周期通知。无 UI Node/scene 层面的 patch —— 这意味着新增徽标能力需要：一个新的 Harmony patch 在卡牌视觉节点创建时注入徽标控件，以及一个新的 host 方法收集所有实现了 ICardDisplayBadgeComponent 的组件数据。

3. 现有 Badge/Enchantment 基础设施：

   • Scaffolding/Content/ModBadgeTemplate.cs：处理跑局结束后的成就徽章（Badge），与卡牌 UI 徽标不同。
   • Scaffolding/Content/ModEnchantmentTemplate.cs：继承自 EnchantmentModel，仅处理附魔图标路径覆盖，与卡牌组件无关。
   • Scaffolding/Content/Patches/BadgeOverridePatches.cs：处理 NBadge 节点图标覆盖和 Badge.Icon getter，为 UI 节点级别的 patch，可作为新增卡牌徽标 patch 的参考模式。

4. 能力 Capability 接口模式：现有接口命名惯例是 ICard + 功能名 + Component（如 ICardDescriptionComponent、ICardGlowComponent），接口定义放在 CardModelComponentCapabilities.cs，host dispatch 方法放在 CardModelComponentCapabilityHost 中。报错者建议的 IEnchanmentDisplayCardComponent 命名拼写有误（应为 Enchantment）且不符合现有惯例；建议命名为 ICardDisplayBadgeComponent 或 ICardBadgeComponent。

5. 实现所需工作量：

   • 在 CardModelComponentCapabilities.cs 中新增接口定义（ICardDisplayBadgeComponent），包含 IconPath、角标数值（可用 Dictionary<Corner, int> 或 int TopLeft / int TopRight / int BottomLeft / int BottomRight）以及排序优先级。
   • 在 CardModelComponentCapabilityHost 中添加 GetDisplayBadges(CardModel) 收集方法。
   • 在 CardModelComponentCapabilityPatches.cs 中新增一个 patch 挂载到卡牌视觉节点（类似 NBadge.Create 的 patch 模式），创建并布局徽标节点。
   • 处理与附魔徽标的共存逻辑（下移偏移量）。

详细验证建议

• 确认报错者期望的数据结构：四角数值是独立 int 还是统一 Amount？是否每个角可以独立隐藏？
• 确认多组件徽标的排序规则：是 ComponentId 排序、注册顺序、还是需要显式的 Order/Priority 属性？
• 确认与原版附魔徽标的共存偏移量：像素值 or 相对布局？
• 确认徽标图标尺寸、字体大小是否有约束，或完全由组件提供方自行决定？
• 在 CardModelComponentCapabilities.cs:80 附近新增 ICardDisplayBadgeComponent 接口，遵循现有命名模式。
• 参考 BadgeOverridePatches.cs:251-293 的 NBadgeCreateIconPatch 实现卡牌徽标 UI 注入。

风险与未决

• 报错者提议的接口名 IEnchanmentDisplayCardComponent 拼写错误且不符合库的命名惯例，实现时需修正。
• 缺乏关于四角数值数据结构的完整规范——若接口设计不当，后续可能需要 breaking change 来调整。
• UI 注入点尚未确定（原版卡牌视觉节点结构未知），需要在游戏运行时调查卡牌左上角渲染节点的 Godot scene tree 结构。
• 报错者标记了 area/api 但未提及 area/ui —— 实际上该 feature 的核心难点在 UI 渲染注入而非 API 接口定义。

---

English translation

Summary

This is a Public API feature request: add enchantment-like badge overlays to card model components — an icon with a number displayed in the top-left corner of the card, with independent numbers possible in all four corners. Multiple component badges should stack vertically, shifting down when a vanilla enchantment badge is present. The current card component capability system (ICardDescriptionComponent, ICardGlowComponent, etc.) covers description, hover tips, and glow — but there is no interface for visual badge/decal rendering. This request fills a clear gap and should be accepted as a valid feature.

Key Takeaways

Item	Detail
Overview	Request for an optional "badge rendering" capability interface on CardModel components, allowing them to display an icon-with-number badge in the card's top-left corner, similar to vanilla enchantment visuals.
Likely cause	CardModelComponentCapabilityHost currently only bridges component capabilities to card descriptions, hover tips, and glow predicates — all text or abstract visual feedback. There is no component interface to hook into card surface decal/badge rendering.
Suggested resolution	Add an ICardDisplayBadgeComponent interface (not the misspelled IEnchanmentDisplayCardComponent) in CardModelComponentCapabilities.cs, defining IconPath, amount values (or a four-corner dictionary), and a GetDisplayBadges(CardModel) method returning a priority-ordered badge list. Then add a Harmony patch on the card UI side to inject component badge nodes.
Info needed	The reporter only provided scattered interface name suggestions without specifying the four-corner data structure, multi-badge ordering rules, or the exact pixel/layout offset for co-existing with enchantment badges. Interface contract details must be confirmed before implementation.

Expand detailed analysis, evidence, and verification

Problem Description

Expected behavior

• A badge similar to enchantment visuals appears in the card's top-left corner, with an icon and a number.
• Support for independent numbers in all four corners of a single icon (unlike vanilla, which only shows one number in the bottom-right).
• When multiple components have IEnchanmentDisplayCardComponent, their badges stack vertically from top to bottom.
• When a vanilla enchantment badge is present, component badges shift downward to avoid overlap.

Actual behavior

• The current card component capability system (Models/Capabilities/CardModelComponentCapabilities.cs) defines three interfaces: ICardDescriptionComponent (description fragments), ICardHoverTipComponent (hover tips), ICardGlowComponent (hand glow). There is no visual badge-related interface.
• The existing ModEnchantmentTemplate (Scaffolding/Content/ModEnchantmentTemplate.cs) and ExternalAssetOverrideRegistry handle enchantment icon paths for the enchantment model itself, unrelated to card component badges.

Reproduction steps

Feature request — not applicable.

Environment & Version

Not applicable (feature request with no runtime logs or version info).

Logs, Attachments & Excerpts

No logs or screenshots attached.

Detailed Analysis

1. Existing component capability system: CardModelComponentCapabilities.cs:102-367 defines CardModelComponentCapabilityHost, which iterates attached components via ModelComponentCapabilityHost.GetCapabilities<TCapability>(card) and dispatches to matching interface methods. Currently handled capabilities:

   • ICardDescriptionComponent → card description text injection
   • ICardHoverTipComponent → hover tip appending
   • ICardGlowComponent → gold/red hand glow
   • IModelDynamicVarComponent → dynamic var updates during card lifecycle

2. Bridge layer: CardModelComponentCapabilityPatches.cs contains 10 Harmony patches, all focused on description rendering, hover tips, glow predicates, and upgrade/downgrade/transform lifecycle notifications. No UI node/scene-level patch exists — meaning a new badge capability would require: a new Harmony patch injecting badge controls during card visual node creation, plus a new host method to collect data from all components implementing ICardDisplayBadgeComponent.

3. Existing Badge/Enchantment infrastructure:

   • Scaffolding/Content/ModBadgeTemplate.cs: handles post-run achievement badges (Badge), unrelated to card UI badges.
   • Scaffolding/Content/ModEnchantmentTemplate.cs: inherits from EnchantmentModel, handles enchantment icon path overrides only.
   • Scaffolding/Content/Patches/BadgeOverridePatches.cs: handles NBadge node icon overrides and Badge.Icon getter — a useful reference pattern for new card badge UI patches.

4. Capability interface naming convention: Existing interfaces follow ICard + <Feature> + Component (e.g., ICardDescriptionComponent, ICardGlowComponent). The reporter's suggested name IEnchanmentDisplayCardComponent is misspelled and doesn't follow conventions; ICardDisplayBadgeComponent or ICardBadgeComponent would be more appropriate.

5. Implementation scope estimate:

   • New interface definition in CardModelComponentCapabilities.cs (ICardDisplayBadgeComponent) with IconPath, corner values (e.g., Dictionary<Corner, int> or separate int TopLeft / TopRight / BottomLeft / BottomRight), and sort priority.
   • New GetDisplayBadges(CardModel) collection method in CardModelComponentCapabilityHost.
   • New patch in CardModelComponentCapabilityPatches.cs hooking into card visual nodes (following the NBadgeCreateIconPatch pattern) to create and lay out badge nodes.
   • Coexistence logic with vanilla enchantment badges (downward offset).

Verification Checklist

• Confirm expected data structure: independent int per corner or a single unified Amount? Can corners be individually hidden?
• Confirm multi-badge ordering: by ComponentId, registration order, or an explicit Order/Priority property?
• Confirm offset amount for enchantment coexistence: pixel value or relative layout?
• Confirm badge icon size and font size constraints, or whether they are fully provider-controlled.
• Add ICardDisplayBadgeComponent interface near CardModelComponentCapabilities.cs:80, following existing naming conventions.
• Reference BadgeOverridePatches.cs:251-293 (NBadgeCreateIconPatch) when implementing card badge UI injection.

Risks & Open Questions

• The reporter's suggested interface name IEnchanmentDisplayCardComponent is misspelled and non-conventional; should be corrected during implementation.
• No complete specification for the four-corner data structure — a poorly designed interface may require a breaking change later.
• The UI injection point is undetermined (vanilla card visual node structure unknown); requires runtime investigation of the Godot scene tree for card top-left rendering nodes.
• The reporter tagged area/api but not area/ui — the core difficulty of this feature is UI rendering injection, not the API interface definition.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#45 · 退出码 0 · 进程 206.05s
• deepseek-v4-pro · API 204767ms · 23 轮 · ↓60739 ↑6828 · 缓存读352512 写0 · $0.6507
• MCP available: management tools exposed to Claude.

[BAKAOLC]

是合理设计，但目前来说该功能仍然在设计期，相比之下有其他的 api 需要继续优化设计，因此这个目前可能会搁置几天
/r set p2