一、能力系统的整体架构与设计思想

在《杀戮尖塔2》的模组开发体系中，自定义能力（通常称为Buff或Debuff）是赋予卡牌、遗物、敌方单位个性化战斗逻辑的核心载体。无论是“每次攻击附加中毒”“回合结束恢复生命”还是“受到伤害时反射伤害”，这些复杂效果均统一继承自能力基类（在游戏框架中对应PowerModel抽象类）。理解这一设计，是掌握全部效果扩展的基石。

该抽象类并非仅仅为效果提供“存放数据”的容器，它同时承担着三项关键职责：

1. 状态管理：记录当前层数、来源实体、可用状态等元数据。
2. 事件响应：向游戏战斗系统暴露可覆写的生命周期钩子方法（如出牌后、回合结束时、受到伤害前等）。
3. 显示驱动：定义该效果在角色头顶、底部状态栏以及进阶说明框中的呈现方式。

因此，开发者在自定义能力时，本质上是在回答三个问题：这个效果是什么（类型与表现）、它如何被合并（叠加策略）、它在战斗的哪个时机做什么事（逻辑落点）。我们将逐层拆解。

二、基础实战：一个“打出牌叠甲并消散”的能力

我们从一个最常见的需求开始：设计一个“磨砺”类效果——当玩家打出任意一张牌后，获得等同于能力层数的格挡值，且在玩家回合结束时减少一层。完整代码如下（采用C#语言，基于《杀戮尖塔2》模组SDK上下文编写）：

public sealed class MyBlockOnPlayBuff : PowerModel
{
    // 1. 效果类型枚举：决定它被UI视为增益还是减益
    public override PowerType Type => PowerType.Buff;
    // 2. 叠层策略枚举：表示这是一个有数值的层数效果
    public override PowerStackType StackType => PowerStackType.Counter;
    // 3. 是否允许多个独立实例并存
    public override bool IsInstanced => false;
    // 4. 是否允许层数降低到负数
    public override bool AllowNegative => false;
    // 5. 鼠标悬停时显示额外提示（如关联“格挡”机制说明）
    protected override List<IHoverTip> ExtraHoverTips => 
        new List<IHoverTip> { HoverTipFactory.Static(StaticHoverTip.Block) };
    // 6. 核心逻辑：玩家打出牌后触发
    public override async Task AfterCardPlayed(PlayerChoiceContext context, CardPlay cardPlay)
    {
        // 仅响应我方单位打出的牌（根据Owner与牌所属者判断）
        if (cardPlay.Card.Owner.Creature != Owner) return;
        // 保护性检查：当层数小于等于0时，无意义则不处理
        if (Amount <= 0) return;
        // 播放能力闪动反馈，增强玩家视觉认知
        Flash();
        // 实际增加格挡值（Amount为当前能力层数）
        await CreatureCmd.GainBlock(Owner, Amount, ValueProp.Unpowered, null, fast: true);
    }
    // 7. 核心逻辑：回合结束时减少自身层数
    public override async Task AfterTurnEnd(PlayerChoiceContext choiceContext, CombatSide side)
    {
        // 仅在属主所处的回合结束时才减少（避免敌方回合误触发）
        if (side == Owner.Side)
        {
            await PowerCmd.Decrement(this); // 将层数减1
        }
    }
}

代码逻辑拆解：

• AfterCardPlayed方法接收两个参数：回合上下文（PlayerChoiceContext）与打牌动作（CardPlay）。通过cardPlay.Card.Owner.Creature可追溯实际打出卡牌的单位，这是判断逻辑归属的关键手段，尤其适合处理“敌方出牌也触发自身效果”等复杂场景。
• 异步延迟：所有动作返回Task，确保战斗状态机能够安全地串行处理（例如先加格挡，再结算格挡相关的其他反应）。
• 数值恒定：Amount代表当前层数。在设计持续N回合的效果时，务必注意在事件内直接读取Amount即可，因为减层操作发生在本回合所有动作结算之后。

三、深入理解核心属性：定义能力的“身份证”

在上面的代码中，我们使用了四个极为重要的重写属性。下面逐一剖析，这是区分“盲目复制代码”与“真正掌握框架”的关键分水岭。

3.1 PowerType：选择增益还是减益的立场

public enum PowerType
{
    None,    // 无特殊态度，不显示成Buff或Debuff图标
    Buff,    // 增益：矢量向上，通常为绿色/金色
    Debuff   // 减益：矢量向下，通常为红色/灰色
}

该枚举直接决定了状态的视觉风格，背后牵涉到游戏内颜色或图标形状的适配。更关键的是，部分事件系统会基于PowerType做过滤，例如“净化所有减益效果”的卡牌只会处理Debuff类型。因此正确标记类型是保证生态兼容性的必要条件。

3.2 PowerStackType：数值叠加还是状态标记

这是设计能力时最容易混乱的地方。

枚举值	适用场景	层数含义	典型示例
Counter	可量的数值型效果	表示强度或剩余回合数	中毒（每层掉1血）、力量（每层加伤）
Single	纯状态型效果	无层数概念，仅显示存在	具备“无法使用技能”的压制效果
None	少见底层指令	无特殊	保留

对于Counter类型，每次获得相同能力时，游戏主逻辑会自动调用合并策略（默认是层数累加）。而Single类型通常配合自定义合入回调（如覆写OnApply判断是否刷新持续时间）。

3.3 IsInstanced：单体实例的合流与分流

• 设为false（默认推荐）：当你再次获得该能力时，框架不会生成新实例，而是找到已有实例并执行层数增加或刷新操作。这保证了战斗界面清爽，且便于集中管理。
• 设为true：每次施加都创造独立逻辑对象。这适用于“多重护盾”或“多次触发奖励”等需要分别计算剩余次数的场景。但请务必注意，这增加了内存占用与逻辑复杂度，稍有不慎会导致状态显示错乱。

3.4 ExtraHoverTips：增强界面的可理解性

返回一个IHoverTip列表，它能让玩家鼠标悬停在状态图标上时看到额外说明。例如关联到“格挡”或“脆弱”的静态说明文本。对于自定义数值型效果，建议额外附加一个动态文本（如HoverTipFactory.Dynamic(() => $"{Amount}点伤害")），让玩家实时了解层数影响。

四、生命周期与事件钩子精讲

PowerModel最大的妙处在于事件系统的丰富程度。除了上文用到的AfterCardPlayed与AfterTurnEnd，常见的覆写钩子还包括（完整列表以SDK反编译为准，此处列核心）：

• Task OnGained(int amount)：当被施加或层数增加时触发，适合播放特定音效或派生子状态。
• Task BeforeAttacked(BattleContext context, AttackInfo attackInfo)：在受到攻击数值计算前触发，可修改伤害值或添加护盾。
• Task AfterAttacked(...)：结算攻击后触发（可写反伤、吸血）。
• Task OnLose(int amount)：层数被削减时触发，可用于“当层数归零时召唤怪物”等交互逻辑。
• Task AfterTurnStart(CombatSide side)：回合开始前触发（区别于AfterTurnEnd）。

提示：所有钩子方法名称均以“After”或“Before”开头，清晰表明调用时机。深入使用时，切勿在Before钩子中修改敌方目标列表等链表结构，否则会破坏迭代器，引发逻辑异常。

五、最佳实践：从简单到复杂的进阶设计思路

5.1 设计“残余回合”型状态的演化

许多新手会直接把Amount当作“剩余回合数”，每回合结束时减一。此方式正确且直观。但如果你需要实现“每回合开始前层数翻倍”的恶魔形态效果，则需要注意事件调用顺序：通常AfterTurnEnd的回调排在“清除负面状态”等系统逻辑之前。因此在翻倍逻辑中，需要注意是否应该优先清除“减少层数”的Debuff。

5.2 避免常见的数值错误

• 误用Owner：Owner指的是携带该能力的实体，而非能力来源者。能力来源者需单独在触发时从StackData中读取，务必区分，否则会出现“敌方施加的中毒，其伤害却计算自己力量”的致命BUG。
• 遗漏异步限制：在事件方法内请勿执行耗时阻塞操作（如文件IO）。一切战斗数据修改必须走游戏专用的控制命令（如CreatureCmd模块）。
• Flash()与视觉反馈：在每个显著效果（如扣血、上盾）前调用Flash()，这能有效提醒玩家该能力正在生效，避免“该触发但看不出变化”的困惑。

六、调试与验证

1. 日志输出：利用Log.Info在关键方法内打印Amount与context信息。SDK通常提供完整的基于回合的逻辑追踪器。
2. 增加低速演示：在模组的调试配置中，将战斗速度调低至0.5倍，观察BUFF图标旁的数字是否按预期逐回合递减。
3. 边界测试：尝试在法术格挡时（0点格挡空过）测试AfterCardPlayed是否会因为Amount为0而跳过，验证防御性判断的正确性。

七、结语

自定义能力是模组开发中最能展现创意的一环。掌握PowerModel的四个核心属性与事件钩子，你便具备了构建从小到大的复杂效果的能力。然而，真正的进阶比拼的是对战斗上下文的洞察——例如当“重击”触发“格挡”时，格挡的加值是否应该受到“易伤”的层数增益？这些细节通常需要结合社区数千小时的平衡经验。建议在完成基础能力后，尝试复刻游戏本体中你熟知的数个知名能力（如势不可挡、时间扭曲），直到你的代码与本体行为完全一致——这会极大提升你对战斗系统的把握能力。

现在，打开你的代码编辑器，去构建那个属于你的独一无二的能力吧。