卡牌与效果

卡面、实例与实体

引擎区分三个层次：

层次	身份	用途
CardDef	DefId / card_id	不可变卡面定义
CardInstance	CardInstId	手牌、牌库和武装区中的具体牌
Unit	UnitId	战场上的单位或总部实体

一张牌跨手牌和牌库移动时通常保留 CardInstId；部署后产生战场实体。复制、生成、转化、 回手和洗入牌库必须按各自卡文明确决定保留实例还是创建定义副本。

声明式 DSL

大多数卡牌效果位于 data/effects/*.json。常用能力包括：

• 目标选择、过滤、数量与目标绑定；
• 伤害、治疗、攻防与费用修改；
• 抽牌、弃牌、跨区移动和生成；
• 关键词授予、规则授予、光环与临时覆盖；
• 条件、序列、抉择、延迟与按事件数值计算；
• 部署、亡计、攻击、回合开始/结束等监听器。

可表达的效果优先留在数据中，便于严格验证、DIY 复用和逐卡审计。

Typed native rule

少数跨区域或改写通用规则的能力通过 native_rules 登记为带类型数据，例如：

• 首张牌费用乘区；
• 毁灭效果额外执行次数；
• HQ 获得防御改为伤害；
• 随机候选偏置；
• 效果伤害减免或增幅；
• 前线 HQ 防御下限。

它们由通用消费点解释，不以卡牌 ID 硬编码。loader 会验证参数范围、重复条目与通道组合。

Real DSL Script

只有 DSL 无法完整表达、且已存在明确行为依据的复杂效果才使用已注册 Script。Script 必须：

• 在注册表中具名；
• 参数严格匹配；
• 走主管线的费用、事件、实例和随机接口；
• 有端到端行为测试；
• 不以空函数、吞错或“成功但不做事”占位。

Suppress 生命周期

Suppress 按阶段处理自身回调、清理前观察者、文本/静态规则撤销、数值回落、清理后观察者 和隐蔽揭示。关键词按策略矩阵处理：有的全来源清除，有的仅清自身来源并由外部 giver 重算，也有的保留或走专用拆链。多 giver 以来源精确去重，宿主离场或被压制时相应撤销。

严格可执行性

加载成功不等于行为可执行。生产 Catalog 在返回前会用主管线的可执行性判定检查每个效果 槽；任何未知结构、未注册 Script 或不支持组合都会拒绝整个卡池。