使用指南
资产 / 材质 / Material节点
资产 / 材质 / Material 节点手册，包含 15 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
读取和验证 Cocos 资产对象，把图片、音频、材质、Prefab 等资源接入工作流逻辑。
覆盖范围
- 节点数量：15
- 分类路径：资产 / 材质 / Material
典型使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
通用注意事项
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 初始化材质 | materialInitialize | 3 / 2 | 立即继续 |
| 初始化默认材质 | materialInitDefault | 3 / 2 | 立即继续 |
| 获取 Effect 名称 | materialGetEffectName | 1 / 1 | 立即继续 |
| 获取 EffectAsset | materialGetEffectAsset | 1 / 1 | 立即继续 |
| 获取 Material Hash | materialGetHash | 1 / 1 | 立即继续 |
| 获取 Pass 数量 | materialGetPassCount | 1 / 1 | 立即继续 |
| 获取 Shader 属性 | materialGetProperty | 3 / 1 | 立即继续 |
| 获取 Technique 索引 | materialGetTechnique | 1 / 1 | 立即继续 |
| 获取所有属性 | materialGetProperties | 1 / 6 | 立即继续 |
| 拷贝材质 | materialCopy | 4 / 2 | 立即继续 |
| 设置 Shader 属性 | materialSetProperty | 5 / 2 | 立即继续 |
| 设置所有属性 | materialSetProperties | 7 / 2 | 立即继续 |
| 校验材质 | materialValidate | 1 / 1 | 立即继续 |
| 新建材质 | materialCreate | 1 / 2 | 立即继续 |
| 重置 Uniforms | materialResetUniforms | 3 / 2 | 立即继续 |
初始化材质
调用 initialize(info: IMaterialInfo)，将 新建材质 产生的空材质绑定到指定 effect 并完成初始化配置。 重要限制：引擎仅允许对尚未初始化的空材质调用此方法；若目标材质已被初始化（如加载好的材质），引擎会打印警告并提前返回，不会生效。 若要修改已有材质，请改用 拷贝材质 或 设置所有属性。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialInitialize |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
materialInfo | 材质信息 | 数据 | struct / IMaterialInfo | 材质信息 包含 effectAsset / effectName、technique 索引、宏定义（defines）和管线状态（states）的初始化参数结构体。 请通过 构造结构体 节点填写后连接到此端口。 仅对 新建材质 输出的空材质有效；对已初始化材质无效且引擎会警告。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质（透传） 把当前操作的 Material 实例原样传出，便于将多个配置节点串联在一起。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
初始化默认材质
调用 initDefault(uuid?)，将目标材质整体重置为内置默认效果（默认为 builtin-unlit，引擎同时会把 mainColor 设为洋红色）。 注意：这是整体重置操作，会覆盖材质的全部数据，而不是局部补齐。若要基于现有材质做局部修改，请改用 拷贝材质 或 设置所有属性。 若需指定其他内置 effect，可通过 builtinUuid 端口传入对应 uuid 字符串；空字符串时沿用默认行为。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialInitDefault |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
builtinUuid | 内置 UUID | 数据 | string | 内置 Effect UUID 可选参数。传入要初始化的内置 effect uuid 字符串；空字符串时沿用默认行为，初始化为 builtin-unlit（主色变洋红）。 | 输入框 默认值："" | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质（透传） 把当前操作的 Material 实例原样传出，便于将多个配置节点串联在一起。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取 Effect 名称
读出当前材质所绑定的 effect 名称字符串（来自 effectAsset?.name）。 常用于调试、日志输出或根据 effect 名称走不同分支。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialGetEffectName |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
effectName | Effect 名称 | 数据 | string | Effect 名称 材质绑定的 effect 名称字符串，例如 “builtin-unlit”。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取 EffectAsset
读出当前材质所绑定的 EffectAsset 实例。 可把输出连接到 EffectAsset 系列节点，进一步读取 effect 的 techniques、shaders 等配置信息。 若材质尚未绑定 effect，此端口输出 null。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialGetEffectAsset |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
effectAsset | 效果资产 | 数据 | cc.Asset / EffectAsset | EffectAsset 材质绑定的效果资产实例。可连接到 EffectAsset 系列节点读取 effect 配置信息；未绑定时为 null。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取 Material Hash
读出当前材质的渲染 hash 值。 hash 值由引擎根据材质配置自动计算，用于批次合并与渲染优化。相同 hash 的材质可进行 draw call 合批。 该值是只读的，不应直接用于业务数值计算；通常只在性能分析、两个材质是否可合批判断等场景中使用。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialGetHash |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
hash | Hash 值 | 数据 | number | Material Hash 材质的渲染 hash 值，由引擎自动计算，用于合批判断。只读，不应参与普通数值运算。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取 Pass 数量
读出当前材质的渲染 pass 数量（通过 material.passes.length 派生）。 大多数材质只有一个 pass（单 pass 渲染）。特殊效果如轮廓、多层混合可能有多个 pass。 首版不直接暴露 Pass[] 原始数组，因为 Pass 类型依赖内部渲染系统，当前项目无稳定消费链路。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialGetPassCount |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
passCount | Pass 数量 | 数据 | number | Pass 数量 材质的渲染 pass 数量（整数）。由 material.passes.length 派生；首版不暴露 Pass[] 原始数组。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取 Shader 属性
调用 material.getProperty(name, passIndex?)，按属性名读取材质的 shader uniform 值。 支持的值类型：数字、向量、颜色、矩阵、四元数、纹理或 null。首版使用 ANY 类型端口，不做静态类型检查。 passIndex 语义：未公开（不连接）时，引擎搜索全部 pass 返回第一个命中值；公开并传入具体值时，只在指定 pass 上查询。 该节点有执行头（SET_STYLE），因为其行为依赖查询条件。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialGetProperty |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
propertyName | 属性名 | 数据 | string | 属性名 要查询的 shader uniform 名称字符串，例如 mainColor、mainTexture。名称区分大小写，需与 effect 中声明的 uniform 完全一致。 | 输入框 默认值："" | 必填 |
passIndex | Pass 索引 | 数据 | number | Pass 索引（可选） 指定要查询的 pass 下标。默认不公开：不连接时引擎搜索全部 pass 并返回第一个命中值；公开并传入具体值时只在指定 pass 上查询。 | 输入框 默认值：0 | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
value | 属性值 | 数据 | any | 属性值 读取到的 shader uniform 值。类型为 ANY（引擎异构联合类型，首版不做静态推断）。支持数字、向量、颜色、矩阵、四元数、纹理或 null。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取 Technique 索引
读出当前材质使用的 technique 索引（整数），对应 EffectAsset.techniques 数组中的下标。 大多数材质只有一个 technique（索引为 0）。多 technique 的材质通常用于表示不同渲染质量级别。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialGetTechnique |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
technique | Technique 索引 | 数据 | number | Technique 索引 当前材质使用的 technique 索引（整数），对应 EffectAsset.techniques 数组下标。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取所有属性
一次性读出 Material 的全部常用属性：effectAsset、effectName、technique、hash、passCount 与 isValid。等同于连接多个 获取类节点，但只用一个节点即可。 适合需要同时读取多个属性的场景，例如调试面板、批量比较、序列化预览。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialGetProperties |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
effectAsset | 效果资产 | 数据 | cc.Asset / EffectAsset | EffectAsset 材质绑定的效果资产实例。 | - | 可选 |
effectName | Effect 名称 | 数据 | string | Effect 名称 材质绑定的 effect 名称字符串。 | - | 可选 |
technique | Technique 索引 | 数据 | number | Technique 索引 当前材质使用的 technique 索引。 | - | 可选 |
hash | Hash 值 | 数据 | number | Hash 值 材质的渲染 hash，用于合批判断。 | - | 可选 |
passCount | Pass 数量 | 数据 | number | Pass 数量 材质的渲染 pass 数量。 | - | 可选 |
isValid | 是否有效 | 数据 | boolean | 是否有效 true：材质合法可用；false：无效或未初始化。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
拷贝材质
调用 material.copy(sourceMaterial, overrides?)，把 sourceMaterial 的全部配置复制到 material，可同时通过 overrides 部分覆盖初始化参数。 这是对已加载材质做”安全复制后再定制”的推荐入口：先从原始材质拷贝，再通过 overrides 指定要改动的字段，其他字段保持原样。 overrides 端口为可选 STRUCT(IMaterialInfo)；不连接时按源材质原样复制。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialCopy |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
sourceMaterial | 源材质 | 数据 | cc.Asset / Material | 源材质 要复制配置的来源 Material 实例。必须是已加载的材质。复制完成后，目标 material 的 effect、technique、宏定义和 uniform 将与源材质一致（可通过 overrides 局部覆盖）。 | - | 必填 |
overrides | 覆盖参数 | 数据 | struct / IMaterialInfo | 覆盖参数（可选） IMaterialInfo 结构体，用于在复制基础上局部覆盖初始化参数（如 effectAsset、technique、defines 等）。 不连接时直接按源材质原样复制。 | - | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质（透传） 把当前操作的 Material 实例原样传出，便于将多个配置节点串联在一起。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
设置 Shader 属性
调用 material.setProperty(name, value, passIndex?)，按属性名写入材质的 shader uniform 值。 支持的值类型：数字、向量、颜色、矩阵、四元数、纹理或 null。value 端口不提供内联控件，请从上游节点连入。 passIndex 语义：未公开（不连接）时，引擎对全部适用 pass 写入；公开并传入具体值时，只写入指定 pass。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialSetProperty |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
propertyName | 属性名 | 数据 | string | 属性名 要写入的 shader uniform 名称字符串，例如 mainColor、mainTexture。名称区分大小写，需与 effect 中声明的 uniform 完全一致。 | 输入框 默认值："" | 必填 |
value | 属性值 | 数据 | any | 属性值 要写入的 shader uniform 值。类型为 ANY，支持数字、向量、颜色、矩阵、四元数、纹理或 null。不提供内联控件，请从上游节点连入。 | - | 必填 |
passIndex | Pass 索引 | 数据 | number | Pass 索引（可选） 指定要写入的 pass 下标。默认不公开：不连接时引擎对全部适用 pass 写入；公开并传入具体值时只写入指定 pass。 | 输入框 默认值：0 | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质（透传） 把当前操作的 Material 实例原样传出，便于将多个配置节点串联在一起。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
设置所有属性
通过组装 IMaterialInfo 覆盖对象，基于 material.copy(material, overrides) 批量修改材质的常用属性：effectAsset、effectName、technique、defines、states。 遵循公开引脚语义：除 exe 与 material 外，其余可写输入默认 isPublic: false——只有被显式公开（连线或配置 isPublic: true）的引脚才参与游戏运行时写入。未公开的字段不参与 overrides 组装，保持材质原值。 注意：defines / states 首版以 OBJECT 类型建模；effectAsset 不提供内联 picker。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialSetProperties |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
effectAsset | 效果资产 | 数据 | cc.Asset / EffectAsset | 效果资产（可选） 要替换的 EffectAsset 实例。默认不公开；公开后才参与 overrides 写入。不提供内联 picker，请从上游节点连入。 | - | 可选 默认隐藏 |
effectName | Effect 名称 | 数据 | string | Effect 名称（可选） 要替换的 effect 名称字符串。默认不公开；公开后才参与 overrides 写入。 | 输入框 默认值："" | 可选 默认隐藏 |
technique | Technique 索引 | 数据 | number | Technique 索引（可选） 要使用的 technique 下标。默认不公开；公开后才参与 overrides 写入。 | 输入框 默认值：0 | 可选 默认隐藏 |
defines | 宏定义 | 数据 | object | 宏定义（可选） MacroRecord 类型，动态 key 字典对象。默认不公开；首版以 OBJECT 建模，不提供内联编辑器。 | - | 可选 默认隐藏 |
states | 管线状态 | 数据 | object | 管线状态（可选） PassOverrides 类型，渲染管线状态覆盖对象。默认不公开；首版以 OBJECT 建模，不提供内联编辑器。 | - | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质（透传） 把当前操作的 Material 实例原样传出，便于将多个配置节点串联在一起。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
校验材质
检查材质实例是否处于合法可用状态。 常用于条件分支判断：加载后先校验再决定是否继续后续材质操作。 返回 true 表示材质已正确初始化并可安全使用；返回 false 表示材质无效或尚未初始化。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialValidate |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
isValid | 是否有效 | 数据 | boolean | 是否有效 true：材质处于合法可用状态；false：无效或未初始化。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
新建材质
在游戏运行时创建一个全新的空 Material 实例，初始未绑定任何 effect。 新建的材质没有可用内容，后续通常接 初始化材质（绑定 effect 与配置）或 拷贝材质（从已有材质拷贝）。 若要加载已有材质文件，请改用 加载资产（类型选 MATERIAL）。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialCreate |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 实例 新建的空材质实例。连接到 初始化材质 或 拷贝材质 节点为其填充内容。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
重置 Uniforms
调用 material.resetUniforms(clearPasses)，重置材质的 uniform 绑定状态。 clearPasses 说明：
- true（默认）：同时清空 pass 实例，材质将在下次使用前重新编译 pass。
- false：只重置 uniform 数据，保留 pass 实例。 常用于游戏运行时”脏重置”场景：在大幅修改材质配置后，通过 resetUniforms 清除旧的 uniform 绑定，避免残留数据干扰渲染。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | materialResetUniforms |
| 分类 | 资产 |
| 二级分类 | 材质 |
| 分组 | Material |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质 这里需要连接一个已经加载好的 Material 实例。 该端口没有”选择资产”按钮，请先使用以下方式获取 Material 实例： - 加载资产：把”类型”选为 MATERIAL，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Material。 - 新建材质：创建一个空材质实例，再通过 初始化材质 或 拷贝材质 填充内容。 | - | 必填 |
clearPasses | 清空 Pass | 数据 | boolean | 清空 Pass true：同时清空 pass 实例，下次使用前重新编译（默认推荐）；false：只重置 uniform 数据，保留 pass 实例。 | 开关 默认值：true | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
material | 材质 | 数据 | cc.Asset / Material | Material 材质（透传） 把当前操作的 Material 实例原样传出，便于将多个配置节点串联在一起。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。