使用指南
Cocos 组件 / 瓦片地图 / TiledObjectGroup节点
Cocos 组件 / 瓦片地图 / TiledObjectGroup 节点手册，包含 10 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：10
- 分类路径：Cocos 组件 / 瓦片地图 / TiledObjectGroup
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 按名称获取对象 | tiledObjectGroupGetObjectByName | 2 / 3 | 立即继续 |
| 按名称获取自定义属性 | tiledObjectGroupGetCustomProperty | 2 / 2 | 立即继续 |
| 获取对象层名称 | tiledObjectGroupGetGroupName | 1 / 1 | 立即继续 |
| 获取对象列表 | tiledObjectGroupGetObjects | 1 / 2 | 立即继续 |
| 获取全部属性 | tiledObjectGroupGetAllProperties | 1 / 7 | 立即继续 |
| 获取显示偏移 | tiledObjectGroupGetOffset | 1 / 1 | 立即继续 |
| 获取预乘透明 | tiledObjectGroupGetPremultiplyAlpha | 1 / 1 | 立即继续 |
| 获取自定义属性表 | tiledObjectGroupGetCustomProperties | 1 / 1 | 立即继续 |
| 获取子对象偏移 | tiledObjectGroupGetPositionOffset | 1 / 1 | 立即继续 |
| 设置预乘透明 | tiledObjectGroupSetPremultiplyAlpha | 3 / 2 | 立即继续 |
按名称获取对象
按名称查找对象层中的首个匹配对象。 注意：名称区分大小写。多个对象同名时返回第一个匹配对象，与引擎 API 一致。未找到时 object 为 null、index 为 -1、exists 为 false。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | tiledObjectGroupGetObjectByName |
| 分类 | Cocos 组件 |
| 二级分类 | 瓦片地图 |
| 分组 | TiledObjectGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup 对象层组件 这里需要连接一个已挂载的 TiledObjectGroup 组件引用。 TiledObjectGroup 是 TiledMap 对象层组件，可用于读取出生点、触发区域、碰撞区域、自定义属性等地图数据。 该端口没有选择器，请先通过以下方式获取组件： - 获取组件：从节点上获取 TiledObjectGroup 组件。 | - | 必填 |
objectName | 对象名 | 数据 | string | 对象名 要查找的对象名称（区分大小写）。 | 输入框 默认值："" | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
object | 对象 | 数据 | any | TMXObject 对象 找到的首个匹配对象；未找到时为 null。 | - | 可选 |
index | 索引 | 数据 | number | 索引 对象在对象数组中的位置索引；未找到时为 -1。 | - | 可选 |
exists | 是否存在 | 数据 | boolean | 是否存在 true：成功找到指定名称的对象；false：未找到。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
按名称获取自定义属性
按名称读取对象层的单个自定义属性。 注意：属性名区分大小写。未找到时 value 输出 null、exists 输出 false。 属性值可能是字符串或数字，因此输出类型为 OBJECT，避免丢失数字属性。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | tiledObjectGroupGetCustomProperty |
| 分类 | Cocos 组件 |
| 二级分类 | 瓦片地图 |
| 分组 | TiledObjectGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup 对象层组件 这里需要连接一个已挂载的 TiledObjectGroup 组件引用。 TiledObjectGroup 是 TiledMap 对象层组件，可用于读取出生点、触发区域、碰撞区域、自定义属性等地图数据。 该端口没有选择器，请先通过以下方式获取组件： - 获取组件：从节点上获取 TiledObjectGroup 组件。 | - | 必填 |
propertyName | 属性名 | 数据 | string | 属性名 要查找的自定义属性名称（区分大小写）。 | 输入框 默认值："" | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
value | 属性值 | 数据 | object | 属性值 找到的自定义属性值（可能是字符串或数字）；未找到时为 null。 | - | 可选 |
exists | 是否存在 | 数据 | boolean | 是否存在 true：成功找到指定名称的属性；false：未找到。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取对象层名称
读取对象层名称。 可用于调试、分支判断或 UI 展示。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | tiledObjectGroupGetGroupName |
| 分类 | Cocos 组件 |
| 二级分类 | 瓦片地图 |
| 分组 | TiledObjectGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup 对象层组件 这里需要连接一个已挂载的 TiledObjectGroup 组件引用。 TiledObjectGroup 是 TiledMap 对象层组件，可用于读取出生点、触发区域、碰撞区域、自定义属性等地图数据。 该端口没有选择器，请先通过以下方式获取组件： - 获取组件：从节点上获取 TiledObjectGroup 组件。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
groupName | 对象层名称 | 数据 | string | 对象层名称 TMX 文件中 objectgroup 元素的 name 属性值。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取对象列表
读取对象层中全部对象数组及数量。 顺序与 TMX 文件/引擎解析结果一致。每个 TMXObject 包含对象的名称、类型、位置、尺寸等完整信息。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | tiledObjectGroupGetObjects |
| 分类 | Cocos 组件 |
| 二级分类 | 瓦片地图 |
| 分组 | TiledObjectGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup 对象层组件 这里需要连接一个已挂载的 TiledObjectGroup 组件引用。 TiledObjectGroup 是 TiledMap 对象层组件，可用于读取出生点、触发区域、碰撞区域、自定义属性等地图数据。 该端口没有选择器，请先通过以下方式获取组件： - 获取组件：从节点上获取 TiledObjectGroup 组件。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
objects | 对象数组 | 数据 | any / array | 对象数组 对象层中全部对象的数组，顺序与 TMX 文件一致。 | - | 可选 |
objectCount | 对象数量 | 数据 | number | 对象数量 对象数组的元素数量。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取全部属性
一次性读出 TiledObjectGroup 的全部已节点化属性：预乘透明、显示偏移、子对象偏移、对象层名称、自定义属性表、对象数组及数量。 等同于连接多个 获取类节点 和方法调用节点，但只用一个节点即可。面向调试、状态同步与多路分发。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | tiledObjectGroupGetAllProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 瓦片地图 |
| 分组 | TiledObjectGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup 对象层组件 这里需要连接一个已挂载的 TiledObjectGroup 组件引用。 TiledObjectGroup 是 TiledMap 对象层组件，可用于读取出生点、触发区域、碰撞区域、自定义属性等地图数据。 该端口没有选择器，请先通过以下方式获取组件： - 获取组件：从节点上获取 TiledObjectGroup 组件。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
premultiplyAlpha | 预乘透明 | 数据 | boolean | 预乘透明 是否按预乘透明方式混合。 | - | 可选 |
offset | 显示偏移 | 数据 | vector2 | 显示偏移 引擎显示偏移，Y 方向已转换。 | - | 可选 |
positionOffset | 子对象偏移 | 数据 | vector2 | 子对象偏移 TMX 原始偏移值。 | - | 可选 |
groupName | 对象层名称 | 数据 | string | 对象层名称 objectgroup 的 name 属性。 | - | 可选 |
properties | 属性表 | 数据 | object | 自定义属性字典 对象层自定义属性。 | - | 可选 |
objects | 对象数组 | 数据 | any / array | 对象数组 对象层中全部对象。 | - | 可选 |
objectCount | 对象数量 | 数据 | number | 对象数量 对象数组的元素数量。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取显示偏移
读取引擎用于显示对象层的 offset 偏移量。 与 TMX 原始偏移相比，Y 方向已按 Cocos 坐标系转换。适合获取对象层在场景中的实际显示偏移。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | tiledObjectGroupGetOffset |
| 分类 | Cocos 组件 |
| 二级分类 | 瓦片地图 |
| 分组 | TiledObjectGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup 对象层组件 这里需要连接一个已挂载的 TiledObjectGroup 组件引用。 TiledObjectGroup 是 TiledMap 对象层组件，可用于读取出生点、触发区域、碰撞区域、自定义属性等地图数据。 该端口没有选择器，请先通过以下方式获取组件： - 获取组件：从节点上获取 TiledObjectGroup 组件。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
offset | 显示偏移 | 数据 | vector2 | 显示偏移 引擎用于显示对象层的偏移量，Y 方向已按 Cocos 坐标系转换。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取预乘透明
读取对象层组件的 premultiplyAlpha 属性。 该属性控制对象层中图片对象渲染时是否按预乘透明方式混合，主要影响图片对象边缘的透明表现。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | tiledObjectGroupGetPremultiplyAlpha |
| 分类 | Cocos 组件 |
| 二级分类 | 瓦片地图 |
| 分组 | TiledObjectGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup 对象层组件 这里需要连接一个已挂载的 TiledObjectGroup 组件引用。 TiledObjectGroup 是 TiledMap 对象层组件，可用于读取出生点、触发区域、碰撞区域、自定义属性等地图数据。 该端口没有选择器，请先通过以下方式获取组件： - 获取组件：从节点上获取 TiledObjectGroup 组件。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
premultiplyAlpha | 预乘透明 | 数据 | boolean | 预乘透明 是否按预乘透明方式混合对象层中的图片对象。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取自定义属性表
读取对象层级自定义属性字典。 由于键名来自 Tiled 文件游戏运行时数据，无法静态枚举，输出类型为 OBJECT。可配合后续字典/属性读取节点按键名访问。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | tiledObjectGroupGetCustomProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 瓦片地图 |
| 分组 | TiledObjectGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup 对象层组件 这里需要连接一个已挂载的 TiledObjectGroup 组件引用。 TiledObjectGroup 是 TiledMap 对象层组件，可用于读取出生点、触发区域、碰撞区域、自定义属性等地图数据。 该端口没有选择器，请先通过以下方式获取组件： - 获取组件：从节点上获取 TiledObjectGroup 组件。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
properties | 属性表 | 数据 | object | 自定义属性字典 对象层在 Tiled 编辑器中定义的所有自定义属性，键值对形式。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取子对象偏移
读取从 TMX 对象层解析出的原始子对象偏移。 适合还原 Tiled 编辑器中的对象层偏移配置，与 获取显示偏移 的区别在于该值未经引擎坐标系转换。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | tiledObjectGroupGetPositionOffset |
| 分类 | Cocos 组件 |
| 二级分类 | 瓦片地图 |
| 分组 | TiledObjectGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup 对象层组件 这里需要连接一个已挂载的 TiledObjectGroup 组件引用。 TiledObjectGroup 是 TiledMap 对象层组件，可用于读取出生点、触发区域、碰撞区域、自定义属性等地图数据。 该端口没有选择器，请先通过以下方式获取组件： - 获取组件：从节点上获取 TiledObjectGroup 组件。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
positionOffset | 子对象偏移 | 数据 | vector2 | 子对象偏移 TMX 对象层解析出的原始偏移值，未经引擎坐标系转换。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置预乘透明
游戏运行时修改对象层组件的 premultiplyAlpha 属性。 修改后会影响后续图片对象材质混合逻辑，不重建对象层，只设置组件属性。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | tiledObjectGroupSetPremultiplyAlpha |
| 分类 | Cocos 组件 |
| 二级分类 | 瓦片地图 |
| 分组 | TiledObjectGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup 对象层组件 这里需要连接一个已挂载的 TiledObjectGroup 组件引用。 TiledObjectGroup 是 TiledMap 对象层组件，可用于读取出生点、触发区域、碰撞区域、自定义属性等地图数据。 该端口没有选择器，请先通过以下方式获取组件： - 获取组件：从节点上获取 TiledObjectGroup 组件。 | - | 必填 |
premultiplyAlpha | 预乘透明 | 数据 | boolean | 预乘透明 要设置的预乘透明开关值。 | 开关 默认值：false | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
tiledObjectGroup | 对象层 | 数据 | cc.Component / TiledObjectGroup | TiledObjectGroup（透传） 把当前操作的 TiledObjectGroup 组件原样传出，便于将多个节点串联在一起。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。