使用指南
Cocos 组件 / 2D物理 / BoxCollider2D节点
Cocos 组件 / 2D物理 / BoxCollider2D 节点手册，包含 5 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：5
- 分类路径：Cocos 组件 / 2D物理 / BoxCollider2D
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取碰撞体尺寸 | boxCollider2DGetSize | 1 / 1 | 立即继续 |
| 获取碰撞体类型 | boxCollider2DGetType | 1 / 1 | 立即继续 |
| 获取世界四顶点 | boxCollider2DGetWorldPoints | 1 / 1 | 立即继续 |
| 获取所有属性 | boxCollider2DGetProperties | 1 / 3 | 立即继续 |
| 设置碰撞体尺寸 | boxCollider2DSetSize | 3 / 2 | 立即继续 |
获取碰撞体尺寸
获取碰撞体尺寸：返回 BoxCollider2D 的本地空间矩形尺寸。 默认值：Size(1, 1)。 注意：这是本地空间中的矩形宽高，不是半尺寸。最终世界碰撞形状会受节点缩放叠加影响。 用途：常用于读取碰撞箱大小来制作 UI 血条提示、调整命中区域尺寸或实现动态缩放的碰撞体。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | boxCollider2DGetSize |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | BoxCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
boxCollider2D | 矩形碰撞体 | 数据 | cc.Component / BoxCollider2D | 目标 BoxCollider2D 组件 要操作的 BoxCollider2D 碰撞体组件。 BoxCollider2D 是 2D 物理中的矩形碰撞体，用于矩形命中区、触发区、脚底判定与地块碰撞等高频场景。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
size | 尺寸 | 数据 | size | 本地碰撞体尺寸 BoxCollider2D 在本地空间中的矩形宽高。 默认值 Size(1, 1)。不是半尺寸，实际世界碰撞形状还会受节点缩放影响。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取碰撞体类型
获取碰撞体类型：返回 BoxCollider2D 的碰撞体类型枚举（ECollider2DType），对 BoxCollider2D 始终返回 BOX（=1）。 枚举值：
- None（=0）：未指定碰撞体类型
- BOX（=1）：矩形碰撞体（BoxCollider2D 始终为此值）
- CIRCLE（=2）：圆形碰撞体（CircleCollider2D）
- POLYGON（=3）：多边形碰撞体（PolygonCollider2D）
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | boxCollider2DGetType |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | BoxCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
boxCollider2D | 矩形碰撞体 | 数据 | cc.Component / BoxCollider2D | 目标 BoxCollider2D 组件 要操作的 BoxCollider2D 碰撞体组件。 BoxCollider2D 是 2D 物理中的矩形碰撞体，用于矩形命中区、触发区、脚底判定与地块碰撞等高频场景。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
type | 碰撞体类型 | 数据 | enum / ECollider2DType | 碰撞体类型枚举 ECollider2DType 枚举值。 None（=0）=未指定 BOX（=1）=矩形（BoxCollider2D 始终为此值） CIRCLE（=2）=圆形 POLYGON（=3）=多边形 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取世界四顶点
获取世界四顶点：返回 BoxCollider2D 在世界坐标下的四个矩形顶点。 语义：顶点由 size + offset + node.worldMatrix 共同决定，是完整经过世界变换后的矩形角点集合；不是 AABB 包围盒。 典型用途：自定义调试绘制、区域判定辅助与几何可视化，如绘制角色地面判定框、检测敌人是否在矩形区域内。 注意：物理引擎未初始化时返回空数组 []。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | boxCollider2DGetWorldPoints |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | BoxCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
boxCollider2D | 矩形碰撞体 | 数据 | cc.Component / BoxCollider2D | 目标 BoxCollider2D 组件 要操作的 BoxCollider2D 碰撞体组件。 BoxCollider2D 是 2D 物理中的矩形碰撞体，用于矩形命中区、触发区、脚底判定与地块碰撞等高频场景。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
worldPoints | 世界顶点 | 数据 | vector2 / array | 世界坐标四顶点 BoxCollider2D 在世界空间中的矩形四角顶点数组。 由 size + offset + node.worldMatrix 变换得出，不是 AABB 矩形。 物理引擎未初始化时返回空数组。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取所有属性
一次性读出 BoxCollider2D 的全部已节点化属性：本地尺寸（size）、世界四顶点（worldPoints）、碰撞体类型（type）。等同于连接多个 获取类节点，但只用一个节点即可。适合调试快照、状态输出与并行分发场景。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | boxCollider2DGetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | BoxCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
boxCollider2D | 矩形碰撞体 | 数据 | cc.Component / BoxCollider2D | 目标 BoxCollider2D 组件 要操作的 BoxCollider2D 碰撞体组件。 BoxCollider2D 是 2D 物理中的矩形碰撞体，用于矩形命中区、触发区、脚底判定与地块碰撞等高频场景。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
size | 尺寸 | 数据 | size | 本地碰撞体尺寸 BoxCollider2D 在本地空间中的矩形宽高，默认 Size(1, 1)。 | - | 可选 |
worldPoints | 世界顶点 | 数据 | vector2 / array | 世界坐标四顶点 矩形四角顶点数组，由 size + offset + node.worldMatrix 决定，物理引擎未初始化时返回空数组。 | - | 可选 |
type | 碰撞体类型 | 数据 | enum / ECollider2DType | 碰撞体类型枚举 ECollider2DType 枚举值。BoxCollider2D 始终返回 BOX（=1）。 None（=0），BOX（=1），CIRCLE（=2），POLYGON（=3） | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置碰撞体尺寸
设置碰撞体尺寸：设置 BoxCollider2D 的本地空间矩形尺寸。 默认值：Size(1, 1)（宽 1、高 1）。 注意：这是本地空间中的矩形宽高，不是半尺寸。最终世界碰撞形状会受节点缩放叠加影响。 用途：常用于动态改变碰撞体大小，如角色变大时同步放大碰撞箱、变身状态切换碰撞尺寸。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | boxCollider2DSetSize |
| 分类 | Cocos 组件 |
| 二级分类 | 2D物理 |
| 分组 | BoxCollider2D |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
boxCollider2D | 矩形碰撞体 | 数据 | cc.Component / BoxCollider2D | 目标 BoxCollider2D 组件 要操作的 BoxCollider2D 碰撞体组件。 BoxCollider2D 是 2D 物理中的矩形碰撞体，用于矩形命中区、触发区、脚底判定与地块碰撞等高频场景。 | - | 必填 |
size | 尺寸 | 数据 | size | 本地碰撞体尺寸 BoxCollider2D 在本地空间中的矩形宽高。 默认值 Size(1, 1)。不是半尺寸，实际世界碰撞形状还会受节点缩放影响。 | 可编辑控件 默认值：[1,1] | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
boxCollider2D | 矩形碰撞体 | 数据 | cc.Component / BoxCollider2D | 目标 BoxCollider2D 组件 透传当前操作的 BoxCollider2D 组件，便于链式修改碰撞体配置。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。