使用指南
核心概念 / 工作流文件、Flow 和文件类型
解释 .sgw 文件、主 Flow、组件、函数库、类、接口、枚举和结构体之间的关系。
16
.sgw 是 Script Graph 的保存单位，Flow 是 .sgw 里的逻辑区域。可以把 .sgw 理解成一个文件，把 Flow 理解成文件中的具体函数、构造逻辑或主逻辑。
一个文件解决一个主要问题
新手最容易踩的坑，是把所有逻辑都放进一个巨大 .sgw。更稳的做法是按职责拆分：
| 文件 | 适合承载 |
|---|---|
PlayerController.sgw | 玩家输入、移动、碰撞、受伤 |
GameRoot.sgw | 场景启动、关卡状态、全局事件 |
UiHomePanel.sgw | 按钮点击、场景切换、面板显隐 |
GameMath.sgw | 分数计算、随机权重、坐标换算 |
PlayerStats.sgw | 血量、速度、攻击力等结构化数据 |
文件越聚焦，后续排查、复用和编译越清晰。
主 Flow 决定文件类型
首次打开空 .sgw 时，你选择的主类型会决定这个文件的核心用途。
| 主类型 | 运行方式 | 常见入口 |
|---|---|---|
| 组件 | 挂到 Cocos 节点后随场景运行 | 加载、启动、更新、启用、禁用、销毁 |
| 函数库 | 被其他工作流调用 | 函数入口、函数返回 |
| 类 | 被实例化后使用 | 构造函数、成员方法 |
| 接口 | 作为类型契约被类实现 | 字段和方法声明 |
| 枚举 | 作为有限值被变量和分支引用 | 枚举成员 |
| 结构体 | 作为数据包被构造、拆解和修改 | 字段定义 |
如果要做能直接跑起来的玩法逻辑，从“组件”开始。
Flow 不是执行线程
Flow 不是一个后台线程，也不是自动并行任务。它只是逻辑组织单元。什么时候执行，仍然取决于入口节点和调用关系：
- 组件主 Flow 通过生命周期事件进入。
- 函数 Flow 通过函数调用节点进入。
- 类方法 Flow 通过实例方法调用进入。
- 事件绑定 Flow 通过对应事件触发进入。
没有入口、没有调用、没有事件，就不会执行。
文件之间如何协作
常见协作方式如下：
| 需求 | 推荐方式 |
|---|---|
| 多个组件都要计算伤害 | 放到函数库 |
| 角色和敌人都有血量、速度 | 用结构体统一字段 |
| 状态只允许固定几个值 | 用枚举 |
| 多类对象要遵守同一能力 | 用接口 |
| 复杂对象需要方法和继承 | 用类 |
| 只是控制某个场景节点 | 用组件工作流 |
命名建议
- 组件工作流用行为名：
PlayerController、GameRoot、StartButton。 - 函数库用领域名：
GameMath、UiTools、ScoreRules。 - 枚举用名词：
GameState、ItemQuality、MoveDirection。 - 结构体用数据名：
PlayerStats、DamageResult、SpawnConfig。 - 类用对象名：
InventoryItem、EnemyModel、QuestState。
继续阅读
- 想理解节点怎么连接，读 节点、引脚和连线。
- 想理解执行顺序，读 事件、执行流和数据流。
- 想做真实 UI 交互，读 按钮开始游戏案例。