定义与运行实例

⚡

Guide

分清可复用的内容定义与实时战斗实例，避免把运行时变化误当成对创作资产的修改

从创作定义生成战斗状态

上图说明了 GCS 的数据边界：Game Card Editor 保存可复用的内容定义，启动 Encounter 时，运行时根据这些定义创建本场战斗的单位、卡牌、状态和牌堆，战斗中的 HP、费用、层数与卡牌位置只属于当前实例，不会回写创作资产

单位定义与单位状态

内容	保存的数据	生命周期
GamePlayerUnit	名称、基础 HP、能量表现、起始卡组、Prefab 与美术	可复用的项目资产
GameEnemyUnit	名称、HP 范围、Tier、Prefab、Intent 与 Behavior	可复用的项目资产
UnitState	当前/最大 HP、护甲、队伍、存活状态、状态层数与活动 Hook	当前战斗
EnemyUnitState	UnitState 的全部数据，以及当前 Intent 和 Pattern 进度	当前战斗

敌人进入战斗时会从定义的 HP 闭区间中确定起始值，此后在 Inspector 中修改原始 GameEnemyUnit，不会更新已经创建的 EnemyUnitState

卡牌定义与卡牌实例

内容	保存的数据	使用位置
GameCard	名称、描述、基础费用、类型、稀有度、Target、美术与 Behavior	内容创作、数据库查询、卡组配置
CardInstance	实例 ID、基础卡牌引用、升级状态与实例费用变化	手牌、抽牌堆、弃牌堆、消耗堆
Active Card	基础卡或当前升级变体	卡面显示与实际结算
Effective Cost	基础费用、Run 修正、临时规则与费用 Hook 的最终结果	出牌检查与战斗 UI

提示

两张 Strike 可以共用同一个 GameCard，但它们在牌堆中是两个独立的 CardInstance，其中一张升级或获得临时费用变化时，另一张不会受到影响

运行时操作应传入实例；内容浏览、卡组配置和数据库查找使用定义，完整牌堆规则见卡牌与牌堆生命周期

状态定义与单位层数

GameStatus 保存名称、说明、图标、叠层规则、上限、衰减方式和 Behavior，单位进入战斗后，UnitState 只记录该单位当前持有哪些状态、各有多少层，以及已知的施加者，因此，修改 GameStatus.MaxStacks 会影响之后的状态结算，但直接改动某个单位身上的层数必须通过运行时接口完成，状态施加、衰减和过期规则见状态生命周期

GameDeck、Master Deck 与战斗牌堆

这三类数据分别服务创作配置、跨战斗进度与当前战斗

层级	用途
GameDeck	配置玩家起始卡组或 Encounter 奖励池
Run Master Deck	在同一局 Run 的多场战斗之间保存卡牌、升级状态与费用变化
战斗牌堆	保存当前战斗中的 CardInstance 及其位置顺序

新战斗会根据 Run Master Deck 或玩家的 Starting Deck 创建牌堆，战斗开始后修改 Master Deck，不会追溯改变已经生成的牌堆

选择正确的数据层级

需求	应修改的对象
调整以后创建的所有 Strike 的基础费用	GameCard 定义
调整当前战斗中某一张 Strike 的费用	该 CardInstance 的受支持费用规则
调整敌人的创作 HP 范围	GameEnemyUnit 定义
改变当前敌人的 HP	通过 GCSApi 或 Controller 修改 EnemyUnitState
改变状态的叠层或衰减规则	GameStatus 定义
改变某个单位当前的状态层数	通过状态 API 或 FlowGraph 节点修改
调整以后开始的 Run 卡组	Master Deck
移动当前战斗中的卡牌	战斗牌堆中的 CardInstance

Play Mode 中的实时数据应在 Game Card Monitor 中检查，Inspector 显示的是创作定义，不能代表已经创建的战斗实例

安全读取与修改

项目代码优先使用 GCSApi 的具名方法：

• 使用 Player()、AliveEnemies()、Hand()、StatusesOn() 等方法读取当前状态

• 使用 DealDamage()、GainArmor()、ApplyStatus()、MoveCardToPile() 等方法提交修改

• 自定义节点通过 ctx.Controller 修改状态

提示

这些入口会执行对应的 Hook、边界检查、事件通知和 Monitor 记录，直接修改实时对象的字段或集合，可能得到暂时正确的数值，却会让其他系统失去同步依据

完整代码入口见 API 使用指南，可用成员见 API 参考