Cocos 组件 / 3D物理 / CapsuleCollider节点

学习目标

访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。

覆盖范围

• 节点数量：11
• 分类路径：Cocos 组件 / 3D物理 / CapsuleCollider

典型使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

通用注意事项

• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
• 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。

节点索引

节点	节点 ID	输入/输出	执行方式
获取朝向轴	capsuleColliderGetDirection	1 / 1	立即继续
获取球半径	capsuleColliderGetRadius	1 / 1	立即继续
获取全部属性	capsuleColliderGetProperties	1 / 5	立即继续
获取世界高度	capsuleColliderGetWorldHeight	1 / 1	立即继续
获取圆柱高度	capsuleColliderGetCylinderHeight	1 / 1	立即继续
获取总高度	capsuleColliderGetHeight	1 / 1	立即继续
设置朝向轴	capsuleColliderSetDirection	3 / 2	立即继续
设置球半径	capsuleColliderSetRadius	3 / 2	立即继续
设置全部属性	capsuleColliderSetProperties	6 / 2	立即继续
设置圆柱高度	capsuleColliderSetCylinderHeight	3 / 2	立即继续
设置总高度	capsuleColliderSetHeight	3 / 2	立即继续

获取朝向轴

获取胶囊朝向轴（direction）：返回胶囊碰撞体的轴向朝向，决定胶囊沿哪个轴延伸。 取值：0（X_AXIS）=X 轴方向，1（Y_AXIS）=Y 轴方向，2（Z_AXIS）=Z 轴方向。 默认值 1（Y 轴）最常用于竖向角色碰撞体；水平滚动物体通常使用 0（X 轴）或 2（Z 轴）。

节点信息

字段	值
节点 ID	capsuleColliderGetDirection
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
direction	朝向轴	数据	enum / physics.EAxisDirection	胶囊朝向轴（EAxisDirection） 取值：0（X_AXIS）=X 轴方向，1（Y_AXIS）=Y 轴方向，2（Z_AXIS）=Z 轴方向。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取球半径

获取胶囊体球半径（radius）：返回胶囊碰撞体本地空间的球半径。 这是两端半球的半径，不含中段圆柱高度。节点缩放会叠加影响最终碰撞体在世界中的大小。 常用于读取角色碰撞体的胖瘦，用于条件判断或动态调整碰撞区域。

节点信息

字段	值
节点 ID	capsuleColliderGetRadius
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
radius	球半径	数据	number	球半径（本地空间） 胶囊两端半球的半径。节点缩放会叠加影响最终碰撞体在世界中的大小。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取全部属性

一次性读取 CapsuleCollider 全部属性：聚合读取 radius、cylinderHeight、direction、height、worldHeight。 等同于连接多个 获取类节点，适合调试、快照记录或并行分发。 注意：height = radius × 2 + cylinderHeight，三者存在关联。worldHeight 为只读推导值。

节点信息

字段	值
节点 ID	capsuleColliderGetProperties
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
radius	球半径	数据	number	胶囊两端半球的半径（本地空间）。负值写入时引擎自动转正。	-	可选
cylinderHeight	圆柱高度	数据	number	胶囊中段圆柱高度（本地空间），不含两端半球。总高度 = cylinderHeight + radius × 2。	-	可选
direction	朝向轴	数据	enum / physics.EAxisDirection	胶囊朝向轴。取值：0（X_AXIS）=X 轴方向，1（Y_AXIS）=Y 轴方向，2（Z_AXIS）=Z 轴方向。	-	可选
height	总高度	数据	number	胶囊总高度（本地空间）：height = radius × 2 + cylinderHeight。	-	可选
worldHeight	世界高度	数据	number	胶囊世界空间高度（只读），受 direction 与节点世界缩放影响。不可直接设置。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取世界高度

获取世界空间高度（worldHeight）：返回胶囊碰撞体在世界空间中沿朝向轴方向的高度（只读）。 此值为推导值，受 direction 与节点缩放影响。如需调整世界空间高度，应修改 height 或 radius。 常用于了解角色碰撞体在世界中的实际高度，用于碰撞检测或空间判断。

节点信息

字段	值
节点 ID	capsuleColliderGetWorldHeight
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
worldHeight	世界高度	数据	number	世界空间高度（只读） 胶囊沿朝向轴在世界空间中的高度，受 direction 与节点世界缩放影响。不可直接设置。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取圆柱高度

获取中段圆柱高度（cylinderHeight）：返回胶囊碰撞体中段圆柱的高度（本地空间）。 这是胶囊中段的高度，不含两端半球。总高度 = cylinderHeight + radius × 2。 常用于区分胶囊不同部分的尺寸，便于精确控制碰撞体比例。

节点信息

字段	值
节点 ID	capsuleColliderGetCylinderHeight
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
cylinderHeight	圆柱高度	数据	number	中段圆柱高度（本地空间） 胶囊中段圆柱的高度，不含两端半球。总高度 = cylinderHeight + radius × 2。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取总高度

获取胶囊总高度（height）：返回胶囊碰撞体本地空间的总高度。 计算关系：height = radius × 2 + cylinderHeight，最小值为直径（2 × radius）。 注意：height 与 cylinderHeight 存在派生关系——写入 height 时引擎会基于当前 radius 重新计算 cylinderHeight；建议根据业务语义选择使用 height 或 cylinderHeight，避免混用造成混淆。

节点信息

字段	值
节点 ID	capsuleColliderGetHeight
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
height	总高度	数据	number	总高度（本地空间） 胶囊完整高度：height = radius × 2 + cylinderHeight。最小值为直径（2 × radius）。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置朝向轴

设置胶囊朝向轴（direction）：修改胶囊碰撞体的轴向朝向。 取值：0（X_AXIS）=X 轴方向，1（Y_AXIS）=Y 轴方向，2（Z_AXIS）=Z 轴方向。 朝向轴决定胶囊沿哪个轴延伸，常见用法：Y 轴（1）用于竖向角色碰撞体，X 轴（0）或 Z 轴（2）用于水平放置的物体。

节点信息

字段	值
节点 ID	capsuleColliderSetDirection
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填
direction	朝向轴	数据	enum / physics.EAxisDirection	胶囊朝向轴（EAxisDirection） 取值：0（X_AXIS）=X 轴方向，1（Y_AXIS）=Y 轴方向，2（Z_AXIS）=Z 轴方向。	下拉选择 默认值：“Y_AXIS”	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 透传当前操作的 CapsuleCollider 组件，便于链式操作。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置球半径

设置胶囊体球半径（radius）：修改胶囊碰撞体本地空间的球半径。 节点缩放会叠加影响最终碰撞体在世界中的大小。 常用于动态调整角色碰撞体的胖瘦，如角色变身时改变体型、受伤时缩小碰撞区域。 注意：修改 radius 不会自动调整 cylinderHeight，但会影响 height（总高度）。如需维持原总高度，需同步调整 cylinderHeight。

节点信息

字段	值
节点 ID	capsuleColliderSetRadius
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填
radius	球半径	数据	number	球半径 胶囊两端半球的半径（本地空间）。节点缩放会叠加影响最终碰撞体在世界中的大小。	输入框 默认值：0.5	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 透传当前操作的 CapsuleCollider 组件，便于链式操作。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置全部属性

批量修改 CapsuleCollider 属性：聚合写入 radius、cylinderHeight、direction、height。 除 exe 与 capsuleCollider 外，所有可写属性引脚默认不公开，只有被显式公开且有值的属性才参与写入。 写入顺序：direction → radius → height（若已公开，否则 cylinderHeight）。 注意：height 与 cylinderHeight 同时公开时以 height 为准。建议先公开 radius 再公开 height。

节点信息

字段	值
节点 ID	capsuleColliderSetProperties
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填
radius	球半径	数据	number	球半径（本地空间）。负值会被自动转为正值。	输入框 默认值：0.5	可选 默认隐藏
cylinderHeight	圆柱高度	数据	number	中段圆柱高度（不含两端半球）。height 已公开时以 height 为准，cylinderHeight 不生效。	输入框 默认值：1	可选 默认隐藏
direction	朝向轴	数据	enum / physics.EAxisDirection	胶囊朝向轴。取值：0（X_AXIS）=X 轴方向，1（Y_AXIS）=Y 轴方向，2（Z_AXIS）=Z 轴方向。	下拉选择 默认值：“Y_AXIS”	可选 默认隐藏
height	总高度	数据	number	胶囊总高度（本地空间）。公开时优先于 cylinderHeight，引擎基于当前 radius 推导 cylinderHeight。	输入框 默认值：2	可选 默认隐藏

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 透传当前操作的 CapsuleCollider 组件，便于链式操作。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置圆柱高度

设置中段圆柱高度（cylinderHeight）：修改胶囊碰撞体中段圆柱的高度（本地空间）。 这只控制中段高度，不含两端半球。总高度 = cylinderHeight + radius × 2。 常用于精确调整碰撞体躯干高度，不影响两端半球的尺寸。 注意：若使用 height（总高度）入口写入后再使用本节点，cylinderHeight 值会被覆盖。建议统一使用 height 或 cylinderHeight，避免混用。

节点信息

字段	值
节点 ID	capsuleColliderSetCylinderHeight
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填
cylinderHeight	圆柱高度	数据	number	中段圆柱高度 胶囊中段高度（不含两端半球）。总高度 = cylinderHeight + radius × 2。	输入框 默认值：1	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 透传当前操作的 CapsuleCollider 组件，便于链式操作。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置总高度

设置胶囊总高度（height）：修改胶囊碰撞体本地空间的总高度。 写入总高度后，引擎会根据当前 radius 推导中段高度（cylinderHeight = height - radius × 2）。输入值小于直径时，中段高度为 0（即两端半球紧贴）。 常用于一键调整角色碰撞体整体高度，如角色站立/蹲下切换。 注意：建议先确定 radius 再写入 height，以获得预期的几何结果。

节点信息

字段	值
节点 ID	capsuleColliderSetHeight
分类	Cocos 组件
二级分类	3D物理
分组	CapsuleCollider
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 要操作的胶囊碰撞体组件。 CapsuleCollider 是 3D 物理中常用的胶囊形碰撞体，广泛用于角色触发区、交互检测与近似人体碰撞体。几何参数 radius、cylinderHeight/height、direction 共同决定最终碰撞体积与朝向。	-	必填
height	总高度	数据	number	总高度 胶囊完整高度（本地空间）。引擎基于当前 radius 计算中段高度。若小于直径，中段高度为 0。	输入框 默认值：2	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
capsuleCollider	胶囊碰撞体	数据	cc.Component / CapsuleCollider	目标 CapsuleCollider 组件 透传当前操作的 CapsuleCollider 组件，便于链式操作。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。