使用指南
物理系统 / 拾取节点
物理系统 / 拾取 节点手册，包含 2 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
执行射线、形状和屏幕点查询，获取物理世界中的碰撞结果。
覆盖范围
- 节点数量：2
- 分类路径：物理系统 / 拾取
典型使用场景
- 点击屏幕选择 3D 对象
- 检测攻击范围或视线遮挡
- 根据射线结果决定移动、拾取或交互
通用注意事项
- 物理查询依赖场景中的碰撞体配置。
- 全部拾取类节点可能返回多个结果，后续通常要遍历或筛选。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 屏幕点 3D 全部拾取 | physicsPickScreenPointAll | 7 / 4 | 立即继续 |
| 屏幕点 3D 最近拾取 | physicsPickScreenPointClosest | 7 / 4 | 立即继续 |
屏幕点 3D 全部拾取
屏幕点 3D 全部拾取：把屏幕点击位置换成 3D 检测，并返回这条方向上碰到的所有物体。 适合做穿透查询、想自己筛选多个候选目标，或需要知道“这一点后面还压着哪些物体”时使用。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | physicsPickScreenPointAll |
| 分类 | 物理系统 |
| 二级分类 | 拾取 |
| 分组 | - |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 到达这里时，立即执行这次设置或查询。 | - | 可选 |
cameraComponent | 相机 | 数据 | cc.Component / Camera | 用于观察场景的相机 这个节点会用它把“你点击的屏幕位置”换算成场景里的检测方向。通常接当前主相机。 | - | 必填 |
x | 屏幕 X | 数据 | number | 屏幕 X 填写你点击或触摸到的屏幕坐标。通常来自鼠标位置或触摸位置。 | 输入框 默认值：0 | 必填 |
y | 屏幕 Y | 数据 | number | 屏幕 Y 填写你点击或触摸到的屏幕坐标。通常来自鼠标位置或触摸位置。 | 输入框 默认值：0 | 必填 |
mask | 碰撞掩码 | 数据 | number | 筛选范围 用来限制“只检查哪些碰撞体”。默认 0xffffffff 表示全部都检查；不确定时保持默认即可。 | 输入框 默认值：4294967295 | 可选 |
maxDistance | 最大距离 | 数据 | number | 最多检测多远 默认 10000000，通常足够大。只有你想明确限制检测距离时才需要修改。 | 输入框 默认值：10000000 | 可选 |
queryTrigger | 检测触发器 | 数据 | boolean | 是否把触发区域算进去 开启后，只负责触发事件的区域也会被算作命中。大多数情况下保持默认即可。 | 可编辑控件 默认值：true | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 继续执行 当前操作完成后，从这里继续后续流程。 | - | 可选 |
ray | 射线 | 数据 | reference / geometry.Ray | 生成出的世界射线 方便你在拾取后继续复用这条射线做别的检测。 | - | 可选 |
hit | 是否命中 | 数据 | boolean | 是否找到目标 如果至少检测到一个碰撞体，这里就是 true；否则为 false。 | - | 可选 |
results | 命中结果数组 | 数据 | reference / array / physics.PhysicsRayResult | 全部检测结果 返回这次检测找到的所有结果。若你只关心最近的一个目标，可改用“最近命中”类节点。 | - | 可选 |
使用场景
- 点击屏幕选择 3D 对象
- 检测攻击范围或视线遮挡
- 根据射线结果决定移动、拾取或交互
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 物理查询依赖场景中的碰撞体配置。
- 全部拾取类节点可能返回多个结果，后续通常要遍历或筛选。
屏幕点 3D 最近拾取
屏幕点 3D 最近拾取：把“你点到的屏幕位置”直接换成 3D 场景里的检测，并返回最先点中的那个物体。 这是做 3D 点击选中、点地面移动、点敌人交互时最常用的节点之一。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | physicsPickScreenPointClosest |
| 分类 | 物理系统 |
| 二级分类 | 拾取 |
| 分组 | - |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 到达这里时，立即执行这次设置或查询。 | - | 可选 |
cameraComponent | 相机 | 数据 | cc.Component / Camera | 用于观察场景的相机 这个节点会用它把“你点击的屏幕位置”换算成场景里的检测方向。通常接当前主相机。 | - | 必填 |
x | 屏幕 X | 数据 | number | 屏幕 X 填写你点击或触摸到的屏幕坐标。通常来自鼠标位置或触摸位置。 | 输入框 默认值：0 | 必填 |
y | 屏幕 Y | 数据 | number | 屏幕 Y 填写你点击或触摸到的屏幕坐标。通常来自鼠标位置或触摸位置。 | 输入框 默认值：0 | 必填 |
mask | 碰撞掩码 | 数据 | number | 筛选范围 用来限制“只检查哪些碰撞体”。默认 0xffffffff 表示全部都检查；不确定时保持默认即可。 | 输入框 默认值：4294967295 | 可选 |
maxDistance | 最大距离 | 数据 | number | 最多检测多远 默认 10000000，通常足够大。只有你想明确限制检测距离时才需要修改。 | 输入框 默认值：10000000 | 可选 |
queryTrigger | 检测触发器 | 数据 | boolean | 是否把触发区域算进去 开启后，只负责触发事件的区域也会被算作命中。大多数情况下保持默认即可。 | 可编辑控件 默认值：true | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 继续执行 当前操作完成后，从这里继续后续流程。 | - | 可选 |
ray | 射线 | 数据 | reference / geometry.Ray | 生成出的世界射线 方便你在拾取后继续复用这条射线做别的检测。 | - | 可选 |
hit | 是否命中 | 数据 | boolean | 是否找到目标 如果至少检测到一个碰撞体，这里就是 true；否则为 false。 | - | 可选 |
result | 最近命中结果 | 数据 | reference / physics.PhysicsRayResult | 单个检测结果 返回这次查询得到的一个结果。3D 结果可继续从这个引脚拖线选择属性节点；2D 结构体结果可继续拆解成员。 | - | 可选 |
使用场景
- 点击屏幕选择 3D 对象
- 检测攻击范围或视线遮挡
- 根据射线结果决定移动、拾取或交互
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 物理查询依赖场景中的碰撞体配置。
- 全部拾取类节点可能返回多个结果，后续通常要遍历或筛选。