概览

🧭

Guide

GameCardSystem (GCS) 是 TinyGiants 面向 Unity 研发的可视化卡牌肉鸽战斗框架，覆盖从内容创作到运行时的完整链路。系统基于 ScriptableObject 的 Workbench 模式，支持以全可视化的方式创作卡牌与战斗内容；内置的 FlowGraph 可视化流图体系，允许开发者在无需编写任何代码的情况下实现各类经典卡牌机制的效果。此外，框架还提供了完善的底层 API，以便你对运行时进行深度扩展

上图呈现了 GCS 卡牌肉鸽框架的完整可视化构筑体系，Game Card Editor 定义卡牌与战斗内容，FlowGraph Editor 把玩法规则编排为可以执行的 Behavior，Play Mode 运行战斗，Game Card Monitor 核对结果并定位问题，四个环节围绕同一份内容和同一套运行时首尾相连，一项机制可以从资产定义一直追踪到实机表现，再带着运行记录回到原处继续修改

一条贯穿创作、运行与接入的工作链路

实际项目从场景初始化进入这条链路，运行对象与内容数据库就绪后，Game Card Editor 中的定义和 FlowGraph 规则会交给 Battle Runtime 执行，Game Card Monitor 再把状态与执行记录带回对应的内容和 Behavior，HUD、地图、任务、存档及其他项目系统则通过 GCSApi 与 Events 连接同一场战斗

上图把内容创作、行为编排、战斗运行、结果诊断和项目接入连成一条可以反复迭代的工作流，编辑器负责建立内容与规则，运行时给出结果，Monitor 负责回溯，API 与事件负责把结果交给项目的其余部分，这条工作流已经覆盖的能力与规模集中在下表

能力范围	核心规模	对项目的直接价值
可视化内容创作	6 种 Game Card Editor 模式	在同一窗口创建卡牌、卡组、玩家、敌人、状态与遭遇战
可视化玩法编排	147 个节点、103 个经典机制配方	无需为每张卡牌、状态或敌人单独编写脚本
运行时与项目接入	147 个 GCSApi public 成员、43 个内置事件	从自定义 UI 和项目代码读取、控制并扩展战斗
Play Mode 诊断	7 个 Game Card Monitor 页签	在 Play Mode 中核对实时状态、等待来源、Flow 执行摘要与事件历史
随包成品	12 场可运行战斗、80 张卡牌、16 个敌人、30 个状态	直接体验完整结果，再回到源资产拆解实现方式

从场景骨架开始建立战斗内容

打开 Game Card System 并点击 Initialize System，GCS 会在当前场景中创建或复用控制器核心 GameCardManager，挂接战斗引导器 GameCardEncounterBootstrap，补齐战场、手牌、Canvas HUD 等运行对象与界面层级，并注册随包提供的六类预设数据库，下面的面板状态就是内容创作可以开始的明确标志

面板中的 Manager、六类数据库与 Bootstrap 全部就绪后，System Information 会同时显示 Unity 版本、编辑器平台、脚本后端和渲染管线支持状态，战斗场景设置与战斗启动分别说明这些对象的职责和启动关系，场景骨架确认无误后，从 Editor & Monitor 打开 Game Card Editor，即可在同一窗口切换六种 Workbench 模式

六种 Workbench 模式共用同一套三栏界面，左侧 List 管理数据库与条目，中间 Inspector 编辑当前定义，右侧 Preview 核对玩家可见结果并通过 Used By 追踪引用，拖动排序、跨数据库复制粘贴、行内重命名、Undo/Redo、智能下拉、引用选择器与 Validation 也会贯穿全部模式，因此完成一种内容后可以沿引用关系直接进入下一种内容

内容	在 Game Card Editor 中定义什么	进入战斗后负责什么
卡牌	名称、描述、费用、类型、稀有度、Target、标签、关键词、Upgrade、美术与 Behavior	玩家可以打出的行动，以及抽取、保留、消耗、升级和费用变化规则
卡组	卡牌条目与副本数量	初始构筑、Run 中的 Master Deck 与遭遇战奖励池
玩家单位	HP、能量、初始卡组、Prefab、图标与职业标签	玩家侧单位状态、起始资源和战斗表现
敌人	HP 范围、层级、Prefab、Intent 与 Behavior	预告并执行 Normal、Elite、Boss 或召唤物的行动
状态	Buff 或 Debuff 身份、叠加、上限、衰减、图标与 Behavior	持续效果、计数器、规则修改、触发器与回合时机
遭遇战	玩家、敌人阵容、奖励卡组、Intent 显示与 Battle Rules	把已有内容装配成可以启动、结算胜负并提供奖励的战斗

这六类内容会把名称、数值、美术资源和引用关系保存为数据库中的 ScriptableObject 子资产，动态玩法逻辑则由资产内部的 FlowGraph 表达，进入战斗时，系统会据此创建 CardInstance、UnitState 与战斗牌堆等彼此隔离的运行数据，而定义资产本身保持不变，数据库管理说明内容如何组织与启用，运行时数据模型说明定义资产、运行实例与安全修改路径之间的关系

内容沿着真实引用关系逐层组成战斗，卡牌先确定玩家看到的卡面和结算时执行的 Behavior，卡组再用卡牌引用与副本数量组织初始构筑、Run 中的 Master Deck 和遭遇战奖励池，随包 Demo 使用 Basic、Support、Skill、Burst 与 Curse 五套模板覆盖不同类型的战斗行动

画面中的五张代表卡牌来自 80 张随包成品，其中包含 6 张 Basic、20 张 Support、40 张 Skill、12 张 Burst 与 2 张 Curse，Strike 与 Defend 还分别提供一条由三个等级构成的升级链，卡牌创作说明卡面字段、费用、目标与 Behavior 如何共同决定一张卡牌，卡组创作则把这些卡牌组成 12 套职业起始卡组和 4 套奖励卡组，同一张卡牌定义可以被不同卡组直接复用

卡牌与卡组建立后，玩家单位会把初始卡组、生命、能量、职业标签、Prefab 与预览美术带入战场，Demo 为 Warrior、Mage、Hunter 与 Priest 四条职业线分别提供 Novice、Veteran、Master 三个阶级

四条职业线各自拥有独立的卡牌构筑、角色表现和三场递进战斗，合计 12 个可以直接引用的玩家单位，玩家侧确定后，敌人会在战场另一端通过 Intent 预告下一步行动，再由 Behavior 执行对应规则

随包 Demo 的 16 个敌人按四条职业主题组织，每条主题都包含 Normal、Elite、Boss 与 Summon，覆盖攻击、防御、增益、减益、治疗、特殊能力、多段行动、加权行为、阶段切换与召唤，目标选择会把玩家卡牌与敌人行为中的 Self、Opponent、All、集合筛选、排序、随机选择和玩家选择解析为实际单位，让战场两端共用同一套目标语义

玩家与敌人进入战场后，状态会在战斗推进过程中持续改变伤害、护甲、能量、费用、抽牌、回合和单位行为，它既能保存玩家可见的层数，也能通过 Behavior 响应 Hook、生命周期与其他战斗时机

这 30 个随包状态由 15 个 Buff 与 15 个 Debuff 组成，覆盖持续伤害、属性修正、易伤、虚弱、护盾、反伤、吸血、控制、生命损失抵消、衰减和全局规则修改，每个状态都可以回到状态创作检查叠层规则、FlowGraph 与引用位置，最后由遭遇战创作引用玩家、敌人阵容、奖励卡组与 Battle Rules，把前面建立的内容装配成一场可以启动、判定胜负并发放奖励的战斗

用 FlowGraph 把内容定义变成玩法行为

至此，Game Card Editor 已经确定战斗中有哪些对象以及它们彼此怎样引用，FlowGraph Editor 会沿用这些定义继续编排行为，把卡牌结算、状态响应与敌人行动组织成各自可以执行的 Behavior

上图把 Card、Status、Enemy 三类 Behavior 与 Group 可折叠子图放在同一画面中，卡牌从打出或其他生命周期入口开始结算，状态在 Hook 与战斗时机中持续改写规则，敌人通过意图模式选择并执行行动，Group 则把已经连通的复杂机制收进可折叠子图

这些流图共用同一套节点、端口和执行上下文，控制线决定先后、分支、循环、选择、等待与 Gate，数据线把单位、卡牌、集合、事件参数和计算结果传递到下一节点，字段既可以保留固定值，也可以提升为端口接收运行时输入，FlowGraph 模型完整解释图、节点、端口、上下文与执行顺序之间的关系

核心程序集提供 145 个节点，Demo 程序集加载后会再注册 2 个 FX 节点，完整节点库共 147 个节点

节点家族	数量	可以完成什么
Entry	33	在战斗、回合、卡牌、单位、状态、能量或事件时机启动行为
Hook	18	在伤害、护甲、治疗、能量、抽牌、费用与可打出判断提交前修改或取消结果
Action	27	修改 HP、护甲、能量、卡牌、牌堆、状态、变量、回合和单位
Operator	22	比较、计算、筛选、排序、选取、合并和转换数据
Get	19	读取单位、卡牌、牌堆、状态、战斗值、变量和事件参数
Flow	10	组织分支、循环、序列、玩家选择、Switch、等待与 Gate
FX	7 + 2 Demo	播放 VFX、SFX、动画、飘字、单位位移、闪烁与镜头反馈
Intent	6	构建敌人意图叶节点、序列、随机与生命阈值模式
Event	2	发送 GCS 内部事件或可选的 GES 事件
Group	1	把复杂流图整理成可以折叠的可视分组

其中 Group 只负责整理画布与封装已经连通的子图，组内节点仍然保留真实连线和执行关系，不会改变运行逻辑，其余节点已经覆盖多段攻击、X 费卡牌、发现、重放、牌堆检索与排序、装备耐久、Boss 多阶段、召唤与复活、跨流图事件、延迟结算、玩家选择和表现等待，节点总览提供完整查找入口，三个配方库则把常见机制整理成 103 个可以直接照着搭建的流图

想制作的机制	直接查看
伤害、护甲、X 费、抽弃牌、发现、重放、变形、姿态、费用与卡牌生命周期	52 个卡牌配方
毒、灼烧、力量、易伤、荆棘、壁垒、沉默、复活、装备与全局规则	30 个状态配方
意图序列、加权随机、Boss 阶段、召唤、分裂、逃跑、牌堆干扰与跨系统事件	21 个敌人配方

节点与配方完成规则表达后，同一套 Behavior 会在 Play Mode 中交给 Battle Runtime 执行，并转化为可以直接观察和验证的战斗结果

战斗运行时把规则落实为可验证结果

玩家打出一张手牌后，运行时会依次检查当前阶段、手牌归属、费用、出牌 Hook、Unplayable 与可打出 Hook，再解析目标并执行卡牌 FlowGraph，伤害、护甲与状态施加会经过对应 Hook，卡牌则按关键词进入 Discard 或 Exhaust，表现节点发出的 VFX、SFX、动画与浮字如果需要阻塞流程，会通过 Wait 节点或登记到 Animation Gate 的协程等待完成，随后战斗状态机继续推进敌人回合、动态召唤、玩家选择、奖励等待和胜负判定，下面这场 Hunter 战斗同时呈现了这些系统共同维护的结果

画面中的玩家与三名敌人 HP、当前手牌与费用、剩余能量、抽牌堆和弃牌堆数量、敌人意图以及当前回合，分别来自运行时中持续协作的不同系统，下表沿着这些可见结果给出各系统的职责与深入入口

运行系统	已经处理的内容	深入阅读
战斗生命周期	Battle Start、玩家回合、敌人阶段、胜利、失败、选择与奖励等待	战斗循环、战斗状态机
卡牌与牌堆	Draw、Hand、Discard、Exhaust，以及跨战斗保留的 Master Deck	卡牌区域与牌堆
目标选择	自身、对手、全体、集合筛选、排序、随机目标、玩家多选一与无有效目标处理	目标选择
状态与 Hook	叠加、上限、衰减、来源归因、主动 Behavior 与 18 个 Hook 节点	状态系统、Hook 节点
敌人战场	意图预告、跳过回合、动态召唤、移除、死亡、复活和多阶段 Boss	敌人创作、敌人配方
表现与等待	CardView 池、拖动出牌、目标箭头、状态 UI、选择与奖励面板、VFX、SFX、动画与 Animation Gate	表现层、自定义 UI
场景与启动	Manager、Encounter Bootstrap、Battle Board、Hand、Canvas、HUD 与 Presentation 根对象	战斗场景、战斗启动

这些可见结果一旦与规则预期不一致，单看 HP 偏差或尚未结束的动画无法判断问题发生在哪一步，Game Card Monitor 会继续把当时的状态与执行过程拆成可以逐项核对的记录

Game Card Monitor 连接实时状态与执行记录

一张卡牌造成的伤害少了 2 点、敌人没有推进下一意图、动画结束后战斗仍在等待，都可以沿阶段、牌堆、单位状态、Animation Gate、FlowGraph 执行摘要与事件时间线还原问题发生的过程，七个实时页签把这些证据集中在同一窗口

实际排查时，先在 Battle、Pile 与 Unit 中确认当前结果，再通过 Phase 还原阶段变化，最后沿 Gate 的等待来源、Flow 的执行摘要和 Event 的事件顺序定位具体数据或对应 Behavior，各页签的检查范围如下

页签	可以检查什么
Battle	当前遭遇战、回合、阵营、玩家与敌人概况
Pile	Hand、Draw、Discard、Exhaust 与 Master Deck 中的卡牌
Unit	HP、护甲、能量、状态、意图模式与单位实时数据
Phase	当前阶段、回合、选择等待状态与阶段切换历史
Gate	Animation Gate 的 Holder 数量、Timeout、持有原因与最近 Acquire/Release 记录
Flow	FlowGraph 的 Host、触发时机、访问节点数与同步执行耗时
Event	GCS 事件时间线、载荷摘要与 Dispatcher 订阅者数量

Game Card Monitor给出全部字段和按症状定位的检查顺序，启动失败、出牌被拒绝、事件没有触发或机制已经结算但画面没有更新时，还可以继续进入常见症状、创作错误与运行时错误，运行时内部已经可以完整追踪后，项目代码便可以通过同一套状态、修改和事件链路接入战斗

通过 GCSApi 接入项目并继续扩展

HUD、地图、任务、存档及其他项目系统需要读取或推动同一场战斗时，GCSApi 是项目代码接入 GCS 的统一入口，战斗查询读取权威 BattleState，内容查询读取 GameCardManager 当前启用的 Database，项目代码通过 Controller 执行修改，内置或自定义 Mutator 节点也会使用同一套状态写入入口，并按具体操作触发对应 Hook、事件与表现刷新

接口范围	成员数	可以完成什么
管理器与战斗生命周期	13	检查就绪状态、开始或释放战斗、出牌、结束回合和处理奖励
实时战斗状态与查询	38	读取阶段、单位、HP、护甲、意图、牌堆、费用、状态和格式化描述
战斗修改	24	造成伤害、修改 HP、护甲与能量、抽牌、移动卡牌、施加状态、召唤敌人和存取变量
内容发现与运行卡组	24	枚举活动数据库和内容、按 GUID 查找资产、管理跨战斗保留的 Master Deck
事件订阅	44	通用订阅，以及覆盖回合、卡牌、伤害、护甲、能量、状态、牌堆、奖励、选择和阶段的强类型入口
扩展注册表	4	发现 FlowGraph 节点、卡牌类型、卡牌标签和描述 Token

最小接入只需要从这个入口启动战斗、尝试出牌并结束玩家回合

using TinyGiants.GCS.Runtime;

GCSApi.StartBattle(encounter);
bool played = GCSApi.TryPlayCard(card, target);
GCSApi.EndPlayerTurn();

• 这三个调用与可视化内容进入相同的运行链路，GCSApi 使用指南按实际接入顺序覆盖启动、回合控制、UI 查询、安全修改、事件订阅与 Master Deck
• API 参考列出全部 147 个 public 成员的签名、返回值、空值约定和运行条件
• 43 个内置事件覆盖战斗与回合、卡牌生命周期、HP、护甲、伤害、能量、状态、敌人、延迟触发、奖励与玩家选择，其中 42 个事件提供 On* 强类型快捷入口，全部事件也可以按事件名订阅
• 事件指南解释订阅模型与生命周期，事件参考提供每个事件的载荷和准确触发时机

项目需要加入内置能力之外的机制时，扩展会继续沿用现有的节点发现、端口推断、执行上下文、内容分类与事件链路

扩展点	适用场景	文档
自定义 FlowGraph 节点	增加新的玩法动作、数据来源、选择器、规则运算或表现请求	自定义节点
自动与显式端口	把字段提升为输入，声明数据输出、下拉选项或动态控制分支	自定义端口
执行上下文	读取连线输入、解析单位与卡牌、通过 Controller 修改状态、存储结果和访问变量	执行上下文
卡牌类型、标签与描述 Token	加入项目自己的分类、筛选维度和动态卡牌文本	类型、标签与 Token
可复制样例	从模板、条件治疗节点和双输入运算节点开始编写扩展	扩展示例

• 四个反射注册表会自动发现带特性的 FlowGraph 节点、卡牌类型、卡牌标签和描述 Token，不需要维护手工注册清单
• 自定义节点会直接出现在原有 Add Node 菜单中，自动推断与显式声明的端口都会从同一执行上下文读取输入，节点对战斗状态的修改则继续交给 Controller
• 描述 Token 会把节点计算结果和项目数据格式化为卡牌文本，核心程序集内置 21 个，Demo 再提供 4 个，共计 25 个，卡牌文本因此能够使用运行时数值而不必复制计算逻辑

这些扩展仍然运行在 GCS 自身的战斗链路中，事件需要跨插件传递时，安装 GameEventSystem 后即可通过可选 GES 集成中的 Raise GES Event 与 On GES Event 建立双向通道，未检测到 GES runtime 时桥接代码不会启用，GCS 自身的战斗和内部事件仍然独立运行，随包 Demo 正是用这套正式工具链和运行时完成的可检查成品

随包 Demo 提供可以拆解的完整成品

Warrior、Mage、Hunter、Priest 四条职业线各自包含 Normal、Elite、Boss 三场战斗，共 12 个可以直接进入 Play Mode 的场景，每个场景都已经接通手牌、能量、目标选择、敌人意图、状态 HUD、奖励、结果界面与对应表现，所有内容与正式项目使用相同的 Game Card Editor、FlowGraph、运行时接口和扩展机制，完整规模如下

Demo 内容	数量	组成
可运行场景	12	四职业 × Normal、Elite、Boss
遭遇战定义	12	四职业 × Normal、Elite、Boss
玩家单位	12	四职业 × Novice、Veteran、Master
敌人	16	四职业 × Normal、Elite、Boss、Summon
卡牌	80	6 Basic、20 Support、40 Skill、12 Burst、2 Curse
卡组	16	12 套职业起始卡组、4 套奖励卡组
状态	30	15 Buff、15 Debuff

每张卡牌、每个状态和每个敌人都可以回到 Game Card Editor 检查字段、FlowGraph 与引用关系，每场遭遇战也可以在同一窗口核对玩家、敌人阵容、奖励卡组与 Battle Rules，再进入对应场景验证 Play Mode 表现

Demo 总览列出全部数量与六个预设数据库，战斗场景展示 12 场战斗的阵容和实机画面，需要反查单个资产或确认文件归属时，可以继续使用内容参考与资源布局，这些内容既能直接运行，也给出了正式项目需要的工程基础

面向正式项目的工程基础

完整工作链路能否进入正式项目，还取决于版本与依赖边界、数据引用、创作保护、运行一致性和问题诊断，GCS 在这些方面已经提供的基础集中在下表

工程维度	已提供的基础
Unity 与渲染管线	支持 Unity 2021.3 LTS 及以上版本，包括 Unity 6，Demo 使用管线无关的 Shader 与 Material，同时支持 Built-in Render Pipeline 与 URP
运行依赖	GCS 运行时 零第三方依赖，框架内置的过渡与程序动画由 TinyGiants 自有的 TGTween 驱动，表现节点也可以触发 Unity Animator
内容稳定性	ScriptableObject 子资产承载内容定义，Unity 对象引用连接内容关系，Active Database 明确控制运行时可用范围，GUID 用于内容查找
创作保护	Game Card Editor 提供 Undo/Redo、Validation、Used By 与跨数据库复制，Game Card Editor 与 FlowGraph Editor 的 Validation 会检查入口、连接与 Host 约束
运行一致性	状态修改统一交给 Controller，Hook 可以在提交前修改或取消结果，事件向订阅者广播变化，Animation Gate 等待已经登记的表现任务
诊断能力	Game Card Monitor 实时显示 Battle、Pile 与 Unit 快照，并在 Play Mode 中记录 Phase、Gate、Flow 与 Event 历史

安装与环境要求给出版本、渲染管线与首场景检查表，运行时数据模型解释定义、实例和安全修改路径，表现层说明 UI、VFX、音频、动画与玩法状态之间的边界，至此可以根据当前目标直接进入对应的实战文档

选择下一步

可以先运行随包成品确认最终体验，也可以直接创作自己的战斗内容、接入项目代码或扩展 GCS

你现在想做什么	推荐入口
先体验一场已经完成的战斗	运行第一场 Demo 战斗
从零完成自己的卡牌、敌人与遭遇战	完成第二场战斗
理解内容、行为与运行时怎样配合	数据库管理、FlowGraph 模型、战斗流程、运行时数据模型
直接开始制作内容	卡牌、卡组、玩家、敌人、状态、遭遇战
查找节点或现成机制	节点总览、卡牌配方、状态配方、敌人配方
接入自定义 UI 与项目代码	GCSApi 使用指南、自定义 UI、事件指南
扩展节点、端口或内容类型	自定义节点、自定义端口、执行上下文
排查创作或运行问题	常见症状、创作错误、运行时错误