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

学习目标

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

覆盖范围

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

典型使用场景

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

通用注意事项

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

节点索引

节点	节点 ID	输入/输出	执行方式
获取横向半宽	boxCharacterControllerGetHalfSideExtent	1 / 1	立即继续
获取全部属性	boxCharacterControllerGetProperties	1 / 3	立即继续
获取竖向半高	boxCharacterControllerGetHalfHeight	1 / 1	立即继续
获取纵向半宽	boxCharacterControllerGetHalfForwardExtent	1 / 1	立即继续
设置横向半宽	boxCharacterControllerSetHalfSideExtent	3 / 2	立即继续
设置全部属性	boxCharacterControllerSetProperties	5 / 2	立即继续
设置竖向半高	boxCharacterControllerSetHalfHeight	3 / 2	立即继续
设置纵向半宽	boxCharacterControllerSetHalfForwardExtent	3 / 2	立即继续

获取横向半宽

获取盒形控制器碰撞宽度：读取角色碰撞盒的左右方向一半宽度。 盒体总宽度 = halfSideExtent × 2。通过此值可判断角色横向的”体型”大小。 常用于读取当前角色的胖瘦状态，为后续调整提供依据。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 要操作的盒形角色控制器。盒形控制器用立方体碰撞体定义角色体积，适合需要方正碰撞体形状的游戏（如方块风格角色）。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
halfSideExtent	横向半宽	数据	number	横向半宽 盒体在左右方向的一半宽度。总体宽 = 半宽 × 2。默认值 0.5。 增大让角色横向更胖；减小则更瘦。	-	可选

使用场景

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

注意事项

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

---

获取全部属性

一次性读取盒形控制器全部碰撞尺寸：同时获取竖向半高、横向半宽、纵向半宽。 三个方向尺寸共同定义角色碰撞盒的完整体积。适合在角色变身、体型切换时一次性记录当前体型，或批量展示角色属性。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 要操作的盒形角色控制器。盒形控制器用立方体碰撞体定义角色体积，适合需要方正碰撞体形状的游戏（如方块风格角色）。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
halfHeight	竖向半高	数据	number	竖向半高 盒体在竖直方向的一半高度。总高度 = 半高 × 2。默认值 0.5。 增大该值让角色碰撞体纵向变高；减小则变矮。	-	可选
halfSideExtent	横向半宽	数据	number	横向半宽 盒体在左右方向的一半宽度。总体宽 = 半宽 × 2。默认值 0.5。 增大让角色横向更胖；减小则更瘦。	-	可选
halfForwardExtent	纵向半宽	数据	number	纵向半宽 盒体在前后方向的一半深度。总深度 = 半宽 × 2。默认值 0.5。 增大让角色前后更厚；减小则更薄。	-	可选

使用场景

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

注意事项

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

---

获取竖向半高

获取盒形控制器碰撞高度：读取角色碰撞盒的竖直方向一半高度。 盒体总高度 = halfHeight × 2。通过此值可判断角色的”身高”状态。 配合修改节点使用，可制作蹲伏/站立切换玩法：蹲伏时读取当前高度并记录，待解除蹲伏后恢复。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 要操作的盒形角色控制器。盒形控制器用立方体碰撞体定义角色体积，适合需要方正碰撞体形状的游戏（如方块风格角色）。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
halfHeight	竖向半高	数据	number	竖向半高 盒体在竖直方向的一半高度。总高度 = 半高 × 2。默认值 0.5。 增大该值让角色碰撞体纵向变高；减小则变矮。	-	可选

使用场景

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

注意事项

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

---

获取纵向半宽

获取盒形控制器碰撞深度：读取角色碰撞盒的前后方向一半深度。 盒体总深度 = halfForwardExtent × 2。通过此值可了解角色”厚薄”状态。 常用于配合宽度和高度一起读取，全面了解当前碰撞盒的三维尺寸。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 要操作的盒形角色控制器。盒形控制器用立方体碰撞体定义角色体积，适合需要方正碰撞体形状的游戏（如方块风格角色）。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
halfForwardExtent	纵向半宽	数据	number	纵向半宽 盒体在前后方向的一半深度。总深度 = 半宽 × 2。默认值 0.5。 增大让角色前后更厚；减小则更薄。	-	可选

使用场景

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

注意事项

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

---

设置横向半宽

设置盒形控制器碰撞宽度：修改角色碰撞盒的左右方向尺寸。 盒体总宽度 = halfSideExtent × 2。增大值让角色更”胖”，更难通过窄缝；减小值让角色更”瘦”，轻松穿过狭窄地形。 常见用例：角色拾取”缩小”道具 → 设置横向半宽为 0.2 → 角色变瘦 → 穿过窄缝。或角色变身 Boss 时增大体型。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 要操作的盒形角色控制器。盒形控制器用立方体碰撞体定义角色体积，适合需要方正碰撞体形状的游戏（如方块风格角色）。	-	必填
halfSideExtent	横向半宽	数据	number	横向半宽 盒体在左右方向的一半宽度。总体宽 = 半宽 × 2。默认值 0.5。 增大让角色横向更胖；减小则更瘦。	输入框 默认值：0.5	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 透传当前操作的 BoxCharacterController 组件，便于链式操作。	-	可选

使用场景

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

注意事项

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

---

设置全部属性

批量修改盒形控制器全部碰撞尺寸：同时写入竖向半高、横向半宽、纵向半宽。 说明：未连接的属性引脚保持原值不变，只修改你显式连接了的属性。 适合在角色体型切换（正常/蹲伏/缩小/变大）时一次性更新整个碰撞盒，确保三轴尺寸同步变化。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 要操作的盒形角色控制器。盒形控制器用立方体碰撞体定义角色体积，适合需要方正碰撞体形状的游戏（如方块风格角色）。	-	必填
halfHeight	竖向半高	数据	number	竖向半高 盒体竖直方向的一半高度。默认值 0.5。增大变高，减小变矮。	输入框 默认值：0.5	可选 默认隐藏
halfSideExtent	横向半宽	数据	number	横向半宽 盒体左右方向的一半宽度。默认值 0.5。增大变胖，减小变瘦。	输入框 默认值：0.5	可选 默认隐藏
halfForwardExtent	纵向半宽	数据	number	纵向半宽 盒体前后方向的一半深度。默认值 0.5。增大变厚，减小变薄。	输入框 默认值：0.5	可选 默认隐藏

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 透传当前操作的 BoxCharacterController 组件，便于链式操作。	-	可选

使用场景

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

注意事项

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

---

设置竖向半高

设置盒形控制器碰撞高度：修改角色碰撞盒的竖直方向尺寸。 盒体总高度 = halfHeight × 2。增大值让角色变高，可够到更高处的平台；减小值让角色变矮，可钻过低矮通道。 常见用例：玩家按下蹲伏键 → 设置半高为 0.3 → 角色碰撞体变矮 → 钻过矮洞。松开后恢复原值。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 要操作的盒形角色控制器。盒形控制器用立方体碰撞体定义角色体积，适合需要方正碰撞体形状的游戏（如方块风格角色）。	-	必填
halfHeight	竖向半高	数据	number	竖向半高 盒体在竖直方向的一半高度。总高度 = 半高 × 2。默认值 0.5。 增大该值让角色碰撞体纵向变高；减小则变矮。	输入框 默认值：0.5	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 透传当前操作的 BoxCharacterController 组件，便于链式操作。	-	可选

使用场景

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

注意事项

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

---

设置纵向半宽

设置盒形控制器碰撞深度：修改角色碰撞盒的前后方向尺寸。 盒体总深度 = halfForwardExtent × 2。增大值让角色前后方向上更”厚”；减小值让角色更”薄”。 常见用例：调整角色面向方向的碰撞范围，例如防御姿态时增大正面碰撞体积，或侧身时减小前后深度以通过窄缝。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 要操作的盒形角色控制器。盒形控制器用立方体碰撞体定义角色体积，适合需要方正碰撞体形状的游戏（如方块风格角色）。	-	必填
halfForwardExtent	纵向半宽	数据	number	纵向半宽 盒体在前后方向的一半深度。总深度 = 半宽 × 2。默认值 0.5。 增大让角色前后更厚；减小则更薄。	输入框 默认值：0.5	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
controller	盒形角色控制器	数据	cc.Component / BoxCharacterController	目标 BoxCharacterController 组件 透传当前操作的 BoxCharacterController 组件，便于链式操作。	-	可选

使用场景

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

注意事项

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