卡牌游戏模组开发：自定义事件机制的设计与实现

在以卡牌构筑与局外成长为核心玩法的游戏中，“事件”是叙事与机制结合最紧密的内容形态：玩家偶遇一个情境，阅读描述，在若干选项中做出抉择，随后获得或承担后果。本篇以某款卡牌策略游戏的模组框架为例，完整拆解一个自定义事件的实现——它提供“获得一张自定义卡牌”与“获得一笔金币”两个选项，体量虽小，却覆盖了事件开发的全部关键环节。

一、为什么事件系统是模组开发的高性价比切入点

相比新增一张卡牌或一件遗物，自定义事件有几点天然优势：

• 接入成本低：事件通过统一的事件模型挂载到游戏流程中，不触碰核心战斗与结算逻辑，出错的影响范围可控；
• 表达能力强：一个事件可以同时调用发卡、发钱、给遗物等多种命令，组合出复杂交互；
• 迭代节奏快：文本驱动的结构决定了原型成本极低，改一段描述、换一组数值就能产出新玩法；
• 便于协作：文案、数值与逻辑在代码里天然分层，非程序背景的创作者也能参与设计。

二、事件模型总览：三个核心扩展点

自定义事件的第一步是继承事件基类 EventModel，它将一个事件拆解为三个各司其职的可覆写成员：

成员	职责	调用时机
CanonicalVars	声明事件的动态变量	页面渲染与文本解析时
IsAllowed(RunState)	校验事件出场资格	事件抽取时
GenerateInitialOptions()	生成初始选项列表	页面构建时

由此可以勾勒出事件在运行期的完整生命周期：

1. 事件被抽中时，框架调用 IsAllowed 校验资格，未通过则换下一个候选；
2. 页面渲染阶段，框架根据 CanonicalVars 声明的变量解析文本占位符，填充名称与数值；
3. 玩家点击某个选项，触发该选项绑定的异步回调；
4. 回调执行效果（加卡、给钱等），最后调用 SetEventFinished 结束事件并展示结果文本。

理解这条主线后，下面逐层展开每个环节。

三、CanonicalVars：声明动态变量

CanonicalVars 返回一个 List<DynamicVar>，职责是“声明”而非“计算”：把事件中会随状态变化、需要在界面上呈现的值集中登记。示例登记了两项：

• new StringVar("MyCustomCard", ModelDb.Card<MyCustomCard>().Title)：以 MyCustomCard 为键，值通过注册表查询获得。这里刻意不手写卡牌名称，而是复用卡牌定义中已本地化的标题，避免同一名称两处维护、改一处漏一处；
• new GoldVar(50)：声明一个金币变量，基础值为 50。

动态变量的价值体现在前后两端：

1. 前端呈现：事件文本可嵌入占位符，渲染时替换为变量当前值。数值调整只需修改变量声明，无需改正文案案；
2. 后端消费：回调中通过 base.DynamicVars.Gold.BaseValue 读取实际值来执行效果。声明与消费走同一份数据，保证“玩家看到的”与“实际发生的”一致，这是事件公平性在工程层面的保障。

四、IsAllowed：控制事件的出场资格

方法签名为 bool IsAllowed(RunState runState)，参数承载当前对局的完整状态。示例直接返回 true，即无条件进入事件池。实际开发中，这是做定向过滤的理想位置：

• 幕次限制：只在特定章节之后出现，避免前期数值冲击；
• 状态限制：仅当卡组中已有某张卡、或玩家持有某遗物时出现，用于设计“配合型”“回收型”事件；
• 频次限制：同一局内仅出现一次，防止重复体验。

一条工程经验：能用 IsAllowed 提前过滤的，就不要拖到回调里再判断。前者让不该出现的事件根本不出现；后者会让玩家面对一个“点了没反应”的选项，无论体验还是调试成本都更高。

五、GenerateInitialOptions：生成选项列表

这是事件的核心回调，返回 List<EventOption>，列表中每个元素对应界面上的一个按钮。构造一个 EventOption 需要三要素：

1. 事件本体：传入 this 作为 Owner，回调执行时可通过 base.Owner 访问事件与对局上下文；
2. 触发回调：一个返回 Task 的异步委托，玩家点击选项后执行；传入 null 则该选项显示为不可触发状态；
3. 本地化键：通过 InitialOptionKey("MEDITATION") 构建选项标题的查找键。该方法按既定规则拼接出“事件标识 + 选项标识”形式的键名，既保证全局唯一，也让一个事件的所有文本聚拢在同一命名空间下，便于批量维护与翻译。

此外，选项还可以关联一件遗物，让按钮直接显示该遗物的图标。做“获得或失去某遗物”类事件时，这种直观提示能显著降低玩家的理解成本。

值得注意的是，示例中键名 LEAVE 对应的回调实际是发放金币——“离开”并不等于“什么都不做”。结合叙事，完全可以让告别也带着收益或代价，这正是事件设计的表达空间。

六、编写回调：效果的异步落地

选项被点击后，框架调用绑定的异步方法。两个回调分别演示了“涉及异步流程”与“纯同步”两种范式。

ActMeditation 的执行分四步：

CardModel card = base.Owner.RunState.CreateCard<MyCustomCard>(base.Owner);

通过运行状态上的工厂方法创建卡牌实例。优先使用工厂而非手动构造，能让卡牌从一开始就纳入对局状态的管理体系，获得统一的归属与追踪。

CardCmd.PreviewCardPileAdd(await CardPileCmd.Add(card, PileType.Deck));

CardPileCmd.Add 将卡牌放入指定牌堆（此处为玩家卡组）。该操作可能伴随动画等异步流程，因此用 await 等待其真正完成，再把结果交给 CardCmd.PreviewCardPileAdd 做可视化预览——让玩家清楚看到“加了什么卡、加到了哪里”，结算的反馈感是事件体验的重要组成部分。

SetEventFinished(L10NLookup("MY_CUSTOM_EVENT.pages.MEDITATION.description"));

最后收尾：退出事件界面，并展示结果描述文本。

ActRecharge 则是纯同步逻辑的写法：发放的金币数量读取自事件声明的动态变量，随后同样调用 SetEventFinished，由于没有任何异步步骤，直接返回 Task.CompletedTask 即可。两个回调统一采用 async Task 签名的好处是：调用方无需区分同步与异步，未来给同步逻辑升级为异步（例如给发钱增加动画）时也不必修改签名。

七、本地化：L10NLookup 与动态文本解析

L10NLookup 是通用的本地化查询方法：按当前语言查找文本，返回 LocString。它返回的不是一段静态字符串，而是携带模型上下文的“可解析字符串”——文本中的占位符由所属的 AbstractModel（此处即事件自身）提供动态变量，渲染时替换为实际值。事件描述里写“获得一张 [MyCustomCard]”，玩家最终看到的就是带具体卡牌名称的完整句子。

键的组织建议从一开始就形成规范：

• 事件描述、每个选项的标题、每个选项的结果文本，统一挂在 事件名.pages.选项名.description 这样的层级之下；
• 选项标题键交给 InitialOptionKey 生成，结果文本键与之保持命名对称；
• 每个键都配套默认语言的翻译文件——多语言环境下，缺失键是高频事故源。

八、完整实现示例

public class MyCustomEvent : EventModel
{
    // 1. 声明动态变量：卡牌名称与金币数量
    protected override List<DynamicVar> CanonicalVars =>
    [
        new StringVar("MyCustomCard", ModelDb.Card<MyCustomCard>().Title),
        new GoldVar(50)
    ];
    // 2. 出场资格：返回 true 表示任意对局中均可出现
    public override bool IsAllowed(RunState runState) => true;
    // 3. 生成初始选项列表
    protected override List<EventOption> GenerateInitialOptions()
    {
        return
        [
            new EventOption(this, ActMeditation, InitialOptionKey("MEDITATION")),
            new EventOption(this, ActRecharge,  InitialOptionKey("LEAVE"))
        ];
    }
    // 选项一：将一张自定义卡牌加入玩家卡组
    private async Task ActMeditation()
    {
        // 在对局状态中创建卡牌实例
        CardModel card = base.Owner.RunState.CreateCard<MyCustomCard>(base.Owner);
        // 加入卡组并等待完成，随后向玩家展示预览
        CardCmd.PreviewCardPileAdd(
            await CardPileCmd.Add(card, PileType.Deck));
        // 结束事件并展示结果文本
        SetEventFinished(L10NLookup("MY_CUSTOM_EVENT.pages.MEDITATION.description"));
    }
    // 选项二：给予玩家金币（纯同步逻辑）
    private Task ActRecharge()
    {
        PlayerCmd.GainGold(base.DynamicVars.Gold.BaseValue, base.Owner);
        SetEventFinished(L10NLookup("MY_CUSTOM_EVENT.pages.LEAVE.description"));
        return Task.CompletedTask;
    }
}

整体结构十分简洁：数据在头部集中声明，交互在中间统一组织，效果在回调中按需落地。

九、设计实践与常见问题

1. 默认提供退出路径：除非有强制发生的叙事理由，事件至少保留一个低风险选项，尊重玩家的选择权；
2. 数值全部变量化：金币、卡牌数量、增减幅度都应通过 DynamicVar 声明，方便平衡性调整并与展示文本联动；
3. 回调保持轻量且幂等：回调运行在交互关键路径上，不要塞入长耗时操作；关键结算应确保只执行一次，防止极端情况下重复触发造成超发；
4. 效果落地后必须收尾：忘记调用 SetEventFinished 会导致事件界面无法关闭，这是新手最常见的问题之一；
5. 结果文本如实描述：结算描述与实际效果不一致，比没有描述更伤害玩家信任。

十、小结

自定义事件的骨架可以浓缩为一句话：用 CanonicalVars 声明数据，用 IsAllowed 控制出场，用 GenerateInitialOptions 组织交互，用异步回调落地效果，最后用 SetEventFinished 与本地化体系收束体验。数据、规则、交互、反馈四个层次泾渭分明，正是事件系统能以低成本承载复杂创意的原因。

掌握这套范式后，可以进一步尝试多阶段事件（选项触发后进入下一页面而非直接结束）、条件分歧文本、与卡组状态联动的动态事件等进阶玩法——它们都建立在本篇拆解的同一套基础设施之上。