使用指南
Cocos 导演 / 场景 / Director节点
Cocos 导演 / 场景 / Director 节点手册，包含 7 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
掌握 Cocos 导演 / 场景 / Director 节点的用途、引脚和常见组合方式。
覆盖范围
- 节点数量：7
- 分类路径：Cocos 导演 / 场景 / Director
典型使用场景
- 组合节点完成游戏逻辑
- 作为中小型游戏功能模块的一部分
通用注意事项
- 按引脚类型连接节点，避免把执行流和数据流混用。
- 修改上游类型或资源命名后，应重新检查相关连线。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取当前场景 | directorGetCurrentScene | 0 / 1 | 立即继续 |
| 加载场景 | directorLoadScene | 2 / 6 | 需要等待结果 |
| 立即运行场景 | directorRunSceneImmediate | 2 / 2 | 立即继续 |
| 立即运行场景资产 | directorRunSceneAssetImmediate | 2 / 2 | 立即继续 |
| 预加载场景 | directorPreloadScene | 2 / 8 | 需要等待结果 |
| 运行场景 | directorRunScene | 2 / 2 | 立即继续 |
| 运行场景资产 | directorRunSceneAsset | 2 / 2 | 立即继续 |
获取当前场景
获取当前场景：拿到游戏现在正在运行的场景。 通常可以把它当成场景相关操作的起点，再继续读取场景信息，或把它交给场景切换节点使用。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directorGetCurrentScene |
| 分类 | Cocos 导演 |
| 二级分类 | 场景 |
| 分组 | Director |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
无。
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
scene | 场景 | 数据 | cc.Node / Scene | Scene 场景实例 当前正在运行的场景，或切换成功后得到的新场景。 | - | 可选 |
使用场景
- 读取游戏运行时的对象或数据状态
- 把结果传给分支、调试或后续计算节点
注意事项
- 适合的工作流类型：component、library、method、function、class。
加载场景
加载场景：开始切换到另一个场景。 节点刚收到请求时会先从“已发起”引脚继续，等新场景真的切换成功后，再从“成功”引脚继续；如果切换失败，则走“失败”引脚。 注意：这里使用的是场景名称，不是资产 UUID。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directorLoadScene |
| 分类 | Cocos 导演 |
| 二级分类 | 场景 |
| 分组 | Director |
| 是否需要等待结果 | 是 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
sceneName | 场景名 | 数据 | string | 场景名 选择你要切换或预加载的场景名称。这里填的是场景名，不是资产 UUID。 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | 已发起 | 执行流 | 执行流 | 已发起 开始切换场景后立即触发。 | - | 可选 |
accepted | 已接受 | 数据 | boolean | 是否接受请求 true 表示运行系统接受了这次加载请求。 | - | 可选 |
then | 成功 | 执行流 | 执行流 | 切换成功 新场景真正切换完成后触发。 | - | 可选 |
scene | 场景 | 数据 | cc.Node / Scene | Scene 场景实例 当前正在运行的场景，或切换成功后得到的新场景。 | - | 可选 |
onError | 失败 | 执行流 | 执行流 | 切换失败 请求未被接受或场景切换失败时触发。 | - | 可选 |
error | 错误 | 数据 | string | 错误信息 加载失败的原因说明。 | - | 可选 |
使用场景
- 按需加载资源或场景数据
- 把异步加载结果交给后续节点使用
注意事项
- 这是异步节点，后续逻辑应从完成、成功或对应执行出口继续。
- 适合的工作流类型：component、library、method、function、class。
立即运行场景
立即运行场景：马上切到这个场景，不等当前帧结束。 适合你明确知道现在就该切场景的情况；如果希望当前帧先完整跑完，再切场景，更适合用“运行场景”。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directorRunSceneImmediate |
| 分类 | Cocos 导演 |
| 二级分类 | 场景 |
| 分组 | Director |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
scene | 场景 | 数据 | cc.Node / Scene | Scene 场景实例 这里需要连接一个已经存在的 Scene 游戏运行时对象。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
scene | 场景 | 数据 | cc.Node / Scene | Scene 场景实例 当前正在运行的场景，或切换成功后得到的新场景。 | - | 可选 |
使用场景
- 连接到同类节点组合完整游戏逻辑
- 在中小型游戏中封装一段明确的行为
注意事项
- 适合的工作流类型：component、library、method、function、class。
立即运行场景资产
立即运行场景资产：马上切到这个场景资产对应的场景。 适合你已经拿到场景资产，并且希望现在立刻完成场景切换。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directorRunSceneAssetImmediate |
| 分类 | Cocos 导演 |
| 二级分类 | 场景 |
| 分组 | Director |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
sceneAsset | 场景资产 | 数据 | cc.Asset / SceneAsset | SceneAsset 场景资产 这里需要连接一个已加载的 SceneAsset。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
sceneAsset | 场景资产 | 数据 | cc.Asset / SceneAsset | SceneAsset 场景资产 预加载成功得到或动作节点透传的 SceneAsset。 | - | 可选 |
使用场景
- 连接到同类节点组合完整游戏逻辑
- 在中小型游戏中封装一段明确的行为
注意事项
- 适合的工作流类型：component、library、method、function、class。
预加载场景
预加载场景：提前把场景需要的资产准备好，但不会马上切过去。 适合在加载页、过场或玩家即将进入新区域时提前准备资产。 有新进度时会走“进度”引脚，全部准备完成后走“成功”引脚。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directorPreloadScene |
| 分类 | Cocos 导演 |
| 二级分类 | 场景 |
| 分组 | Director |
| 是否需要等待结果 | 是 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
sceneName | 场景名 | 数据 | string | 场景名 选择你要切换或预加载的场景名称。这里填的是场景名，不是资产 UUID。 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | 已发起 | 执行流 | 执行流 | 已发起 开始预加载后立即触发。 | - | 可选 |
then | 成功 | 执行流 | 执行流 | 预加载成功 场景资产全部准备完成后触发。 | - | 可选 |
sceneAsset | 场景资产 | 数据 | cc.Asset / SceneAsset | SceneAsset 场景资产 预加载成功得到或动作节点透传的 SceneAsset。 | - | 可选 |
onError | 失败 | 执行流 | 执行流 | 预加载失败 预加载失败时触发。 | - | 可选 |
error | 错误 | 数据 | string | 错误信息 预加载失败的原因说明。 | - | 可选 |
onProgress | 进度 | 执行流 | 执行流 | 进度更新 预加载进度变化时触发。 | - | 可选 |
finished | 已完成 | 数据 | number | 已完成数量 当前已完成的资产数量。 | - | 可选 |
total | 总数 | 数据 | number | 总数量 需要预加载的总资产数量。 | - | 可选 |
使用场景
- 按需加载资源或场景数据
- 把异步加载结果交给后续节点使用
注意事项
- 这是异步节点，后续逻辑应从完成、成功或对应执行出口继续。
- 适合的工作流类型：component、library、method、function、class。
运行场景
运行场景：把一个已经准备好的场景安排到当前帧结束后再切过去。 如果你不希望立刻打断当前帧，而是想等这一帧正常结束后再切场景，就用这个节点。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directorRunScene |
| 分类 | Cocos 导演 |
| 二级分类 | 场景 |
| 分组 | Director |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
scene | 场景 | 数据 | cc.Node / Scene | Scene 场景实例 这里需要连接一个已经存在的 Scene 游戏运行时对象。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
scene | 场景 | 数据 | cc.Node / Scene | Scene 场景实例 当前正在运行的场景，或切换成功后得到的新场景。 | - | 可选 |
使用场景
- 连接到同类节点组合完整游戏逻辑
- 在中小型游戏中封装一段明确的行为
注意事项
- 适合的工作流类型：component、library、method、function、class。
运行场景资产
运行场景资产：把一个场景资产安排到当前帧结束后再切过去。 适合你手里拿到的是场景资产，而不是已经创建好的场景对象。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directorRunSceneAsset |
| 分类 | Cocos 导演 |
| 二级分类 | 场景 |
| 分组 | Director |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
sceneAsset | 场景资产 | 数据 | cc.Asset / SceneAsset | SceneAsset 场景资产 这里需要连接一个已加载的 SceneAsset。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
sceneAsset | 场景资产 | 数据 | cc.Asset / SceneAsset | SceneAsset 场景资产 预加载成功得到或动作节点透传的 SceneAsset。 | - | 可选 |
使用场景
- 连接到同类节点组合完整游戏逻辑
- 在中小型游戏中封装一段明确的行为
注意事项
- 适合的工作流类型：component、library、method、function、class。