使用指南
Cocos 组件 / 2D物理 / PolygonCollider2D节点
Cocos 组件 / 2D物理 / PolygonCollider2D 节点手册，包含 7 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：7
- 分类路径：Cocos 组件 / 2D物理 / PolygonCollider2D
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取局部顶点数组 | polygonCollider2DGetPoints | 1 / 1 | 立即继续 |
| 获取碰撞体类型 | polygonCollider2DGetType | 1 / 1 | 立即继续 |
| 获取世界顶点数组 | polygonCollider2DGetWorldPoints | 1 / 1 | 立即继续 |
| 获取所有属性 | polygonCollider2DGetProperties | 1 / 4 | 立即继续 |
| 获取重建阈值 | polygonCollider2DGetThreshold | 1 / 1 | 立即继续 |
| 设置局部顶点数组 | polygonCollider2DSetPoints | 3 / 2 | 立即继续 |
| 设置重建阈值 | polygonCollider2DSetThreshold | 3 / 2 | 立即继续 |
获取局部顶点数组
获取局部顶点数组：返回 PolygonCollider2D 在本地坐标系下的多边形顶点数组。 默认值：4 个顶点 [(-1,-1), (1,-1), (1,1), (-1,1)]（矩形外框）。 语义：这是多边形的几何源数据，顶点顺序决定边的连接方式；复杂轮廓可能被物理后端拆分为多个凸多边形。 用途：用于读取自定义碰撞轮廓的顶点数据，或实现不规则的碰撞检测区域。 建议： 传入不自交、首尾不重复的顶点序列，以获得稳定的物理形状。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | polygonCollider2DGetPoints |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | PolygonCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
polygonCollider2D | 多边形碰撞体 | 数据 | cc.Component / PolygonCollider2D | 目标 PolygonCollider2D 组件 要操作的 PolygonCollider2D 碰撞体组件。 PolygonCollider2D 是 2D 物理中的多边形碰撞体，适合不规则地形、斜坡、自定义命中轮廓与复杂触发区。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
points | 局部顶点 | 数据 | vector2 / array | 局部多边形顶点数组 本地坐标系下的多边形顶点数组，默认 4 顶点矩形轮廓。 顶点顺序决定边连接方式；写入后会改变碰撞体几何外形。 建议提供不自交、首尾不重复的轮廓。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取碰撞体类型
获取碰撞体类型：返回 PolygonCollider2D 的碰撞体类型枚举（ECollider2DType），对 PolygonCollider2D 始终返回 POLYGON（=3）。 可用于类型自描述、统一枚举链路与跨碰撞体分支判断。 枚举值：
- None（=0）：未指定碰撞体类型
- BOX（=1）：矩形碰撞体（BoxCollider2D）
- CIRCLE（=2）：圆形碰撞体（CircleCollider2D）
- POLYGON（=3）：多边形碰撞体（PolygonCollider2D 始终为此值）
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | polygonCollider2DGetType |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | PolygonCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
polygonCollider2D | 多边形碰撞体 | 数据 | cc.Component / PolygonCollider2D | 目标 PolygonCollider2D 组件 要操作的 PolygonCollider2D 碰撞体组件。 PolygonCollider2D 是 2D 物理中的多边形碰撞体，适合不规则地形、斜坡、自定义命中轮廓与复杂触发区。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
type | 碰撞体类型 | 数据 | enum / ECollider2DType | 碰撞体类型枚举 ECollider2DType 枚举值。 None（=0）=未指定 BOX（=1）=矩形 CIRCLE（=2）=圆形 POLYGON（=3）=多边形（PolygonCollider2D 始终为此值） | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取世界顶点数组
获取世界顶点数组：返回 PolygonCollider2D 在世界坐标下的多边形顶点数组。 语义：最终受本地点集（points）、偏移（offset）与节点世界变换共同影响。这不是 worldAABB 包围盒。 典型用途：调试绘制、区域轮廓可视化与不规则碰撞区域的命中判定辅助。 注意：物理引擎未初始化时返回空数组 []。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | polygonCollider2DGetWorldPoints |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | PolygonCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
polygonCollider2D | 多边形碰撞体 | 数据 | cc.Component / PolygonCollider2D | 目标 PolygonCollider2D 组件 要操作的 PolygonCollider2D 碰撞体组件。 PolygonCollider2D 是 2D 物理中的多边形碰撞体，适合不规则地形、斜坡、自定义命中轮廓与复杂触发区。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
worldPoints | 世界顶点 | 数据 | vector2 / array | 世界坐标多边形顶点数组 经世界变换后的顶点数组，受本地点集、偏移与世界矩阵共同影响。 不是 worldAABB，物理引擎未初始化时返回空数组。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取所有属性
一次性读出 PolygonCollider2D 的全部已节点化属性：重建阈值（threshold）、局部顶点数组（points）、世界顶点数组（worldPoints）、碰撞体类型（type）。等同于连接多个 获取类节点，但只用一个节点即可。适合调试、序列化与并行分发场景。 注意：threshold 为点集重建阈值（不是摩擦/碰撞阈值）；type 对 PolygonCollider2D 始终为 POLYGON（值 3）。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | polygonCollider2DGetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | PolygonCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
polygonCollider2D | 多边形碰撞体 | 数据 | cc.Component / PolygonCollider2D | 目标 PolygonCollider2D 组件 要操作的 PolygonCollider2D 碰撞体组件。 PolygonCollider2D 是 2D 物理中的多边形碰撞体，适合不规则地形、斜坡、自定义命中轮廓与复杂触发区。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
threshold | 重建阈值 | 数据 | number | 点集重建容差阈值 编辑器自动重建顶点时使用的容差/简化阈值，默认 1。不是摩擦阈值，也不是碰撞触发阈值。 | - | 可选 |
points | 局部顶点 | 数据 | vector2 / array | 局部多边形顶点数组 本地坐标系下的多边形顶点数组，默认 4 顶点矩形轮廓。 | - | 可选 |
worldPoints | 世界顶点 | 数据 | vector2 / array | 世界坐标多边形顶点数组 经世界变换后的顶点数组，受本地点集、偏移与世界矩阵共同影响，物理引擎未初始化时返回空数组。 | - | 可选 |
type | 碰撞体类型 | 数据 | enum / ECollider2DType | 碰撞体类型枚举 ECollider2DType 枚举值。PolygonCollider2D 始终返回 POLYGON（=3）。 None（=0），BOX（=1），CIRCLE（=2），POLYGON（=3） | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取重建阈值
获取重建阈值：返回 PolygonCollider2D 的点集重建容差阈值（threshold）。 默认值：1。 注意：threshold 是编辑器”Regenerate Points”功能在自动重建多边形点集时使用的容差/简化阈值，不是摩擦阈值，也不是碰撞触发阈值。仅修改此数值不会自动重算点集，需要配合编辑器重建操作才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | polygonCollider2DGetThreshold |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | PolygonCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
polygonCollider2D | 多边形碰撞体 | 数据 | cc.Component / PolygonCollider2D | 目标 PolygonCollider2D 组件 要操作的 PolygonCollider2D 碰撞体组件。 PolygonCollider2D 是 2D 物理中的多边形碰撞体，适合不规则地形、斜坡、自定义命中轮廓与复杂触发区。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
threshold | 重建阈值 | 数据 | number | 点集重建容差阈值 编辑器自动重建多边形顶点时使用的容差/简化阈值，默认值 1，最小值 0，步进 0.1。 不是摩擦阈值，也不是碰撞触发阈值。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置局部顶点数组
设置局部顶点数组：设置 PolygonCollider2D 在本地坐标系下的多边形顶点数组。 默认值：4 个顶点 [(-1,-1), (1,-1), (1,1), (-1,1)]。 语义：写入后会改变碰撞体几何外形；复杂轮廓可能被物理后端拆分为多个凸多边形。 用途：用于游戏运行时改变碰撞轮廓，如角色变形、地面塌陷、动态创建不规则障碍物。 注意：需从数组变量或数组构造节点传入二维向量数组，不提供内联编辑控件。建议提供不自交、首尾不重复的顶点序列。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | polygonCollider2DSetPoints |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | PolygonCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
polygonCollider2D | 多边形碰撞体 | 数据 | cc.Component / PolygonCollider2D | 目标 PolygonCollider2D 组件 要操作的 PolygonCollider2D 碰撞体组件。 PolygonCollider2D 是 2D 物理中的多边形碰撞体，适合不规则地形、斜坡、自定义命中轮廓与复杂触发区。 | - | 必填 |
points | 局部顶点 | 数据 | vector2 / array | 局部多边形顶点数组 本地坐标系下的多边形顶点数组，顶点顺序决定边连接方式。 写入后会改变碰撞体几何外形。 必须通过数组变量或数组构造节点传入，无内联编辑控件。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
polygonCollider2D | 多边形碰撞体 | 数据 | cc.Component / PolygonCollider2D | 目标 PolygonCollider2D 组件 透传当前操作的 PolygonCollider2D 组件，便于链式修改多边形碰撞体配置。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置重建阈值
设置重建阈值：设置 PolygonCollider2D 的点集重建容差阈值（threshold）。 默认值：1，最小值 0，步进 0.1。 注意：threshold 是编辑器”Regenerate Points”功能在自动重建多边形点集时使用的容差/简化阈值，不是摩擦阈值，也不是碰撞触发阈值。仅修改此数值不会自动重算点集。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | polygonCollider2DSetThreshold |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | PolygonCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
polygonCollider2D | 多边形碰撞体 | 数据 | cc.Component / PolygonCollider2D | 目标 PolygonCollider2D 组件 要操作的 PolygonCollider2D 碰撞体组件。 PolygonCollider2D 是 2D 物理中的多边形碰撞体，适合不规则地形、斜坡、自定义命中轮廓与复杂触发区。 | - | 必填 |
threshold | 重建阈值 | 数据 | number | 点集重建容差阈值 编辑器自动重建多边形顶点时使用的容差/简化阈值，默认值 1，最小值 0，步进 0.1。 不是摩擦阈值，也不是碰撞触发阈值。 | 输入框 默认值：1 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
polygonCollider2D | 多边形碰撞体 | 数据 | cc.Component / PolygonCollider2D | 目标 PolygonCollider2D 组件 透传当前操作的 PolygonCollider2D 组件，便于链式修改多边形碰撞体配置。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。