使用指南
资产 / 网格 / Mesh节点
资产 / 网格 / Mesh 节点手册，包含 19 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
读取和验证 Cocos 资产对象，把图片、音频、材质、Prefab 等资源接入工作流逻辑。
覆盖范围
- 节点数量：19
- 分类路径：资产 / 网格 / Mesh
典型使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
通用注意事项
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 读取顶点属性 | meshReadAttribute | 3 / 1 | 立即继续 |
| 读取属性格式 | meshReadAttributeFormat | 3 / 1 | 立即继续 |
| 读取索引数据 | meshReadIndices | 2 / 1 | 立即继续 |
| 更新动态子网格 | meshUpdateSubMesh | 4 / 2 | 立即继续 |
| 合并网格 | meshMerge | 5 / 3 | 立即继续 |
| 获取 Mesh 哈希 | meshGetHash | 1 / 1 | 立即继续 |
| 获取 Mesh 结构体 | meshGetStruct | 1 / 1 | 立即继续 |
| 获取 Mesh 数据 | meshGetData | 1 / 1 | 立即继续 |
| 获取骨骼缓冲索引 | meshGetJointBufferIndices | 1 / 1 | 立即继续 |
| 获取数据访问许可 | meshGetAllowDataAccess | 1 / 1 | 立即继续 |
| 获取所有属性 | meshGetProperties | 1 / 9 | 立即继续 |
| 获取渲染子网格列表 | meshGetRenderingSubMeshes | 1 / 1 | 立即继续 |
| 获取子网格数量 | meshGetSubMeshCount | 1 / 1 | 立即继续 |
| 获取最大顶点坐标 | meshGetMaxPosition | 1 / 1 | 立即继续 |
| 获取最小顶点坐标 | meshGetMinPosition | 1 / 1 | 立即继续 |
| 设置数据访问许可 | meshSetAllowDataAccess | 3 / 2 | 立即继续 |
| 校验网格可合并性 | meshValidateMergingMesh | 2 / 1 | 立即继续 |
| 新建网格资产 | meshCreate | 1 / 2 | 立即继续 |
| 重置 Mesh 结构 | meshReset | 3 / 2 | 立即继续 |
读取顶点属性
调用 mesh.readAttribute(primitiveIndex, attributeName)，读取指定子网格中、指定顶点属性语义对应的 TypedArray 数据。 返回值：不同属性对应不同数组类型（如 ATTR_POSITION 返回 Float32Array，ATTR_JOINTS 可能返回 Uint8Array 或 Uint16Array）。首版以引用语义透传，不做额外展开。 前提条件：allowDataAccess 需为 true，否则返回 null。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshReadAttribute |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
primitiveIndex | 子网格索引 | 数据 | number | 子网格索引 要查询的子网格（Primitive）索引，从 0 开始。 | 输入框 默认值：0 | 必填 |
attributeName | 属性名称 | 数据 | enum / gfx.AttributeName | 顶点属性语义（gfx.AttributeName） 用于指定要读取的顶点属性，如 ATTR_POSITION（顶点位置）、ATTR_NORMAL（法线）、ATTR_UV（纹理坐标）等。从下拉选择器中选择。 | 下拉选择 默认值：“ATTR_POSITION” | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
attributeData | 属性数据 | 数据 | reference / TypedArray | 顶点属性数据 指定子网格中指定属性的 TypedArray 引用（如 Float32Array / Uint8Array / Uint16Array 等）。allowDataAccess = false 时返回 null。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
读取属性格式
读取指定子网格中指定顶点属性的格式信息（gfx.FormatInfo）。 gfx.FormatInfo 描述了属性的存储格式，可进一步读取：
- size：每个元素的字节大小
- count：分量数（如 Vec3 = 3）
- type：元素基础类型（float/half/uint8 等）
- hasAlpha / isCompressed / isNormalized：格式特性标志 若指定属性在该子网格中不存在，返回 null。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshReadAttributeFormat |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
primitiveIndex | 子网格索引 | 数据 | number | 子网格索引 要查询的子网格（Primitive）索引，从 0 开始。 | 输入框 默认值：0 | 必填 |
attributeName | 属性名称 | 数据 | enum / gfx.AttributeName | 顶点属性语义（gfx.AttributeName） 要查询格式的顶点属性。 | 下拉选择 默认值：“ATTR_POSITION” | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
formatInfo | 格式信息 | 数据 | reference / gfx.FormatInfo | gfx.FormatInfo 指定属性的格式信息，包含字节大小、分量数、基础类型与格式标志。属性不存在时为 null。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
读取索引数据
读取指定子网格的索引缓冲数据。 返回值类型取决于底层索引步长：
- Uint8Array：索引步长 1 字节（不超过 255 个顶点）
- Uint16Array：索引步长 2 字节（不超过 65535 个顶点，最常见）
- Uint32Array：索引步长 4 字节（超大网格） 首版以引用语义透传结果，不保证在画布内可进一步细粒度编辑。前提条件：allowDataAccess 需为 true。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshReadIndices |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
primitiveIndex | 子网格索引 | 数据 | number | 子网格索引 要读取索引的子网格（Primitive）索引，从 0 开始。 | 输入框 默认值：0 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
indices | 索引数据 | 数据 | reference / TypedArray | 索引数据 类型取决于底层索引步长。allowDataAccess = false 时返回 null。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
更新动态子网格
调用 mesh.updateSubMesh(primitiveIndex, dynamicGeometry)，更新指定子网格的动态几何数据。 仅适用于动态 Mesh（即通过包含 IDynamicInfo 的 ICreateInfo 创建的 Mesh）。若目标不是动态 Mesh，引擎将遵循现有安全行为而不会崩溃。 IDynamicGeometry 至少需要 positions（顶点位置）；indices 与边界（minPos/maxPos）按场景决定是否提供。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshUpdateSubMesh |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
primitiveIndex | 子网格索引 | 数据 | number | 子网格索引 要更新的子网格（Primitive）的索引，从 0 开始。使用 获取子网格数量 确认有效范围。 | 输入框 默认值：0 | 必填 |
dynamicGeometry | 动态几何数据 | 数据 | struct / IDynamicGeometry | IDynamicGeometry 动态几何更新数据，至少需要 positions（顶点位置）。indices 与边界（minPos/maxPos）按场景决定是否提供。使用 构造结构体 构造此结构体。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 实例（透传） 把当前操作的 Mesh 实例原样传出，便于将多个配置节点串联在一起。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
合并网格
调用 mesh.merge(otherMesh, worldMatrix, validate)，将另一个网格合并到当前网格中。 可选参数说明：
- worldMatrix（可选）：目标网格的世界矩阵，若提供则在合并前应用坐标变换
- validate（可选，默认 false）：是否在合并前自动校验布局兼容性。建议先用 MeshValidateMergingMesh 手动校验，再执行合并。 输出的 merged 表示本次合并是否成功（validate = true 且不兼容时会返回 false）。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshMerge |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
otherMesh | 待合并网格 | 数据 | cc.Asset / Mesh | 待合并网格 要合并到当前 Mesh 中的目标网格。 | - | 必填 |
worldMatrix | 世界矩阵（可选） | 数据 | cc.Asset / Mat4 | 世界矩阵（可选） 待合并网格的世界矩阵。若提供，合并前会对其顶点坐标应用此矩阵变换。不提供则直接合并。 | - | 可选 |
validate | 校验兼容性 | 数据 | boolean | 校验兼容性 true：合并前自动校验布局兼容性，不兼容时跳过合并并返回 merged = false；false（默认）：直接合并，不做前置校验。建议提前使用 MeshValidateMergingMesh 手动校验。 | 开关 默认值：false | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 实例（透传） 把当前操作的 Mesh 实例原样传出，便于将多个配置节点串联在一起。 | - | 可选 |
merged | 是否成功 | 数据 | boolean | 是否成功 true：合并成功；false：validate = true 且布局不兼容时返回 false。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取 Mesh 哈希
读取网格资产的哈希值（hash: number）。 该哈希由引擎在序列化时生成，可用于快速比对两个网格资产是否具有相同的拓扑结构。不同内容的 Mesh 哈希值通常不同，但哈希相同不保证内容完全一致。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshGetHash |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
hash | 哈希值 | 数据 | number | 网格哈希值 由引擎在序列化时生成，可用于快速比对网格拓扑结构是否相同。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取 Mesh 结构体
读取网格资产的结构描述（struct: Mesh.IStruct）。 Mesh.IStruct 包含顶点束数量、属性格式、子网格定义、骨骼绑定、Morph 目标等完整网格拓扑信息。可继续使用 拆分结构体 节点拆解其内部字段。 注意：struct 是网格的描述性元数据，不包含实际二进制顶点数据——后者在 data 属性中，可通过 获取 Mesh 数据 读取。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshGetStruct |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
struct | 网格结构体 | 数据 | struct / IStruct | Mesh.IStruct 网格的完整结构描述，包含顶点束、属性格式、子网格定义等拓扑信息。使用 拆分结构体 节点拆解内部字段。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取 Mesh 数据
读取网格资产的原始二进制顶点数据（data: Uint8Array）。 该缓冲区存储所有顶点束的原始字节，可结合 Mesh.IStruct 中的属性格式与偏移量手动解析特定属性。对于按属性名读取，推荐使用 读取顶点属性 节点。 注意：若 allowDataAccess 为 false 且网格已在 GPU 上传完成，data 可能为空——请先用 获取数据访问许可 确认状态，或在访问前确保 allowDataAccess 为 true。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshGetData |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
data | 二进制数据 | 数据 | reference / Uint8Array | 原始顶点数据 网格所有顶点束的原始字节缓冲区。allowDataAccess = false 且 GPU 上传完成后可能为空。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取骨骼缓冲索引
读取网格的骨骼缓冲索引数组（jointBufferIndices: number[]）。 该数组描述了每个子网格（Primitive）对应的骨骼缓冲索引，供 SkinnedMeshRenderer 建立骨骼与顶点数据的映射关系。 若网格不含蒙皮数据，返回空数组。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshGetJointBufferIndices |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
jointBufferIndices | 骨骼缓冲索引 | 数据 | number / array | 骨骼缓冲索引数组 每个子网格对应的骨骼缓冲索引，供 SkinnedMeshRenderer 使用。不含蒙皮数据时为空数组。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取数据访问许可
读取网格资产的 allowDataAccess 状态。 当为 true 时，CPU 侧 data 缓冲区保持可读；当为 false 时，静态网格在 GPU 上传完成后可能释放 CPU 侧数据。这会影响后续 读取顶点属性、读取索引数据、获取 Mesh 数据 等读取链路的可用性。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshGetAllowDataAccess |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
allowDataAccess | 允许数据访问 | 数据 | boolean | allowDataAccess true：CPU 侧数据可读；false：静态网格 GPU 上传后可能释放 CPU 侧数据，影响后续属性/索引读取。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取所有属性
一次性读出网格资产的全部已节点化属性：
- struct：网格结构描述（Mesh.IStruct）
- data：原始顶点二进制数据（Uint8Array 引用）
- hash：网格哈希值
- allowDataAccess：CPU 侧数据访问许可
- renderingSubMeshes：渲染子网格数组（REFERENCE）
- subMeshCount：子网格数量
- minPosition：AABB 最小角坐标
- maxPosition：AABB 最大角坐标
- jointBufferIndices：骨骼缓冲索引数组 适合需要同时取用多项信息的场景，等同于分别连接多个单字段读取节点。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshGetProperties |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
struct | 网格结构体 | 数据 | struct / IStruct | Mesh.IStruct 网格的完整结构描述。 | - | 可选 |
data | 二进制数据 | 数据 | reference / Uint8Array | 原始顶点数据 allowDataAccess = false 后可能为空。 | - | 可选 |
hash | 哈希值 | 数据 | number | 网格哈希值 由引擎在序列化时生成。 | - | 可选 |
allowDataAccess | 允许数据访问 | 数据 | boolean | allowDataAccess true：CPU 侧数据可读；false：可能已释放 CPU 侧数据。 | - | 可选 |
renderingSubMeshes | 渲染子网格列表 | 数据 | reference / array / RenderingSubMesh | 渲染子网格数组 访问会触发引擎懒初始化。 | - | 可选 |
subMeshCount | 子网格数量 | 数据 | number | 子网格数量 网格中包含的 Primitive 数量。 | - | 可选 |
minPosition | 最小坐标 | 数据 | vector3 | AABB 最小角坐标 未定义 AABB 时为 null。 | - | 可选 |
maxPosition | 最大坐标 | 数据 | vector3 | AABB 最大角坐标 未定义 AABB 时为 null。 | - | 可选 |
jointBufferIndices | 骨骼缓冲索引 | 数据 | number / array | 骨骼缓冲索引数组 不含蒙皮数据时为空数组。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取渲染子网格列表
读取网格资产的渲染子网格数组（renderingSubMeshes: RenderingSubMesh[]）。 每个 RenderingSubMesh 代表一个可渲染子网格单元，内部包含：
- 顶点缓冲（vertexBuffers）：GPU 侧顶点数据
- 索引缓冲（indexBuffer）：GPU 侧索引数据
- 图元类型（primitiveMode）：三角形、线段等
- 绘制范围（drawInfo）：顶点数量、索引数量、偏移等 注意：访问此属性会触发引擎的懒初始化（initialize()），可能创建 GPU 相关对象——这是引擎现有行为，不是节点额外副作用。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshGetRenderingSubMeshes |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
renderingSubMeshes | 渲染子网格列表 | 数据 | reference / array / RenderingSubMesh | 渲染子网格数组 每个元素代表一个可渲染子网格，包含顶点缓冲、索引缓冲、图元类型与绘制范围。访问会触发引擎懒初始化。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取子网格数量
读取网格资产中的子网格（Primitive）数量，即 struct.primitives.length。 一个 Mesh 可包含多个子网格，每个子网格对应一个独立的渲染单元（通常对应一个材质槽）。可先读取数量再决定按索引查询的有效范围。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshGetSubMeshCount |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
subMeshCount | 子网格数量 | 数据 | number | 子网格数量 网格中包含的 Primitive 数量，与材质槽数量对应。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取最大顶点坐标
读取网格的局部空间 AABB 最大角坐标（maxPosition: Vec3）。 若网格未定义 AABB（maxPosition 为 null），则输出 null。通常用于网格包围盒判断、剔除计算或程序化几何对齐。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshGetMaxPosition |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
maxPosition | 最大坐标 | 数据 | vector3 | 最大顶点坐标 网格局部空间 AABB 的最大角。未定义 AABB 时为 null。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
获取最小顶点坐标
读取网格的局部空间 AABB 最小角坐标（minPosition: Vec3）。 若网格未定义 AABB（minPosition 为 null），则输出 null。通常用于网格包围盒判断、剔除计算或程序化几何对齐。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshGetMinPosition |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
minPosition | 最小坐标 | 数据 | vector3 | 最小顶点坐标 网格局部空间 AABB 的最小角。未定义 AABB 时为 null。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
设置数据访问许可
设置网格资产的 allowDataAccess 属性，控制 CPU 侧数据的可读性。 重要提示：将此值设为 false 后，静态网格在 GPU 上传完成时可能自动释放 CPU 侧 data 缓冲区。这将使后续对 读取顶点属性、读取索引数据、获取 Mesh 数据 等节点的读取调用失效——返回空数据或 null。 若你需要游戏运行时读取顶点属性，请确保在 GPU 上传前将此值设为 true。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshSetAllowDataAccess |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
allowDataAccess | 允许数据访问 | 数据 | boolean | allowDataAccess true：保持 CPU 侧数据可读；false：GPU 上传完成后可能自动释放 CPU 侧数据，影响后续读取节点。 | 开关 默认值：true | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 实例（透传） 把当前操作的 Mesh 实例原样传出，便于将多个配置节点串联在一起。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
校验网格可合并性
调用 mesh.validateMergingMesh(otherMesh)，校验目标 Mesh 与给定 Mesh 是否具备布局兼容性，即是否可安全合并。 校验内容包括：
- 顶点束数量一致
- 顶点属性格式（名称、格式、类型）逐一对应
- 子网格（Primitive）数量相同
- 每个子网格的 primitiveMode 匹配
- 索引布局（有索引/无索引）兼容 返回 true 表示兼容，可继续使用 MeshMerge 节点执行合并；返回 false 表示布局不兼容，合并会失败。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshValidateMergingMesh |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
otherMesh | 待合并网格 | 数据 | cc.Asset / Mesh | 待合并网格 要与当前 Mesh 进行布局兼容性校验的目标网格。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
canMerge | 可合并 | 数据 | boolean | 可合并 true：两个网格布局兼容，可安全合并；false：布局不兼容，合并会失败。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
新建网格资产
在游戏运行时创建一个全新的空网格资产实例，不包含任何顶点或子网格数据。 通常配合 重置网格 或 更新子网格 节点来填充网格内容，实现程序化网格构建。若只是加载已有网格资产，请改用 加载资产（类型选 MESH）。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshCreate |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 实例 新建的空网格资产实例。连接到 重置网格 / 更新子网格 等节点继续配置。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。
重置 Mesh 结构
调用 mesh.reset(createInfo)，重置当前 Mesh 的完整结构与二进制数据。 Mesh.ICreateInfo 包含新的结构描述（struct）与对应的二进制数据（data），执行后会替换 Mesh 现有的所有内容。 通常用于程序化网格构建：先创建空 Mesh（MeshCreate），再用 reset 填充内容。重置后如需读取顶点属性，确保 allowDataAccess = true。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | meshReset |
| 分类 | 资产 |
| 二级分类 | 网格 |
| 分组 | Mesh |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 网格资产 这里需要连接一个已经加载好的 Mesh 实例。 该端口没有”选择网格资产”按钮，请先使用以下方式获取 Mesh 实例： - 加载资产：把”类型”选为 MESH，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 Mesh。 - 新建网格资产：在游戏运行时创建空 Mesh 实例。 | - | 必填 |
createInfo | 创建信息 | 数据 | struct / ICreateInfo | Mesh.ICreateInfo 包含新的网格结构描述（struct）与二进制数据（data）。使用 构造结构体 节点构造此结构体。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
mesh | 网格资产 | 数据 | cc.Asset / Mesh | Mesh 实例（透传） 把当前操作的 Mesh 实例原样传出，便于将多个配置节点串联在一起。 | - | 可选 |
使用场景
- 读取音频时长、图片尺寸、材质参数等资产信息
- 校验加载结果是否可用
- 创建或传递特定类型的资产实例
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 资产节点通常要求连接已加载的资产实例。
- 父类 Asset 生命周期能力应优先使用通用资产管理节点。