卡牌游戏模组开发：自定义卡牌模型设计详解

一、从抽象基类开始：统一卡牌的“出生方式”

在卡牌构筑类游戏中，模组系统最常见的扩展点就是自定义卡牌。无论具体框架如何实现，几乎都会采用同一个设计范式：提供一张卡牌模型抽象基类（下文以 CardModel 指代），官方卡牌与模组卡牌都继承自它。

这样设计的价值至少有三点：

1. 元数据强约束：基类通过构造函数强制子类在实例化时声明关键元数据（耗能、类型、稀有度、目标），避免出现“字段忘了赋值”的半初始化卡牌，把错误暴露在编译期而非运行期。
2. 统一生命周期：框架可以在基类中统一实现打出流程、费用结算、存档序列化等公共逻辑，子类只需专注效果本身。
3. 便于框架识别与注册：模组加载器可以通过反射扫描基类的派生类型，批量完成卡牌注册，无需模组作者手工维护注册表。

理解了这一点，构造函数的参数设计就不再是“五个孤立的参数”，而是框架与模组作者之间的一份契约。

二、构造函数：五个参数背后的契约

一段典型的基类构造函数如下（以 C# 风格示意）：

protected CardModel(int canonicalEnergyCost,
                    CardType type,
                    CardRarity rarity,
                    TargetType targetType,
                    bool shouldShowInCardLibrary = true)
{
    CanonicalEnergyCost     = canonicalEnergyCost;
    Type                    = type;
    Rarity                  = rarity;
    TargetType              = targetType;
    ShouldShowInCardLibrary = shouldShowInCardLibrary;
}

1. canonicalEnergyCost：基础耗能是“锚点”，不是“最终值”

第一个参数会被赋给 CanonicalEnergyCost 属性，并用于初始化 EnergyCost——也就是卡牌最终显示并实际扣除的耗能。

为什么要把“基础耗能”和“实际耗能”分成两个属性？因为对局中的耗能是高度动态的：

• 卡牌升级后费用可能变化；
• 局内获得的减费效果（例如“本回合首次打出某类牌费用归零”）会临时修改费用；
• 某些负面效果会让特定类型的卡牌额外加费。

如果只用一个字段存耗能，这些修正会互相覆盖、难以回滚。正确的心智模型是：

EnergyCost = CanonicalEnergyCost + Σ(费用修正)   （并按规则截断，例如不低于 0）

CanonicalEnergyCost 是恒定锚点，所有临时修正都作用在 EnergyCost 上，效果移除时重新计算即可干净还原。这也是 “canonical”（基准值）这个命名想传达的语义。

2. shouldShowInCardLibrary：容易被忽略的细节

最后一个布尔参数控制这张卡是否出现在卡牌图鉴中，默认值为 true。可选参数语法让大多数正常获取的卡牌无需显式传参，而代币、事件奖励等特殊卡牌只需多传一个 false，即可避免污染图鉴。这是“让常用路径最短”的 API 设计技巧。

三、卡牌类型：同时驱动表现层与规则层

类型用一个枚举描述，常见形态如下：

public enum CardType
{
    None,    // 无
    Attack,  // 攻击牌
    Skill,   // 技能牌
    Power,   // 效果牌
    Status,  // 状态牌
    Curse,   // 诅咒牌
    Quest    // 任务牌
}

表现层：类型最直观的作用是决定卡牌肖像框的样式——攻击牌、技能牌、效果牌在卡面上有不同的框体与配色，玩家扫一眼即可完成分类。

规则层：类型更重要的作用是作为规则系统的索引。成熟的卡牌游戏充满“每逢打出一张攻击牌……”“技能牌不受某类反制影响……”这类联动条件，这些判断都依赖 Type 字段。保留 None 成员同样有意义：它既能充当占位，也可用于抽象中间基类——暂时不参与类型判定的卡牌可先用 None 挂起。

实践建议：选择类型时不要只看“这张牌做什么”，还要看“希望哪些联动效果响应它”。一张造成伤害的牌未必必须是攻击牌——如果不希望它触发“打出攻击牌”类增益，选技能牌反而更符合设计意图。

四、稀有度：一枚枚举，串起整个经济系统

稀有度枚举通常包含两个层次：

public enum CardRarity
{
    None,      // 无
    Basic,     // 基础（初始套牌）
    Common,    // 普通
    Uncommon,  // 罕见
    Rare,      // 稀有
    // —— 以下为不进入随机卡池的特殊类别 ——
    Event,     // 事件
    Token,     // 代币
    Status,    // 状态
    Curse,     // 诅咒
    Quest      // 任务
}

（部分框架还会在稀有层级之上增设更高的特殊稀有度，思路一致，不再展开。）

1. 视觉层：边框样式

与类型决定肖像框类似，稀有度决定卡牌边框——普通、罕见、稀有在卡面上有明显的视觉区分，这是玩家感知卡牌价值的最快通道。

2. 规则层：卡池、定价与转化

普通/罕见/稀有三个层级构成“可随机获取”的核心池：

• 战斗内投放：战斗奖励按稀有度加权抽取，三个层级各配一个权重，具体数值由设计目标决定；
• 商店定价：稀有度越高，商人处的基础售价越高；
• 卡牌转化：卡牌被“变形/转化”为新卡时，通常从相同或相近稀有度的池子中抽取，避免玩家借转化机制无限套利。

3. 特殊类别：不进卡池，走条件获取

事件/代币/状态/诅咒/任务这类稀有度的共同点是：不会出现在任何随机卡池中，只能通过特定条件进入玩家卡组：

• 代币：由其他卡牌在战斗中临时生成，典型如“打出某张牌时自动将若干张临时攻击代币加入手牌”，代币本身不可被选入卡组，战斗结束即失效；
• 任务：作为任务凭证存在，例如先获得一张寻宝图式的任务卡，满足条件后再兑换成奖励；
• 状态/诅咒：负面牌，通常由敌人、事件或自身效果塞进卡组；
• 事件：由特定剧情事件发放。

对模组作者而言，要点在于：稀有度不是“强弱标签”，而是驱动投放与经济系统的索引。为自定义卡牌选定稀有度时，要同时回答三个问题：它应出现在哪个池子里？商人类 NPC 应卖多少钱？它被转化时会变成什么级别的卡？

五、目标类型：打出前的“目标解析”流程

目标类型决定卡牌打出时对哪些单位生效：

public enum TargetType
{
    None,               // 无（不可指定目标）
    Self,               // 出牌者自身
    AnyEnemy,           // 任意一个敌人
    AllEnemies,         // 所有敌人
    RandomEnemy,        // 随机一个敌人
    AnyPlayer,          // 任意玩家（多人场景）
    AnyAlly,            // 任意盟友
    AllAllies,          // 所有盟友
    TargetedNoCreature  // 非生物目标
}

1. 一张目标牌的完整打出链路

框架通常要经过三步：

1. 合法性校验：当前是否还存在合法目标？例如目标为 AnyAlly 的卡，若所有盟友均已阵亡，这张牌应被置灰、无法打出，而不是拖出去后才提示失败；
2. 目标高亮与选择：界面高亮可选目标，等待玩家指定；AllEnemies、AllAllies、Self 等群体或自身目标则跳过选择直接结算；
3. 结算：将目标集合交给卡牌效果逻辑执行。

模组作者要特别注意第一步：目标校验发生在“能否打出”的层面，而不是“打出后是否空转”。如果自定义卡依赖某个特殊目标的存在，务必让框架能在出牌前判定其可用性。

2. 盟友语义与多人目标

AnyAlly/AllAllies 中的“盟友”，指非自身的存活友军单位。这一语义区分了两类牌的本质：Self 是“作用于自己”，AnyAlly 是“作用于别人”——治疗队友、为队友附加增益的牌必须用后者。AnyPlayer 则暗示框架为多人对局或协作场景预留了扩展空间。

3. TargetedNoCreature：目标不必是“单位”

一个容易被忽视的成员是 TargetedNoCreature：目标既非敌人也非友军，而是场景中的非生物实体——例如某些交互型道具或剧情物品，其作用对象是场景中的商人、物件等。它的设计意义在于：把“与场景交互”也纳入统一的出牌目标系统，复用同一套选择、高亮与校验逻辑，而不是为交互另起炉灶。

此外，RandomEnemy 这类随机目标要留意结算时机：目标在结算瞬间才确定，若模组需要回放或联机同步，随机数种子的管理也应纳入考虑。

六、一个最小可用的自定义卡牌

把上述要素拼起来，一张自定义卡牌的骨架通常如下：

public sealed class SampleStrike : CardModel
{
    public SampleStrike() : base(
        canonicalEnergyCost: 1,
        type:       CardType.Attack,
        rarity:     CardRarity.Common,
        targetType: TargetType.AnyEnemy)
        // shouldShowInCardLibrary 使用默认值 true
    {
        // 名称、描述、升级分支、效果逻辑在此初始化
    }
}

几行元数据声明，就完成了这张卡在图鉴、卡池、商店与战斗目标系统中的全部“身份登记”，剩下的工作只有编写效果。

七、小结

自定义卡牌的本质，是用一组结构化元数据向框架描述“我是谁”：

• 基础耗能与实际耗能分离，让费用修正可叠加、可回滚；
• 类型同时驱动视觉框体与联动规则；
• 稀有度串联卡池投放、商店定价与转化逻辑，并区分“可随机获取”与“条件获取”两类卡牌；
• 目标类型定义了从校验、选择到结算的完整出牌链路，覆盖单体、群体、自身、盟友乃至非生物目标。

吃透这四个维度的语义之后，再复杂的自定义卡牌，也只是在这套坐标系上做填空题；后续的进阶话题——效果逻辑、升级分支与本地化——都将建立在这一模型之上。