自定义药水开发实战：从属性配置到战斗回调

在卡牌构筑类游戏的模组开发中，药水系统是一个典型而完整的扩展点：它既涉及数据定义（稀有度、使用时机、目标类型、数值变量），又涉及行为实现（使用回调、效果结算），还要与游戏内的随机获取机制（药水池）打通。本文以“群体伤害药水”为案例，系统梳理自定义药水的开发范式，帮助读者建立可复用的开发思路，而非仅仅记住一段示例代码。

一、药水系统的整体设计思路

在动手写代码之前，先理解药水对象在整个游戏循环中的位置。一个药水通常包含两类信息：

1. 静态元数据：稀有度、使用时机、目标类型、数值变量等。它们决定了药水“是什么”以及“如何被系统识别和使用”。
2. 动态行为：玩家使用药水时触发的回调逻辑。它决定了药水“做了什么”。

这种“元数据 + 回调”的分层设计，使药水能够被统一地纳入随机掉落、界面展示与战斗结算流程，同时保留足够的扩展自由度。开发自定义药水时，本质上是继承一个药水基类，重写元数据属性，并实现使用回调。

二、核心属性逐项解析

2.1 稀有度（Rarity）

稀有度决定药水在随机药水池中的出现权重与归类。常见的枚举取值包括：

• None：无稀有度，通常用于特殊占位。
• Common：普通，出现频率较高。
• Uncommon：罕见，出现频率中等。
• Rare：稀有，出现频率较低。
• Event：事件专属，通常不进入常规随机池。
• Token：代币类，一般由特定机制生成而非随机获取。

在实现中，Common、Uncommon、Rare 三档药水会被纳入合适的药水池参与随机抽取，因此自定义药水若希望“自然出现”在游戏中，应优先选择这三档之一。案例中的群体伤害药水选择了 Rare，这是因为其效果强度较高，需要通过较低的出现概率来平衡游戏体验。稀有度的选择本质上是数值平衡的一部分，开发者应结合效果强度谨慎设定。

2.2 使用时机（Usage）

使用时机决定药水在哪些场景下可以被激活，其枚举取值与语义如下：

• None：无法使用，通常用于占位或内部标记。
• CombatOnly：仅能在战斗中使用。若玩家在非战斗场景，使用键会被禁用。
• AnyTime：任意时机可用，包括战斗外场景，例如恢复类或资源转换类药水。
• Automatic：不可由玩家主动触发，只能通过代码逻辑触发，例如“死亡时自动生效”的保底类药水。

这里有一个容易被忽视的细节：Automatic 并不意味着药水“随时自动使用”，而是强调它不响应玩家的主动操作，必须由其他系统调用。开发者在设计“被动型”药水时，应选择该值，并在合适的游戏事件中显式调用其使用逻辑，而不是期望系统自动感知。

案例中的群体伤害药水设置为 CombatOnly，因为伤害结算依赖于战斗上下文（敌人集合、伤害管线等），在非战斗场景使用既无意义也无法正确结算。

2.3 目标类型（TargetType）

目标类型描述药水的作用对象范围，常见取值包括单体目标、全体敌人、全体友方、自身等。案例中使用 TargetType.AllEnemies，表示对战斗中所有可命中敌人生效。

目标类型的意义不仅在于界面提示（例如拖拽指向），也影响使用回调中如何构造目标集合。开发者应在回调中根据目标类型正确筛选目标，避免出现“界面显示群体、逻辑只打单体”的不一致问题。

2.4 数值变量（CanonicalVars）

数值变量用于声明药水的可配置数值，使数值与逻辑解耦，便于平衡调整与界面展示。案例中通过 DamageVar(30m, ValueProp.Unpowered) 声明了一个基础值为 30 的伤害变量，其中 ValueProp.Unpowered 表示该数值不受增益类效果影响，属于“固定值”语义。

这种设计的价值在于：

• 数值集中声明，避免散落在回调中的魔法数字；
• 变量可被界面读取，用于在药水描述中动态展示数值；
• 通过属性标记控制数值是否受修正影响，保证结算语义清晰。

开发者应根据药水效果选择合适类型的变量，例如伤害、格挡、抽牌数等，并为每个变量明确其修正语义。

三、使用回调的实现要点

使用回调是药水的行为核心，其签名通常接收两个关键参数：玩家选择上下文与使用目标。前者用于承载交互过程中的状态与异步流程，后者表示玩家选定的目标（对于全体目标类型，可能为空或需要自行展开）。

案例中的实现思路可以抽象为三步：

1. 确定目标集合：对全体敌人类型，从战斗状态中取出所有可命中敌人。
2. 执行效果结算：调用伤害指令，传入上下文、目标集合、数值与修正属性等。
3. 异步处理：回调返回异步任务，确保结算流程可被正确等待与串联。

示意性代码如下：

public sealed class MyAoEPotion : PotionModel
{
    public override PotionRarity Rarity => PotionRarity.Rare;
    public override PotionUsage Usage => PotionUsage.CombatOnly;
    public override TargetType TargetType => TargetType.AllEnemies;
    protected override List<DynamicVar> CanonicalVars =>
        new DynamicVar[] { new DamageVar(30m, ValueProp.Unpowered) };
    protected override async Task OnUse(PlayerChoiceContext choiceContext, Creature? target)
    {
        await CreatureCmd.Damage(
            choiceContext,
            Owner.Creature.CombatState.HittableEnemies,
            DynamicVars.Damage.BaseValue,
            DynamicVars.Damage.Props,
            Owner.Creature,
            null);
    }
}

需要强调的是几处工程细节：

• 目标来源：不应硬编码单个目标，而应从战斗状态中获取“可命中敌人”集合，以正确处理已死亡、不可选中、隐身等边界情况。
• 数值来源：应从声明的数值变量中读取，而非在回调中写死，保证与界面展示一致。
• 异步正确性：伤害结算涉及动画与状态变更，必须使用 await 等待完成，避免出现“结算未完成即返回”的竞态问题。
• 来源归属：传入施加者信息，使伤害能够正确归因，从而触发相关的击杀统计、增益联动等逻辑。

四、注册到药水池

完成药水类定义后，还需要将其加入共享药水池，才能让游戏中的角色随机获取。注册的本质是向“可抽取药水集合”追加条目，通常包含药水类型与其稀有度信息的关联。

注册时应注意：

1. 时机：应在模组初始化阶段完成注册，确保药水池在构建时已包含自定义条目。
2. 稀有度一致性：注册信息中的稀有度应与药水类中声明的稀有度保持一致，否则可能出现“按某档抽取但实际展示另一档”的不一致。
3. 去重与幂等：避免重复注册导致同一药水被多次抽取或权重异常。
4. 兼容性：注册应尽量使用公开的扩展点，避免直接修改内部集合，以降低版本升级带来的破坏风险。

五、常见问题与最佳实践

• 药水不出现：优先检查是否完成注册、稀有度是否为可抽取档位、是否被错误设置为 Event 或 Token。
• 使用键灰色不可点：检查 Usage 是否与当前场景匹配，例如在非战斗场景使用 CombatOnly 药水会被禁用。
• 效果与描述不符：确认界面展示读取的数值变量与回调中使用的变量是同一来源。
• 结算异常或卡顿：检查回调是否正确异步等待，避免遗漏 await 导致流程提前返回。
• 平衡性失控：将数值集中到数值变量中，便于统一调整；稀有度与效果强度应同步评估。

六、小结

自定义药水的开发可以归纳为一条清晰的主线：继承基类 → 声明元数据（稀有度、使用时机、目标类型、数值变量）→ 实现使用回调 → 注册进药水池。理解每个属性背后的系统语义，比机械复制示例更重要。掌握这一范式后，开发者可以进一步扩展出治疗药水、增益药水、被动触发药水等变体，并在此基础上设计更复杂的组合效果，从而构建出稳定、可维护且平衡良好的药水体系。