使用指南
Cocos 组件 / 3D物理 / CapsuleCharacterController节点
Cocos 组件 / 3D物理 / CapsuleCharacterController 节点手册，包含 4 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：4
- 分类路径：Cocos 组件 / 3D物理 / CapsuleCharacterController
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取半径 | capsuleCharacterControllerGetRadius | 1 / 1 | 立即继续 |
| 获取高度 | capsuleCharacterControllerGetHeight | 1 / 1 | 立即继续 |
| 设置半径 | capsuleCharacterControllerSetRadius | 3 / 2 | 立即继续 |
| 设置高度 | capsuleCharacterControllerSetHeight | 3 / 2 | 立即继续 |
获取半径
获取胶囊体碰撞半径：调节胶囊角色的”胖瘦”。 半径越大，角色横向越占空间，通过窄门、缝隙的能力越弱；半径越小，角色越”瘦”，容易穿过狭窄通道。 适合用在做角色体型调整、蹲伏碰撞缩小、或者让角色”变胖”无法通过某些区域等玩法。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | capsuleCharacterControllerGetRadius |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CapsuleCharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
capsuleCharacterController | 胶囊控制器 | 数据 | cc.Component / CapsuleCharacterController | 目标 CapsuleCharacterController 组件 要操作的胶囊角色控制器组件。 该组件是 Cocos Creator 3D 物理角色控制器体系中的胶囊体实现，通过调整其几何参数控制角色碰撞体积。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
radius | 半径 | 数据 | number | 半径 胶囊横向碰撞体积大小。0.5 为默认值。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取高度
获取胶囊体碰撞高度：读取角色胶囊碰撞体的”高度”参数。 这个值表示胶囊中间柱体的长度，角色总高度 = height + 2 × radius。配合 radius 一起使用，可以控制角色的站立体型。 常用场景：检测当前角色是站立还是蹲伏状态、或者读取变身前后体型变化。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | capsuleCharacterControllerGetHeight |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CapsuleCharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
capsuleCharacterController | 胶囊控制器 | 数据 | cc.Component / CapsuleCharacterController | 目标 CapsuleCharacterController 组件 要操作的胶囊角色控制器组件。 该组件是 Cocos Creator 3D 物理角色控制器体系中的胶囊体实现，通过调整其几何参数控制角色碰撞体积。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
height | 高度 | 数据 | number | 高度 胶囊中间柱体长度。注意不是角色总高度。默认 1。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置半径
设置胶囊体碰撞半径：修改胶囊角色的”胖瘦”。 半径增大 → 角色横向变宽，通过窄门更困难；半径减小 → 角色变瘦，更容易穿过狭窄通道。 常用场景：拾取”缩小”道具时减小碰撞半径以钻过通风管道；或角色进入”狂暴”状态变大体型。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | capsuleCharacterControllerSetRadius |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CapsuleCharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
capsuleCharacterController | 胶囊控制器 | 数据 | cc.Component / CapsuleCharacterController | 目标 CapsuleCharacterController 组件 要操作的胶囊角色控制器组件。 该组件是 Cocos Creator 3D 物理角色控制器体系中的胶囊体实现，通过调整其几何参数控制角色碰撞体积。 | - | 必填 |
radius | 半径 | 数据 | number | 半径 胶囊横向碰撞体积。负值自动取正。默认 0.5。 | 输入框 默认值：0.5 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
capsuleCharacterController | 胶囊控制器 | 数据 | cc.Component / CapsuleCharacterController | 目标 CapsuleCharacterController 组件 透传当前操作的 CapsuleCharacterController 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置高度
设置胶囊体碰撞高度：修改角色胶囊碰撞体的”身高”。 高度增大 → 角色碰撞体变高，适合站立状态；高度减小 → 碰撞体变矮，适合蹲伏或爬行状态。 常用场景：玩家按下蹲伏键时缩小碰撞高度以钻过低矮障碍物；或变身体型切换时同步调整碰撞体。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | capsuleCharacterControllerSetHeight |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CapsuleCharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
capsuleCharacterController | 胶囊控制器 | 数据 | cc.Component / CapsuleCharacterController | 目标 CapsuleCharacterController 组件 要操作的胶囊角色控制器组件。 该组件是 Cocos Creator 3D 物理角色控制器体系中的胶囊体实现，通过调整其几何参数控制角色碰撞体积。 | - | 必填 |
height | 高度 | 数据 | number | 高度 角色碰撞体高度。负值自动取正。默认 1。 | 输入框 默认值：1 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
capsuleCharacterController | 胶囊控制器 | 数据 | cc.Component / CapsuleCharacterController | 目标 CapsuleCharacterController 组件 透传当前操作的 CapsuleCharacterController 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。