1. 项目概述：为什么3D物理射线检测是交互的基石

在任何一个3D游戏或交互应用中，当玩家点击屏幕，试图选中一个远处的宝箱、与NPC对话，或者用准星瞄准敌人时，背后默默工作的核心技术，十有八九就是物理射线检测。这听起来像是个深奥的图形学概念，但其实它的核心思想非常直观：想象你手里拿着一支无限长的激光笔，从屏幕上的某个点（比如你的点击位置）向虚拟世界的深处射出一道看不见的光线。这道光线碰到的第一个物体，就是你要交互的目标。在Cocos Creator 3.x中，这套由物理引擎驱动的射线检测系统，正是实现诸如物体拾取、子弹命中判定、视线检测、地面高度采样等几乎所有空间交互功能的“幕后英雄”。

我经历过不少项目，从简单的点击拾取道具，到复杂的策略游戏单位框选，再到FPS游戏的射击反馈，物理射线检测都是绕不开的一环。新手开发者最容易踩的坑，往往不是写不出检测代码，而是不理解射线检测背后的物理世界规则、坐标系的转换，以及性能上的取舍。比如，为什么有时候点击没反应？为什么射线穿过了物体却没检测到？为什么在大场景里频繁检测会导致卡顿？这些问题，都需要我们不仅知其然，更要知其所以然。

本指南的目的，就是带你从最基本的射线发射原理开始，一步步深入到Cocos Creator 3D物理引擎的底层逻辑，掌握如何高效、准确地进行物体拾取与碰撞检测。我会结合大量实际项目中的代码片段、参数配置心得和那些“坑”里总结出的经验，让你不仅能实现功能，更能理解背后的“为什么”，从而在面对复杂需求时游刃有余。

2. 核心原理拆解：射线、碰撞器与物理世界

在动手写代码之前，我们必须把几个核心概念和它们之间的关系彻底理清。很多模糊不清的问题，都源于对基础原理的一知半解。

2.1 物理射线（Ray）的本质是什么？

在Cocos Creator 3D中，一条射线（geometry.Ray）本质上是一个由起点（origin）和方向（direction）定义的数学线段。方向向量通常需要是单位向量（长度为1），这能确保计算的一致性。当你从屏幕点击点发射射线时，真正的过程是两步转换：

1. 屏幕坐标到世界坐标的起点：通过摄像机（Camera）的screenToWorld方法，将二维屏幕坐标（x, y）转换为三维世界空间中的一个点。这个点通常位于摄像机的近裁剪面上。
2. 构建方向向量：同样利用摄像机，通过screenPointToRay方法可以直接获得一条从摄像机近裁剪面指向远裁剪面的射线。其方向就是从摄像机位置指向屏幕点击点在远裁剪面对应点的向量，并归一化。

理解这一点至关重要：射线检测的起点和方向是基于世界坐标系的。如果你的物体不在世界坐标系的原点，或者你的摄像机有旋转，那么射线的计算就必须考虑这些变换。

2.2 碰撞器（Collider）：物体的“物理外壳”

射线要检测到物体，物体必须有一个“物理外壳”，这就是碰撞器（Collider）。Cocos Creator 3D支持多种类型的碰撞器，最常用的有：

• 盒碰撞器（BoxCollider）：一个轴对齐的立方体。性能最好，适用于箱子、门、墙壁等规则物体。
• 球碰撞器（SphereCollider）：一个球体。计算速度快，适用于球形道具、粗略的角色范围检测。
• 胶囊碰撞器（CapsuleCollider）：一个胶囊体。非常适合用于角色控制器，因为它结合了圆柱体的垂直性和球体的圆滑顶部。
• 网格碰撞器（MeshCollider）：使用模型的实际网格作为碰撞形状。最精确，但性能开销最大，通常只用于静态的复杂场景物体（如地形、复杂建筑）。

注意：一个常见的误解是，只要模型渲染出来了，就能被射线检测到。不对！必须为需要被检测的节点添加相应的碰撞器组件，它才会被物理引擎“看见”。你可以把渲染器（MeshRenderer）理解为物体的“皮肤”，而碰撞器是它的“骨骼”或“碰撞体积”。

2.3 物理世界（PhysicsWorld）与射线检测查询

所有的碰撞器都存在于一个全局的物理世界（physics.PhysicsSystem.instance）中。当你调用射线检测方法时，实际上是向这个物理世界发起一次查询：“从我射线的起点，沿着这个方向，第一个碰到的是谁？”

Cocos Creator 3D的物理引擎（内置为Cannon.js或可选插件如PhysX）会进行复杂的数学计算，判断射线与场景中每个碰撞器的包围盒或精确形状是否相交，并返回相交点的信息（如点坐标、法线、碰撞的物体等）。

这里有一个关键选择：使用物理引擎的射线检测，还是使用图形学的射线检测（如与模型三角面求交）？对于游戏中的绝大多数交互（拾取、射击、地面检测），使用物理引擎的碰撞器进行检测是完全足够且性能最优的。因为碰撞器通常是简化过的几何体（如包围盒、球体），计算量远小于与成千上万个三角面求交。只有在你需要极其精确的、像素级的拾取（比如模型编辑工具）时，才需要考虑后者。

3. 基础入门：实现一个简单的屏幕点击拾取

让我们从一个最经典的需求开始：点击屏幕上的3D物体，在控制台输出它的名字。

3.1 场景与节点设置

首先，在场景中放置一个可以被点击的物体，例如一个Cube（立方体）。

1. 创建一个Cube节点（或使用任何3D模型）。
2. 选中这个Cube节点，在属性检查器中点击添加组件->物理组件->盒型碰撞器 (BoxCollider)。你会看到Cube被一个绿色的线框包围，这就是碰撞器的可视化范围。你可以调整碰撞器组件中的Size属性，让它更贴合你的模型。
3. 确保这个节点有一个用于标识的Node名称，比如“TargetCube”。

3.2 编写点击检测脚本

创建一个TypeScript脚本（例如RaycastExample.ts），挂载到场景中的任意一个持久节点上（比如Canvas或一个专门的Manager节点）。

import { _decorator, Component, Node, input, Input, EventTouch, Camera, geometry, PhysicsSystem, physics } from 'cc'; const { ccclass, property } = _decorator; @ccclass('RaycastExample') export class RaycastExample extends Component { @property(Camera) mainCamera: Camera = null!; // 主摄像机，用于屏幕坐标到射线的转换 onLoad() { // 监听触摸开始事件 input.on(Input.EventType.TOUCH_START, this.onTouchStart, this); } onDestroy() { // 记得移除监听，防止内存泄漏 input.off(Input.EventType.TOUCH_START, this.onTouchStart, this); } onTouchStart(event: EventTouch) { // 1. 获取触摸点在屏幕上的坐标 const touchPos = event.getLocation(); // 2. 通过摄像机，将屏幕点转换为一条世界空间中的射线 const outRay = new geometry.Ray(); this.mainCamera.screenPointToRay(touchPos.x, touchPos.y, outRay); // 3. 执行射线检测 // 参数：射线，检测选项，最大检测距离，检测掩码（默认0xffffffff） if (PhysicsSystem.instance.raycast(outRay)) { // 4. 获取所有检测结果 const results = PhysicsSystem.instance.raycastResults; // 通常我们取第一个命中的结果（距离射线起点最近的） if (results.length > 0) { const firstResult = results[0]; const hitNode = firstResult.collider.node; console.log(`点击到了物体：${hitNode.name}`); // 你可以在这里做更多事情，比如高亮物体、触发事件等 } } else { console.log('什么都没点到'); } } }

3.3 关键参数解析与常见问题

• screenPointToRay：这是最关键的一步。它封装了从屏幕到世界坐标的复杂转换。务必确保传入的mainCamera引用是正确的、用于渲染场景的主摄像机。
• PhysicsSystem.instance.raycast：这是发起检测的核心方法。它返回一个布尔值，表示是否有碰撞发生。真正的检测结果存储在PhysicsSystem.instance.raycastResults这个静态数组中。
• 检测结果（RaycastResult）：这个对象包含丰富的信息：
  • collider: 命中的碰撞器组件。
  • node: 命中的碰撞器所在的节点（最常用的属性）。
  • hitPoint: 射线与碰撞器相交点的世界坐标。
  • distance: 从射线起点到相交点的距离。
  • normal: 相交点处碰撞器表面的法线向量（可用于反弹计算等）。
• 常见问题1：点击没反应
  • 检查碰撞器：确认目标节点是否添加了正确的碰撞器组件，并且组件处于启用状态。
  • 检查摄像机：确认脚本中引用的摄像机是否正确，并且该摄像机正在渲染你点击的区域。
  • 检查节点层级：确保目标节点及其父节点没有被禁用（active属性为false）。
  • 检查碰撞分组：这是新手高级坑，后面会详细讲。
• 常见问题2：射线穿过了物体但没检测到
  • 可能是检测距离不够。raycast方法有一个maxDistance参数，默认值可能不够大。如果你的物体离摄像机起点很远，需要显式设置一个较大的值，例如：PhysicsSystem.instance.raycast(outRay, physics.ERaycastOption.ANY, 1000)。

4. 进阶技巧：精准过滤与性能优化

当场景中有成百上千个物体时，无差别的全局射线检测会成为性能瓶颈。同时，你可能只想检测特定类型的物体（比如只检测可拾取道具，忽略地面和墙壁）。这就需要用到碰撞分组和掩码过滤。

4.1 理解碰撞分组与掩码（Mask）

Cocos Creator 3D的物理系统使用一个32位的掩码系统来管理哪些物体之间可以发生碰撞或射线检测。每个碰撞器（Collider）都有两个关键属性：

• Group：这个碰撞器属于哪个分组。例如，你可以定义分组：PLAYER = 1, ENEMY = 2, BULLET = 4, PICKABLE = 8, SCENERY = 16。
• Mask：这个碰撞器可以与哪些分组的物体发生交互。它是一个位掩码。

交互规则：当两个物体A和B可能发生交互时，系统会检查(A.Group & B.Mask) && (B.Group & A.Mask)。只有当这两个条件都为真时，交互才会发生。

对于射线检测，规则类似：射线的检测掩码（在raycast方法中传入）会与碰撞器的Group进行按位与(&)操作，结果非零则这个碰撞器才会被检测。

4.2 实战：实现只拾取可交互道具

假设我们定义：

• 可拾取道具的分组为PICKABLE = (1 << 0)，即二进制第0位为1。
• 地面和墙壁的分组为SCENERY = (1 << 1)。

步骤1：设置分组在项目设置 -> 物理 -> 碰撞矩阵中，可以预设分组。更动态的方式是在代码中定义：

// 定义分组常量，使用位运算左移来确保每位独立 export enum PhysicsGroup { DEFAULT = 0, PICKABLE = 1 << 0, // 1 SCENERY = 1 << 1, // 2 PLAYER = 1 << 2, // 4 // ... 可以继续定义 }

步骤2：为物体设置分组在物体节点的碰撞器组件上，或者在代码中设置：

// 假设有一个道具节点 propNode const collider = propNode.getComponent(BoxCollider); if (collider) { collider.setGroup(PhysicsGroup.PICKABLE); // 通常，我们希望道具能与默认分组和玩家分组发生碰撞，但这里主要关注射线检测 collider.setMask(PhysicsGroup.DEFAULT | PhysicsGroup.PLAYER); }

步骤3：在射线检测时使用掩码修改之前的射线检测代码：

onTouchStart(event: EventTouch) { const touchPos = event.getLocation(); const outRay = new geometry.Ray(); this.mainCamera.screenPointToRay(touchPos.x, touchPos.y, outRay); // 关键：只检测属于 PICKABLE 分组的物体 const mask = PhysicsGroup.PICKABLE; // 使用 raycastClosest 可以只获取最近的一个结果，性能更好 if (PhysicsSystem.instance.raycastClosest(outRay, mask, 1000)) { const result = PhysicsSystem.instance.raycastClosestResult; const hitNode = result.collider.node; console.log(`拾取了道具：${hitNode.name}`); // 触发拾取逻辑，比如让道具飞向玩家、播放音效、销毁节点等 hitNode.destroy(); } // 忽略其他分组的物体，不会进入这个判断 }

通过这种方式，你的点击只会对“可拾取道具”生效，点击地面或角色模型不会有任何反应。这极大地提升了交互的精准度和逻辑清晰度。

4.3 性能优化策略

1. 使用raycastClosest替代raycast：如果你只需要知道最近的一个命中目标（比如点击拾取、子弹命中），一定要用raycastClosest。物理引擎在找到第一个有效命中后就会停止计算，比raycast（收集所有命中）快得多。
2. 合理设置最大检测距离（maxDistance）：不要无脑设置一个超大值（如99999）。根据你的游戏场景尺度，设置一个合理的值。例如，在一个室内场景中，检测距离设为50米可能就绰绰有余了。
3. 善用碰撞分组掩码：这是最重要的优化手段。通过精细的分组设计，确保每次射线检测只与极少数的候选碰撞器进行求交计算。例如，UI射线、游戏世界射线、子弹射线应该使用不同的掩码。
4. 避免每帧进行大量射线检测：例如，如果需要用射线检测来实现角色是否着地（Ground Check），不必每帧都检测。可以降低检测频率，或者仅在角色y轴速度向下或即将着陆的几帧内进行检测。
5. 对于静态物体，使用合适的碰撞器：永远不要对不会移动的复杂场景使用MeshCollider。尽量用多个简单的BoxCollider或SphereCollider来近似。地形可以考虑使用高度场碰撞器（如果物理引擎支持）。

5. 复杂场景应用：从物体拾取到游戏机制

掌握了基础和优化后，我们可以将射线检测应用到更丰富的游戏场景中。

5.1 3D物体拖拽与放置

实现思路：在TOUCH_START时发射射线检测可拖拽物体。如果命中，则记录该物体和初始点击偏移量。在TOUCH_MOVE时，再次从屏幕点发射射线，但这次是射向一个虚拟的“放置平面”（比如XZ地面平面），计算射线与平面的交点，作为物体新的目标位置。

// 简化的拖拽逻辑示例 private _draggingNode: Node | null = null; private _offset: Vec3 = new Vec3(); onTouchStart(event: EventTouch) { const touchPos = event.getLocation(); const ray = new geometry.Ray(); this.camera.screenPointToRay(touchPos.x, touchPos.y, ray); if (PhysicsSystem.instance.raycastClosest(ray, this.draggableMask, 1000)) { const result = PhysicsSystem.instance.raycastClosestResult; this._draggingNode = result.collider.node; // 计算点击点在世界空间与物体位置的偏移 const hitPoint = result.hitPoint; const nodePos = this._draggingNode.worldPosition; Vec3.subtract(this._offset, nodePos, hitPoint); // 监听移动事件 input.on(Input.EventType.TOUCH_MOVE, this.onTouchMove, this); input.on(Input.EventType.TOUCH_END, this.onTouchEnd, this); } } onTouchMove(event: EventTouch) { if (!this._draggingNode) return; const touchPos = event.getLocation(); const ray = new geometry.Ray(); this.camera.screenPointToRay(touchPos.x, touchPos.y, ray); // 假设地面是Y=0的平面 const plane = geometry.Plane.fromPoints(new Vec3(0,0,0), new Vec3(1,0,0), new Vec3(0,0,1)); const outPoint = new Vec3(); // 计算射线与地面的交点 if (geometry.intersect.rayPlane(ray, plane, outPoint)) { // 应用之前计算的偏移量 outPoint.add(this._offset); this._draggingNode.setWorldPosition(outPoint); } } onTouchEnd() { this._draggingNode = null; input.off(Input.EventType.TOUCH_MOVE, this.onTouchMove, this); input.off(Input.EventType.TOUCH_END, this.onTouchEnd, this); }

5.2 第一人称/第三人称射击游戏的命中检测

对于射击游戏，射线检测是判断子弹是否命中的核心。通常有两种做法：

1. 客户端预测+服务器验证（权威服务器）：在玩家开枪的瞬间，客户端立即发射一条射线进行检测，并播放命中特效（火花、血花），给玩家即时反馈。同时，将开枪的参数（位置、方向、时间戳）发送给服务器。服务器在同样的游戏逻辑帧下，用同样的参数进行射线检测，并裁决最终结果。如果客户端结果与服务器不一致，则以服务器为准，并进行位置修正（这可能会产生“回滚”效应）。
2. 纯客户端检测（非对称或P2P游戏）：对于要求不高的游戏或单机游戏，可以直接使用客户端的射线检测结果。

射击检测的要点：

• 射线起点：通常不是摄像机中心，而是从枪口模型（muzzle）的世界位置发射。
• 方向：对于第一人称，方向就是摄像机的前向量。对于需要模拟弹道的游戏，方向可能需要加入一个随机的散布角（spread）。
• 分层检测：子弹通常能穿透某些物体（如薄木板），但不能穿透墙壁。这需要更复杂的检测逻辑，比如使用raycast获取所有命中点，然后根据物体的材质属性判断是否停止检测。

5.3 策略游戏的矩形框选（Box Selection）

框选不是一条射线，而是一个从屏幕空间拖拽形成的2D矩形，需要转换为3D空间的一个视锥体（Frustum）或一个区域，然后检测哪些单位在这个区域内。

简化实现思路：

1. 在鼠标拖拽开始和结束时，记录两个屏幕角点p1和p2。
2. 将这两个屏幕点，分别与摄像机的近、远裁剪面结合，可以构造出4条射线（矩形的四个角射向远裁剪面），这四条射线在近裁剪面和远裁剪面之间围成了一个平截头体。
3. 更实用的方法是：遍历所有可选中的单位，将它们的世界坐标通过摄像机转换到屏幕坐标，然后判断这个屏幕坐标是否在p1和p2定义的矩形内。这种方法虽然不够“物理”，但计算量小，实现简单，对于策略游戏单位通常足够精确。

// 伪代码：屏幕矩形框选检测 selectUnitsInScreenRect(rect: Rect) { const selectedUnits: Unit[] = []; for (const unit of allUnits) { const worldPos = unit.node.worldPosition; const screenPos = new Vec3(); // 将单位的世界坐标转换为屏幕坐标 this.mainCamera.worldToScreen(screenPos, worldPos); // 判断屏幕坐标是否在矩形内 if (rect.contains(screenPos.x, screenPos.y)) { selectedUnits.push(unit); } } return selectedUnits; }

6. 调试技巧与高级话题

6.1 可视化调试射线

在开发过程中，肉眼看不到射线是一件很痛苦的事情。我们可以通过绘制调试线段来可视化射线。

import { debug } from 'cc'; // ... onTouchStart(event: EventTouch) { const touchPos = event.getLocation(); const ray = new geometry.Ray(); this.camera.screenPointToRay(touchPos.x, touchPos.y, ray); // 可视化射线：从起点画一条长度为100的线 const rayEnd = new Vec3(); Vec3.scaleAndAdd(rayEnd, ray.o, ray.d, 100); debug.DrawLine(ray.o, rayEnd, Color.GREEN, 1.0); // 绿色，持续1秒 // ... 执行检测 if (PhysicsSystem.instance.raycastClosest(ray, this.mask, 100)) { const result = PhysicsSystem.instance.raycastClosestResult; // 可视化命中点 debug.DrawLine(result.hitPoint, Vec3.add(new Vec3(), result.hitPoint, result.normal), Color.RED, 1.0); } }

在Cocos Creator编辑器的游戏预览窗口中，你就能看到画出的绿色射线和红色的命中点法线了。这是排查“射线方向不对”、“起点不对”等问题的最直观方法。

6.2 穿透检测与形状投射（Shape Cast）

有时我们需要的不是一条线，而是一个有体积的形状（如胶囊体、盒子）沿着路径移动，检测其是否会与场景发生碰撞。这被称为形状投射（Shape Cast）或扫描测试（Sweep Test）。典型的应用场景包括：

• 角色移动预判：在移动角色前，用一个胶囊体沿着移动方向扫描，判断是否会撞墙，从而提前阻止穿墙。
• 投掷物体积碰撞：一个滚动的巨石，需要用球体进行扫描检测。

Cocos Creator的物理系统（特别是Cannon.js后端）提供了PhysicsSystem.instance.sweepBox、sweepSphere、sweepCapsule等方法。其原理与射线检测类似，但计算的是整个几何体在运动过程中与其它碰撞器的重叠情况，返回的是从起点到第一次发生碰撞的分数（fraction）和碰撞信息。

// 示例：胶囊体扫描，用于角色控制器 const capsule = new physics.Capsule(radius, height); const startPos = new Vec3(0, 1, 0); const endPos = new Vec3(10, 1, 0); // 想要移动到的位置 const orientation = Quat.IDENTITY; const mask = PhysicsGroup.WALL; if (PhysicsSystem.instance.sweepCapsule(capsule, startPos, endPos, orientation, mask)) { const result = PhysicsSystem.instance.sweepResults[0]; // result.fraction 是一个0-1的值，表示从startPos到endPos的路径上，在多大比例的位置发生了碰撞 // 我们可以计算安全的移动位置：Vec3.lerp(safePos, startPos, endPos, result.fraction - 0.01); console.log(`在路径的 ${result.fraction * 100}% 处会发生碰撞`); }

6.3 与UI系统的交互优先级处理

在3D游戏中，通常还会有2D UI界面（如按钮、血条）。当玩家点击屏幕时，系统需要决定是优先响应UI点击还是3D世界的射线检测。Cocos Creator的事件系统采用冒泡机制，通常UI节点会位于更上层。

标准做法是：

1. 首先检查点击是否落在任何可交互的UI组件（如Button）上。这由Cocos的UI事件系统自动处理。
2. 如果没有任何UI拦截该点击事件（即事件没有被标记为propagationStopped），再将事件传递给你的3D射线检测逻辑。

你可以在监听触摸事件时，通过检查事件是否已被UI处理来决定是否进行3D检测：

onTouchStart(event: EventTouch) { // 如果事件已经被UI组件处理并停止冒泡，则不再进行3D检测 if (event.propagationStopped) { return; } // ... 执行3D射线检测逻辑 }

另一种更清晰的设计模式是，将UI层和3D游戏世界的输入监听分开，通过一个中央的输入管理器来协调，根据当前游戏状态（如是否打开了背包界面）来决定将输入派发给哪个系统。

从一条简单的屏幕射线到复杂的形状投射，从基础的点击拾取到支撑起射击、策略、拖拽等核心玩法，物理射线检测是3D交互开发中不可或缺的工具。理解其原理，善用分组掩码进行优化，掌握调试方法，就能让它在你的项目中稳定高效地运行。最关键的是多动手实践，在不同的场景中尝试应用，并观察和调试结果，积累的经验会让你在面对任何交互需求时都能快速找到解决方案。