使用指南
Cocos 组件 / 3D物理 / CharacterController节点
Cocos 组件 / 3D物理 / CharacterController 节点手册，包含 24 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：24
- 分类路径：Cocos 组件 / 3D物理 / CharacterController
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 绑定触发器持续事件 | characterControllerTriggerStayBind | 3 / 2 | 立即继续 |
| 绑定触发器进入事件 | characterControllerTriggerEnterBind | 3 / 2 | 立即继续 |
| 绑定触发器离开事件 | characterControllerTriggerExitBind | 3 / 2 | 立即继续 |
| 绑定碰撞事件 | characterControllerControllerColliderHitBind | 3 / 2 | 立即继续 |
| 获取本地中心偏移 | characterControllerGetCenter | 1 / 1 | 立即继续 |
| 获取控制器类型 | characterControllerGetType | 1 / 1 | 立即继续 |
| 获取碰撞分组 | characterControllerGetGroup | 1 / 1 | 立即继续 |
| 获取皮肤宽度 | characterControllerGetSkinWidth | 1 / 1 | 立即继续 |
| 获取全部属性 | characterControllerGetProperties | 1 / 10 | 立即继续 |
| 获取世界中心位置 | characterControllerGetCenterWorldPosition | 1 / 1 | 立即继续 |
| 获取是否着地 | characterControllerGetIsGrounded | 1 / 1 | 立即继续 |
| 获取速度 | characterControllerGetVelocity | 1 / 1 | 立即继续 |
| 获取台阶高度 | characterControllerGetStepOffset | 1 / 1 | 立即继续 |
| 获取最大爬坡角度 | characterControllerGetSlopeLimit | 1 / 1 | 立即继续 |
| 获取最小移动距离 | characterControllerGetMinMoveDistance | 1 / 1 | 立即继续 |
| 设置本地中心偏移 | characterControllerSetCenter | 3 / 2 | 立即继续 |
| 设置碰撞分组 | characterControllerSetGroup | 3 / 2 | 立即继续 |
| 设置皮肤宽度 | characterControllerSetSkinWidth | 3 / 2 | 立即继续 |
| 设置全部属性 | characterControllerSetProperties | 9 / 2 | 立即继续 |
| 设置世界中心位置 | characterControllerSetCenterWorldPosition | 3 / 2 | 立即继续 |
| 设置台阶高度 | characterControllerSetStepOffset | 3 / 2 | 立即继续 |
| 设置最大爬坡角度 | characterControllerSetSlopeLimit | 3 / 2 | 立即继续 |
| 设置最小移动距离 | characterControllerSetMinMoveDistance | 3 / 2 | 立即继续 |
| 执行移动 | characterControllerMove | 3 / 2 | 立即继续 |
绑定触发器持续事件
绑定触发器持续事件：当角色控制器持续停留在触发器区域内时，持续触发连接的 执行事件 节点。 此节点建立长期监听，不是一次性立即触发；触发器持续事件会在每次物理 tick 时反复触发，请注意性能影响。 事件 payload 包含触发事件对象，含 type、collider、characterController 等字段。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerTriggerStayBind |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
event | 事件 | 事件 | 事件 | 事件入口 连接到 执行事件 节点的事件输出引脚。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
handle | 句柄 | 数据 | eventHandle | 绑定句柄 用于后续取消这个具体监听。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
绑定触发器进入事件
绑定触发器进入事件：当角色控制器进入触发器区域时，触发连接的 执行事件 节点。 此节点建立长期监听，不是一次性立即触发；适合放在初始化流程中。 事件 payload 包含触发事件对象，含 type、collider、characterController 等字段。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerTriggerEnterBind |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
event | 事件 | 事件 | 事件 | 事件入口 连接到 执行事件 节点的事件输出引脚。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
handle | 句柄 | 数据 | eventHandle | 绑定句柄 用于后续取消这个具体监听。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
绑定触发器离开事件
绑定触发器离开事件：当角色控制器离开触发器区域时，触发连接的 执行事件 节点。 此节点建立长期监听，不是一次性立即触发；适合放在初始化流程中。 事件 payload 包含触发事件对象，含 type、collider、characterController 等字段。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerTriggerExitBind |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
event | 事件 | 事件 | 事件 | 事件入口 连接到 执行事件 节点的事件输出引脚。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
handle | 句柄 | 数据 | eventHandle | 绑定句柄 用于后续取消这个具体监听。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
绑定碰撞事件
绑定角色控制器碰撞事件：当角色控制器移动过程中与场景中的静态碰撞体或动态碰撞体发生碰撞时，触发连接的 执行事件 节点。 此节点建立长期监听，不是一次性立即触发；适合放在 OnEnable/Start 等初始化流程中。 事件 payload 类型为 CharacterControllerContact，包含碰撞接触信息。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerControllerColliderHitBind |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
event | 事件 | 事件 | 事件 | 事件入口 连接到 执行事件 节点的事件输出引脚，用于标识触发目标。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
handle | 句柄 | 数据 | eventHandle | 绑定句柄 用于后续取消这个具体监听。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取本地中心偏移
获取本地中心偏移：返回角色控制器碰撞体在节点本地坐标系中的中心偏移量。 此值为局部坐标，与节点位置无关。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetCenter |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
center | 本地中心偏移 | 数据 | vector3 | 本地中心偏移 角色控制器碰撞体相对于节点本地坐标系的中心偏移量。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取控制器类型
获取控制器类型：返回当前角色控制器的类型枚举值（ECharacterControllerType）。 BOX — 盒体角色控制器，CapsuleCharacterController 使用的几何形状为胶囊体（CAPSULE）。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetType |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
type | 类型 | 数据 | enum / physics.ECharacterControllerType | 控制器类型 当前角色控制器的类型枚举（ECharacterControllerType）： BOX（盒体角色控制器，适合方形角色体积） CAPSULE（胶囊体角色控制器，适合圆柱/人形角色体积） | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取碰撞分组
获取碰撞分组：返回 CharacterController 的碰撞分组值（单 bit 整数）。 碰撞分组决定该控制器与哪些物体发生碰撞，需要与项目碰撞矩阵配合使用。 注意：此值必须是单 bit（如 1、2、4、8），不是 mask。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetGroup |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
group | 碰撞分组 | 数据 | number | 碰撞分组 碰撞分组值，必须是单 bit 值（如 1、2、4、8），不是多个分组求和后的 mask。引擎会根据项目碰撞矩阵自动推导对应的 mask。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取皮肤宽度
获取皮肤宽度：返回角色控制器的皮肤厚度，用于防止控制器陷入几何体。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetSkinWidth |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
skinWidth | 皮肤宽度 | 数据 | number | 皮肤宽度 角色控制器碰撞体的皮肤厚度，用于防止陷入几何体。引擎会强制取绝对值，且最小保持 0.0001。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取全部属性
一次性读取 CharacterController 所有属性：聚合读取 group、minMoveDistance、stepOffset、slopeLimit、skinWidth、center、centerWorldPosition、velocity、isGrounded、type。 适合在调试或多属性联动场景下批量获取控制器状态。 注意：velocity 和 isGrounded 只有执行过 move() 后才有意义。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
group | 碰撞分组 | 数据 | number | 碰撞分组 碰撞分组值，必须是单 bit 值（如 1、2、4、8），不是多个分组求和后的 mask。引擎会根据项目碰撞矩阵自动推导对应的 mask。 | - | 可选 |
minMoveDistance | 最小移动距离 | 数据 | number | 最小移动距离 控制器响应 move() 的最小位移阈值，低于此值的移动请求会被忽略，可用于过滤输入抖动。 | - | 可选 |
stepOffset | 台阶高度 | 数据 | number | 台阶高度 角色控制器可自动跨越的最大台阶高度，超过此值的障碍物会阻挡移动。 | - | 可选 |
slopeLimit | 最大爬坡角度 | 数据 | number | 最大爬坡角度 角色控制器可爬行的最大斜面角度（单位：度）。超过此角度的斜面会阻挡移动。 | - | 可选 |
skinWidth | 皮肤宽度 | 数据 | number | 皮肤宽度 角色控制器碰撞体的皮肤厚度，用于防止陷入几何体。引擎会强制取绝对值，且最小保持 0.0001。 | - | 可选 |
center | 本地中心偏移 | 数据 | vector3 | 本地中心偏移 角色控制器碰撞体相对于节点本地坐标系的中心偏移量。 | - | 可选 |
centerWorldPosition | 世界中心位置 | 数据 | vector3 | 世界空间中心位置 角色控制器碰撞体在世界坐标系下的中心位置。setter 会立即同步到底层物理控制器。 | - | 可选 |
velocity | 速度 | 数据 | vector3 | 速度 上一次 move() 执行后计算出的速度向量。注意：只有执行过 move() 后才会更新，初始值为零向量。 | - | 可选 |
isGrounded | 已着地 | 数据 | boolean | 是否着地 角色控制器在上一次 move() 后是否接触地面。注意：只有执行过 move() 后才会更新。 | - | 可选 |
type | 类型 | 数据 | enum / physics.ECharacterControllerType | 控制器类型 当前角色控制器的类型枚举（ECharacterControllerType）： BOX（盒体角色控制器，适合方形角色体积） CAPSULE（胶囊体角色控制器，适合圆柱/人形角色体积） | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取世界中心位置
获取世界中心位置：返回角色控制器碰撞体在世界坐标系下的中心位置。 此值为世界坐标，已综合考虑节点位置与局部偏移。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetCenterWorldPosition |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
centerWorldPosition | 世界中心位置 | 数据 | vector3 | 世界空间中心位置 角色控制器碰撞体在世界坐标系下的中心位置。setter 会立即同步到底层物理控制器。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取是否着地
获取是否着地：返回角色控制器在上一次 move() 后是否接触地面。 注意：只有执行过 move() 之后才会更新；未执行 move() 时始终返回 false。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetIsGrounded |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
isGrounded | 已着地 | 数据 | boolean | 是否着地 角色控制器在上一次 move() 后是否接触地面。注意：只有执行过 move() 后才会更新。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取速度
获取速度：返回角色控制器在上一次 move() 调用后计算出的速度向量。 注意：只有执行过 move() 之后才会更新；未执行 move() 时返回零向量，不代表当前帧的真实速度。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetVelocity |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
velocity | 速度 | 数据 | vector3 | 速度 上一次 move() 执行后计算出的速度向量。注意：只有执行过 move() 后才会更新，初始值为零向量。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取台阶高度
获取台阶高度：返回角色控制器可自动跨越的最大台阶高度。 超过此高度的障碍物会阻挡移动，而不是被自动爬上去。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetStepOffset |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
stepOffset | 台阶高度 | 数据 | number | 台阶高度 角色控制器可自动跨越的最大台阶高度，超过此值的障碍物会阻挡移动。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取最大爬坡角度
获取最大爬坡角度：返回角色控制器可行走的最大斜面角度（单位：度）。 超过此角度的斜面会阻挡移动。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetSlopeLimit |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
slopeLimit | 最大爬坡角度 | 数据 | number | 最大爬坡角度 角色控制器可爬行的最大斜面角度（单位：度）。超过此角度的斜面会阻挡移动。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取最小移动距离
获取最小移动距离：返回 CharacterController 忽略极小移动请求的阈值。 低于此阈值的 move() 请求不会产生物理位移，可用于过滤摇杆等输入的抖动。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerGetMinMoveDistance |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
minMoveDistance | 最小移动距离 | 数据 | number | 最小移动距离 控制器响应 move() 的最小位移阈值，低于此值的移动请求会被忽略，可用于过滤输入抖动。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置本地中心偏移
设置本地中心偏移：设置角色控制器碰撞体在节点本地坐标系中的中心偏移量。 修改后控制器形状在物理世界中的位置会随之变化。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerSetCenter |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
center | 本地中心偏移 | 数据 | vector3 | 本地中心偏移 角色控制器碰撞体相对于节点本地坐标系的中心偏移量。 | 可编辑控件 默认值：[0,0,0] | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 角色控制器 透传当前操作的角色控制器组件，方便连到下一个操作节点。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置碰撞分组
设置碰撞分组：设置 CharacterController 的碰撞分组。 引擎会根据项目碰撞矩阵自动推导 mask，无需手动设置 mask。 注意：必须输入单 bit 值（如 1、2、4、8），多 bit 组合在游戏运行时会以 mask 形式体现但 group 本身仍应是单 bit。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerSetGroup |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
group | 碰撞分组 | 数据 | number | 碰撞分组 碰撞分组值，必须是单 bit 值（如 1、2、4、8），不是多个分组求和后的 mask。引擎会根据项目碰撞矩阵自动推导对应的 mask。 | 输入框 默认值：1 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 角色控制器 透传当前操作的角色控制器组件，方便连到下一个操作节点。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置皮肤宽度
设置皮肤宽度：设置角色控制器的皮肤厚度。 引擎会取绝对值，且将最小值强制为 0.0001，防止皮肤宽度为零导致物理不稳定。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerSetSkinWidth |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
skinWidth | 皮肤宽度 | 数据 | number | 皮肤宽度 角色控制器碰撞体的皮肤厚度，用于防止陷入几何体。引擎会强制取绝对值，且最小保持 0.0001。 | 输入框 默认值：0.01 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 角色控制器 透传当前操作的角色控制器组件，方便连到下一个操作节点。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置全部属性
批量修改 CharacterController 可写属性：聚合写入 group、minMoveDistance、stepOffset、slopeLimit、skinWidth、center、centerWorldPosition。 说明：除 exe 与 characterController 外，所有可写属性引脚默认不公开（isPublic: false），只有被显式公开且有值的属性才参与写入；未公开属性保持原值不变。 注意：velocity、isGrounded、type 是只读属性，不在此节点写入范围内。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerSetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
group | 碰撞分组 | 数据 | number | 碰撞分组值，必须是单 bit（如 1、2、4、8），不是 mask。 | 输入框 默认值：1 | 可选 默认隐藏 |
minMoveDistance | 最小移动距离 | 数据 | number | 控制器响应 move() 的最小位移阈值，引擎会取绝对值。 | 输入框 默认值：0.001 | 可选 默认隐藏 |
stepOffset | 台阶高度 | 数据 | number | 可自动跨越的最大台阶高度，引擎会取绝对值。 | 输入框 默认值：0.5 | 可选 默认隐藏 |
slopeLimit | 最大爬坡角度 | 数据 | number | 可行走的最大斜面角度（度），引擎会取绝对值。 | 输入框 默认值：45 | 可选 默认隐藏 |
skinWidth | 皮肤宽度 | 数据 | number | 碰撞体皮肤厚度，引擎会取绝对值且最小为 0.0001。 | 输入框 默认值：0.01 | 可选 默认隐藏 |
center | 本地中心偏移 | 数据 | vector3 | 碰撞体在本地坐标系的中心偏移。 | 可编辑控件 默认值：[0,0,0] | 可选 默认隐藏 |
centerWorldPosition | 世界中心位置 | 数据 | vector3 | 碰撞体在世界坐标系下的中心位置，setter 立即同步到物理控制器。 | 可编辑控件 默认值：[0,0,0] | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 角色控制器 透传当前操作的角色控制器组件，方便连到下一个操作节点。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置世界中心位置
设置世界中心位置：设置角色控制器碰撞体在世界坐标系下的中心位置。 此操作会立即同步到底层物理控制器。与设置 center（局部偏移）不同，此节点直接操作世界坐标。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerSetCenterWorldPosition |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
centerWorldPosition | 世界中心位置 | 数据 | vector3 | 世界空间中心位置 角色控制器碰撞体在世界坐标系下的中心位置。setter 会立即同步到底层物理控制器。 | 可编辑控件 默认值：[0,0,0] | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 角色控制器 透传当前操作的角色控制器组件，方便连到下一个操作节点。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置台阶高度
设置台阶高度：设置角色控制器可自动跨越的最大台阶高度。 引擎会对值取绝对值；建议根据角色造型设置合适的台阶高度以获得自然的移动体验。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerSetStepOffset |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
stepOffset | 台阶高度 | 数据 | number | 台阶高度 角色控制器可自动跨越的最大台阶高度，超过此值的障碍物会阻挡移动。 | 输入框 默认值：0.5 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 角色控制器 透传当前操作的角色控制器组件，方便连到下一个操作节点。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置最大爬坡角度
设置最大爬坡角度：设置角色控制器可行走的最大斜面角度（度）。 引擎会对值取绝对值，合法范围 0–180 度。超出合法范围的输入由引擎处理。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerSetSlopeLimit |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
slopeLimit | 最大爬坡角度 | 数据 | number | 最大爬坡角度 角色控制器可爬行的最大斜面角度（单位：度）。超过此角度的斜面会阻挡移动。 | 输入框 默认值：45 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 角色控制器 透传当前操作的角色控制器组件，方便连到下一个操作节点。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置最小移动距离
设置最小移动距离：设置忽略极小移动的阈值。 引擎会对值取绝对值，输入负值与同值的正值效果相同。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerSetMinMoveDistance |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
minMoveDistance | 最小移动距离 | 数据 | number | 最小移动距离 控制器响应 move() 的最小位移阈值，低于此值的移动请求会被忽略，可用于过滤输入抖动。 | 输入框 默认值：0.001 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 角色控制器 透传当前操作的角色控制器组件，方便连到下一个操作节点。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
执行移动
执行移动：驱动角色控制器在本帧按指定位移向量移动。 输入的是位移量，不是速度；通常每帧由业务逻辑计算后输入。 内部使用引擎的固定时步，无需额外传入 deltaTime。 执行后可通过 获取速度 和 获取是否着地 节点读取运动结果。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | characterControllerMove |
| 分类 | Cocos 组件 |
| 二级分类 | 3D物理 |
| 分组 | CharacterController |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 目标角色控制器组件 要操作的角色控制器。 就像角色的”碰撞身体”——决定了角色怎么移动、能不能爬坡、跨过多高的台阶。 支持两种形状的控制器（Box 方块、Capsule 胶囊），都继承自 CharacterController，均可接入此端口。 | - | 必填 |
movement | 移动向量 | 数据 | vector3 | 移动位移向量 本次移动的位移量，不是速度；通常每帧由业务逻辑计算后输入。move() 内部使用引擎固定时步，无需额外传入 deltaTime。 | 可编辑控件 默认值：[0,0,0] | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
characterController | - | 数据 | cc.Component / CharacterController | 角色控制器 透传当前操作的角色控制器组件，方便连到下一个操作节点。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。