资产 / 预制体 / Prefab节点

学习目标

读取和验证 Cocos 资产对象，把图片、音频、材质、Prefab 等资源接入工作流逻辑。

覆盖范围

• 节点数量：11
• 分类路径：资产 / 预制体 / Prefab

典型使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

通用注意事项

• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

节点索引

节点	节点 ID	输入/输出	执行方式
获取持久化标记	prefabGetPersistent	1 / 1	立即继续
获取模板根节点	prefabGetData	1 / 1	立即继续
获取所有属性	prefabGetProperties	1 / 4	立即继续
获取优化策略	prefabGetOptimizationPolicy	1 / 1	立即继续
获取优化阈值	prefabGetOptimizationThreshold	0 / 1	立即继续
设置持久化标记	prefabSetPersistent	3 / 2	立即继续
设置模板根节点	prefabSetData	3 / 2	立即继续
设置所有属性	prefabSetProperties	5 / 2	立即继续
设置优化策略	prefabSetOptimizationPolicy	3 / 2	立即继续
实例化预制体	prefabInstantiate	2 / 2	立即继续
校验预制体	prefabValidate	1 / 1	立即继续

获取持久化标记

读出 Prefab 资产上的持久化标记（persistent），输出 true 或 false。 这是 Prefab 资产上的一个标记字段，表示该 Prefab 是否倾向于作为跨场景常驻节点模板。注意：此标记不等价于 director.addPersistRootNode(node)——真正让节点跨场景常驻，仍需实例化后单独处理。

节点信息

字段	值
节点 ID	prefabGetPersistent
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体 这里需要连接一个已经加载好的 Prefab 实例。 该端口没有”选择预制体”按钮，请先使用以下方式获取预制体实例： - 加载资产：把”类型”选为 PREFAB，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Prefab。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
persistent	持久化标记	数据	boolean	持久化标记 Prefab 资产上的标记，不等价于跨场景常驻 API。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取模板根节点

读出 Prefab 的根节点模板（data），即该 Prefab 资产保存的原始节点结构。 注意：这里获取的是 Prefab 的模板节点，不是场景中已经实例化的节点。修改这个节点等同于修改 Prefab 模板本身，而不是修改某个具体的游戏运行时实例。

节点信息

字段	值
节点 ID	prefabGetData
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体 这里需要连接一个已经加载好的 Prefab 实例。 该端口没有”选择预制体”按钮，请先使用以下方式获取预制体实例： - 加载资产：把”类型”选为 PREFAB，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Prefab。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
node	模板根节点	数据	cc.Node	模板根节点 Prefab 资产保存的根节点模板。这不是实例化后的场景节点，修改它会影响 Prefab 模板本身。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取所有属性

一次性读出 Prefab 的全部常用属性：模板根节点、优化策略、持久化标记、是否有效。等同于连接多个 获取类节点，但只用一个节点即可。 适合调试、预览、批量检查 Prefab 配置等场景。 注意：node 输出的是 Prefab 的模板根节点，不是实例化后的场景节点。

节点信息

字段	值
节点 ID	prefabGetProperties
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体 这里需要连接一个已经加载好的 Prefab 实例。 该端口没有”选择预制体”按钮，请先使用以下方式获取预制体实例： - 加载资产：把”类型”选为 PREFAB，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Prefab。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
node	模板根节点	数据	cc.Node	模板根节点 Prefab 资产保存的根节点模板（非实例化节点）。	-	可选
optimizationPolicy	优化策略	数据	number	优化策略 AUTO = 0，SINGLE_INSTANCE = 1，MULTI_INSTANCE = 2。	-	可选
persistent	持久化标记	数据	boolean	持久化标记 Prefab 资产上的标记值。	-	可选
isValid	是否有效	数据	boolean	是否有效 validate() 校验结果；true 表示结构正常。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取优化策略

读出 Prefab 的实例化优化策略（optimizationPolicy）。 该策略决定引擎对该 Prefab 进行实例化时采用哪种性能优化方式：

• AUTO（0）：根据实例化次数自动判断，首次使用单次优化，达到阈值后切换到多次优化。
• SINGLE_INSTANCE（1）：单次创建优化，适合只创建一次的 Prefab。
• MULTI_INSTANCE（2）：多次创建优化，适合频繁创建的 Prefab（如子弹、敌人）。

节点信息

字段	值
节点 ID	prefabGetOptimizationPolicy
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体 这里需要连接一个已经加载好的 Prefab 实例。 该端口没有”选择预制体”按钮，请先使用以下方式获取预制体实例： - 加载资产：把”类型”选为 PREFAB，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Prefab。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
optimizationPolicy	优化策略	数据	number	优化策略 AUTO = 0，SINGLE_INSTANCE = 1，MULTI_INSTANCE = 2。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取优化阈值

读取 Prefab 在 AUTO 策略下的优化切换阈值。 当实例化次数达到该值后，引擎会自动从”单次优化”切换到”多次优化”模式。默认值为 3，该值为只读常量，不可修改。

节点信息

字段	值
节点 ID	prefabGetOptimizationThreshold
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

无。

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
threshold	优化阈值	数据	number	优化阈值 AUTO 策略下，实例化次数达到 3（默认值）后切换为多次创建优化。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

设置持久化标记

设置 Prefab 资产上的持久化标记（persistent）。 注意：这是 Prefab 资产上的一个标记字段，不等价于直接把某个游戏运行时节点注册为持久根节点。如果你希望实例化后的节点跨场景常驻，需要在节点实例化后额外调用 director.addPersistRootNode(node)。

节点信息

字段	值
节点 ID	prefabSetPersistent
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体 这里需要连接一个已经加载好的 Prefab 实例。 该端口没有”选择预制体”按钮，请先使用以下方式获取预制体实例： - 加载资产：把”类型”选为 PREFAB，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Prefab。	-	必填
persistent	持久化标记	数据	boolean	持久化标记 设置 Prefab 资产上的持久化标记。注意：不等价于跨场景常驻 API。	开关 默认值：false	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体（透传） 把当前操作的 Prefab 实例原样传出，便于将多个配置节点串联在一起。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

设置模板根节点

将一个 Node 设置为 Prefab 的根节点模板（data）。 重要：这个操作修改的是预制体模板本身（即 Prefab 资产中保存的原始节点内容），而不是修改已经实例化到场景中的节点。 执行后 Prefab 实例将透传到输出端口，便于链式调用其他配置节点。

节点信息

字段	值
节点 ID	prefabSetData
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体 这里需要连接一个已经加载好的 Prefab 实例。 该端口没有”选择预制体”按钮，请先使用以下方式获取预制体实例： - 加载资产：把”类型”选为 PREFAB，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Prefab。	-	必填
node	根节点	数据	cc.Node	根节点 要设置为 Prefab 模板根节点的 Node。注意：这会修改 Prefab 模板内容，不是修改场景中已实例化的节点。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体（透传） 把当前操作的 Prefab 实例原样传出，便于将多个配置节点串联在一起。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

设置所有属性

一次性批量修改 Prefab 的多个常用属性：模板根节点、优化策略、持久化标记。 公开引脚语义（重要）：除 exe 与 prefab 外，所有可写属性引脚默认不公开（isPublic: false），只有被显式公开的引脚才参与写入。若想保留目标属性原值不变，必须保持引脚不公开——仅断开连线不够，已公开的引脚会用内联控件默认值覆盖原值。

节点信息

字段	值
节点 ID	prefabSetProperties
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体 这里需要连接一个已经加载好的 Prefab 实例。 该端口没有”选择预制体”按钮，请先使用以下方式获取预制体实例： - 加载资产：把”类型”选为 PREFAB，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Prefab。	-	必填
node	模板根节点	数据	cc.Node	模板根节点 要设置为 Prefab 模板根节点的 Node。默认不公开；公开后才参与写入。注意：这会修改 Prefab 模板本身。	-	可选 默认隐藏
optimizationPolicy	优化策略	数据	number	优化策略 选择实例化优化方式。默认不公开；公开后才参与写入。	下拉选择 默认值：0	可选 默认隐藏
persistent	持久化标记	数据	boolean	持久化标记 Prefab 资产上的持久化标记。默认不公开；公开后才参与写入。注意：不等价于跨场景常驻 API。	开关 默认值：false	可选 默认隐藏

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体（透传） 把当前操作的 Prefab 实例原样传出，便于将多个配置节点串联在一起。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

设置优化策略

设置 Prefab 的实例化优化策略（optimizationPolicy）。 根据使用场景选择合适的策略：

• AUTO（0）：自动判断，适合大多数情况。
• SINGLE_INSTANCE（1）：单次创建优化，适合只创建一次的 Prefab。
• MULTI_INSTANCE（2）：多次创建优化，适合频繁实例化的 Prefab（如子弹、敌人）。

节点信息

字段	值
节点 ID	prefabSetOptimizationPolicy
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体 这里需要连接一个已经加载好的 Prefab 实例。 该端口没有”选择预制体”按钮，请先使用以下方式获取预制体实例： - 加载资产：把”类型”选为 PREFAB，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Prefab。	-	必填
optimizationPolicy	优化策略	数据	number	优化策略 AUTO = 0，SINGLE_INSTANCE = 1，MULTI_INSTANCE = 2。	下拉选择 默认值：0	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体（透传） 把当前操作的 Prefab 实例原样传出，便于将多个配置节点串联在一起。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

实例化预制体

将 Prefab 资产实例化为一个新的游戏运行时节点（Node）。 重要说明：

• 生成一个全新的 Node 实例，对实例的任何修改都不会自动写回原 Prefab 资产。
• 实例化后的 Node 需要手动添加到场景中（如通过 添加子节点 节点），否则不会显示。
• 这是一个执行流节点：需要先走到这里完成实例化，再把结果节点继续传给后续操作。

节点信息

字段	值
节点 ID	prefabInstantiate
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体 这里需要连接一个已经加载好的 Prefab 实例。 该端口没有”选择预制体”按钮，请先使用以下方式获取预制体实例： - 加载资产：把”类型”选为 PREFAB，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Prefab。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
node	节点	数据	cc.Node	Node 实例 从 Prefab 实例化出的新游戏运行时节点。对该节点的修改不会影响原 Prefab 资产。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

校验预制体

对 Prefab 进行基础有效性校验，输出 true 或 false。 返回 false 表示 Prefab 存在结构问题（如根节点数据异常），此时不应继续对其进行实例化或属性操作。

节点信息

字段	值
节点 ID	prefabValidate
分类	资产
二级分类	预制体
分组	Prefab
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
prefab	预制体	数据	cc.Asset / Prefab	Prefab 预制体 这里需要连接一个已经加载好的 Prefab 实例。 该端口没有”选择预制体”按钮，请先使用以下方式获取预制体实例： - 加载资产：把”类型”选为 PREFAB，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Prefab。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
isValid	是否有效	数据	boolean	是否有效 true：Prefab 结构正常；false：存在结构问题。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。