Unity基础学习（十二）Unity 物理系统之范围检测

        

目录

一、关于范围检测的主要API：

1. 盒状范围检测 Physics.OverlapBox

2. 球形范围检测 Physics.OverlapSphere

3. 胶囊范围检测 Physics.OverlapCapsule

4. 盒状检测 NonAlloc 版

5. 球形检测 NonAlloc 版

6. 胶囊检测 NonAlloc 版

二、关于API中的两个重点参数

QueryTriggerInteraction 参数详解 

1. QueryTriggerInteraction.UseGlobal

2. QueryTriggerInteraction.Collide

3. QueryTriggerInteraction.Ignore

LayerMask 在范围检测中的深度解析

1. 层级系统基础

2. LayerMask 本质

层级选择：精准定位目标层

基础选择方法

高级选择方式

 层级合并：组合检测

基本合并技巧

层级排除：精准过滤 

常见错误：

1. 层名拼写错误（静默失败）

2. 位运算优先级错误

3. 掩码值为0（不检测任何层）

4. 混淆层索引和掩码值 这个最常见

三、总结

 基本范围检测函数

高效 NonAlloc 版本

 关键参数详解表

通用参数（所有检测函数）

盒状检测特有参数

球形检测特有参数

胶囊检测特有参数

NonAlloc 版本特有参数

 LayerMask 操作指南

 高频错误及解决方案

---

        在前面的内容中，我们学习了关于碰撞的检测相关，今天我们来看看指定范围的检测，这个检测是什么呢？就是瞬时检测指定空间内的碰撞器对象（无实体碰撞效果），适用于技能攻击、区域触发等场景。

        那么被检测的对象需要具备些什么条件呢？被检测对象 必须挂载碰撞器（Collider）（无需 Rigidbody）。

一、关于范围检测的主要API：

1. 盒状范围检测 Physics.OverlapBox

参数相关：

Collider[] Physics.OverlapBox(Vector3 center,                 // 盒子中心点（世界坐标）Vector3 halfExtents,            // 盒子三边尺寸（半长，非全尺寸）Quaternion orientation,         // 盒子旋转角度int layerMask = AllLayers,      // 层级掩码（默认所有层）QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal
)

返回值：检测范围内的所有碰撞器组成的数组（无碰撞时返回空数组）

例如：

void CheckAttackRange()
{// 在玩家前方1米处创建2x2x2的检测盒Vector3 center = transform.position + transform.forward;Vector3 size = new Vector3(2, 2, 2);int enemyLayer = 1 << LayerMask.NameToLayer("Enemy");Collider[] hits = Physics.OverlapBox(center,size / 2,  // 注意：参数是半长尺寸transform.rotation,enemyLayer,QueryTriggerInteraction.Ignore);foreach (Collider col in hits){Enemy enemy = col.GetComponent<Enemy>();if(enemy != null) enemy.TakeDamage(10);}// 调试绘制Debug.DrawLine(transform.position, center, Color.red, 0.5f);
}

实际上你看不到他的检测范围的，你要自己想象。 

 

2. 球形范围检测 Physics.OverlapSphere

参数相关：

Collider[] Physics.OverlapSphere(Vector3 position,               // 球心位置（世界坐标）float radius,                   // 球体半径int layerMask = AllLayers,      // 层级掩码QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal
)

返回值：球体内的所有碰撞器数组 

void DetectNearbyItems()
{// 检测周围5米内的可收集物品int itemLayer = LayerMask.GetMask("Collectibles");float detectRadius = 5f;Collider[] items = Physics.OverlapSphere(transform.position,detectRadius,itemLayer);foreach (Collider item in items){item.GetComponent<Collectible>().Highlight();}// 调试绘制Gizmos.color = Color.cyan;Gizmos.DrawWireSphere(transform.position, detectRadius);
}

这个球形的和上面的一样，就只是参数不同而已，形状不同，效果都是碰撞检测，还有下面的胶囊检测也是如此。 

3. 胶囊范围检测 Physics.OverlapCapsule

参数相关：

Collider[] Physics.OverlapCapsule(Vector3 point0,                 // 胶囊体底部球心Vector3 point1,                 // 胶囊体顶部球心float radius,                   // 胶囊半径int layerMask = AllLayers,      // 层级掩码QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal
)

例如：

void CheckCharacterHit()
{// 检测玩家角色碰撞（高度2米，半径0.5米）Vector3 feetPos = transform.position;Vector3 headPos = feetPos + Vector3.up * 2;float charRadius = 0.5f;int playerLayer = LayerMask.GetMask("Player");Collider[] hits = Physics.OverlapCapsule(feetPos,headPos,charRadius,playerLayer);if (hits.Length > 0){Debug.Log("Player character hit detected!");}
}

         上面的三个API只是最基本的范围检测，他们还有好兄弟。你不需要将返回值碰撞器数组存下来，可以直接在外部创建一个数组，然后装入这个数组中即可：

4. 盒状检测 NonAlloc 版

int Physics.OverlapBoxNonAlloc(Vector3 center,                 // 盒子中心点Vector3 halfExtents,            // 盒子半尺寸（长/宽/高各一半）Collider[] results,             // 结果存储数组（预分配）Quaternion orientation = Quaternion.identity, // 旋转角度int layerMask = AllLayers,      // 层级掩码QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal
)

返回值：实际检测到的碰撞器数量（非数组长度） 

5. 球形检测 NonAlloc 版

int Physics.OverlapSphereNonAlloc(Vector3 position,               // 球心位置float radius,                   // 球体半径Collider[] results,             // 结果存储数组int layerMask = AllLayers,      // 层级掩码QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal
)

返回值：实际检测到的碰撞器数量 

6. 胶囊检测 NonAlloc 版

int Physics.OverlapCapsuleNonAlloc(Vector3 point0,                 // 胶囊底部球心Vector3 point1,                 // 胶囊顶部球心float radius,                   // 胶囊半径Collider[] results,             // 结果存储数组int layerMask = AllLayers,      // 层级掩码QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal
)

返回值：实际检测到的碰撞器数量

使用手段都是和前三个差不多的

NonAlloc 方法核心优势

特性	基础方法 (OverlapX)	NonAlloc 方法 (OverlapXNonAlloc)
内存分配	每次调用创建新数组	使用预分配数组，无GC开销
性能影响	高频调用导致GC压力	零内存分配，性能稳定
使用场景	低频/单次检测	高频检测（如Update中）
返回值	Collider[] 数组	int (实际检测数量)

二、关于API中的两个重点参数

QueryTriggerInteraction 参数详解 

QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal 是 Unity 物理检测 API 中的一个重要参数，用于控制物理检测如何处理触发器(Trigger)。实际上一般默认的就OK

这个参数决定了在物理检测（如范围检测、射线检测等）中是否应该包括触发器碰撞器：

1. 控制检测行为：指定是否将触发器视为有效的碰撞对象

2. 避免意外结果：防止触发器干扰正常的物理检测逻辑

3. 灵活配置：可以覆盖项目的全局设置

1. QueryTriggerInteraction.UseGlobal

行为：使用项目的全局物理设置
说明：检测行为取决于 "Edit > Project Settings > Physics" 中的 "Queries Hit Triggers" 设置

推荐场景：
希望检测行为与项目全局设置保持一致时
不特别关注触发器处理方式时

2. QueryTriggerInteraction.Collide

行为：包含触发器在检测结果中
说明：无论项目全局设置如何，本次检测都会将触发器视为有效碰撞体

推荐场景：
需要检测区域触发器时（如进入安全区、收集区域）
需要响应触发器事件时

3. QueryTriggerInteraction.Ignore

行为：忽略所有触发器
说明：无论项目全局设置如何，本次检测都会跳过所有触发器

推荐场景：
只关心实体碰撞时（如攻击检测、物理碰撞）
避免触发器干扰检测结果时

示例：不同参数的效果

注： ：这种写法叫做可选参数。

// 检测所有碰撞体（包括普通碰撞器和触发器）
Collider[] allHits = Physics.OverlapSphere(position: transform.position,radius: 5f,layerMask: LayerMask.GetMask("Enemy", "Trap", "SafeZone"),queryTriggerInteraction: QueryTriggerInteraction.Collide
);
// 结果：包含敌人、陷阱区域、安全区// 只检测实体碰撞体（忽略所有触发器）
Collider[] physicalHits = Physics.OverlapSphere(position: transform.position,radius: 5f,layerMask: LayerMask.GetMask("Enemy", "Trap", "SafeZone"),queryTriggerInteraction: QueryTriggerInteraction.Ignore
);
// 结果：只包含敌人（陷阱区域和安全区是触发器，被忽略）// 使用全局设置检测
Collider[] globalSettingHits = Physics.OverlapSphere(position: transform.position,radius: 5f,layerMask: LayerMask.GetMask("Enemy", "Trap", "SafeZone"),queryTriggerInteraction: QueryTriggerInteraction.UseGlobal
);
// 结果：取决于项目设置中的"Queries Hit Triggers"选项

LayerMask 在范围检测中的深度解析

LayerMask 核心概念

1. 层级系统基础

Unity 提供 32 个层级（0-31）
每个游戏对象分配到一个层级
层级用于逻辑分组（如：玩家、敌人、环境、UI等）

2. LayerMask 本质

32 位位掩码（bitmask）
每个位对应一个层级（1=包含，0=排除）
示例：00000000 00000000 00000000 00000101 表示包含第0层和第2层

可以在这里进行创建层级

通过代码来获取层级：

// 单层级
int enemyLayer = LayerMask.NameToLayer("Enemy");
LayerMask enemyMask = 1 << enemyLayer;// 多层级组合
LayerMask enemyAndObstacleMask = (1 << LayerMask.NameToLayer("Enemy")) | (1 << LayerMask.NameToLayer("Obstacle"));// 排除特定层
LayerMask allExceptUI = ~(1 << LayerMask.NameToLayer("UI"));//或者
// 包含多个层级
LayerMask mask = LayerMask.GetMask("Enemy", "Projectile", "Destructible");// 等效于：
// (1 << LayerMask.NameToLayer("Enemy")) |
// (1 << LayerMask.NameToLayer("Projectile")) |
// (1 << LayerMask.NameToLayer("Destructible"))

接下来咱们讲讲为什么它会这么进行设计，和如何进行层级的选择，合并，排除。

        因为位运算很快，而且非常的适合做状态合并与排除。你只需要将对应位置的数置0即排除，置1就合并了。利用，位与，位或进行操作。 

层级选择：精准定位目标层

基础选择方法

// 选择单个层级
LayerMask enemyMask = 1 << LayerMask.NameToLayer("Enemy");// 选择多个层级
LayerMask combatMask = (1 << LayerMask.NameToLayer("Enemy")) | (1 << LayerMask.NameToLayer("Boss"));

高级选择方式

// 使用 GetMask 更简洁
LayerMask environmentMask = LayerMask.GetMask("Ground", "Water", "Wall");

 层级合并：组合检测

基本合并技巧

// 创建基础掩码
LayerMask baseMask = LayerMask.GetMask("Player", "Enemy");// 动态添加层级
void AddLayerToMask(ref LayerMask mask, string layerName)
{int layer = LayerMask.NameToLayer(layerName);if (layer != -1) {mask |= (1 << layer);  // 按位或操作}
}// 使用
AddLayerToMask(ref baseMask, "Projectile");

多掩码组合

// 定义不同类别的掩码
LayerMask characterMask = LayerMask.GetMask("Player", "NPC", "Enemy");
LayerMask environmentMask = LayerMask.GetMask("Ground", "Wall", "Water");
LayerMask interactableMask = LayerMask.GetMask("Chest", "Door", "Lever");// 组合掩码
LayerMask fullDetectionMask = characterMask | environmentMask | interactableMask;

层级排除：精准过滤 

// 所有层
LayerMask allLayers = ~0; // 或 Physics.AllLayers// 排除 UI 层
int uiLayer = LayerMask.NameToLayer("UI");
LayerMask noUIMask = allLayers & ~(1 << uiLayer);// 排除多个层
int ignoreLayer1 = LayerMask.NameToLayer("IgnoreRaycast");
int ignoreLayer2 = LayerMask.NameToLayer("Water");
LayerMask filteredMask = allLayers & ~((1 << ignoreLayer1) | (1 << ignoreLayer2));

假设你要排除的层级：00000000 00000000 00000000 00001001

取反后                         11111111   11111111   11111111   11110110

全层级                         11111111   11111111   11111111   11111111

相与后，便排除了指定层级

常见错误：

1. 层名拼写错误（静默失败）

// 错误：层名拼错无提示
LayerMask mask = 1 << LayerMask.NameToLayer("Enemi"); // 返回 -1// 解决方案：验证层名
int GetLayerSafe(string layerName)
{int layer = LayerMask.NameToLayer(layerName);if (layer == -1){Debug.LogError($"Layer '{layerName}' does not exist!");return 0; // 默认层}return layer;
}

2. 位运算优先级错误

// 错误：运算优先级问题
LayerMask wrongMask = 1 << 8 | 1 << 9; // 实际是 (1 << 8) | (9)!// 正确：使用括号明确优先级
LayerMask correctMask = (1 << 8) | (1 << 9);

3. 掩码值为0（不检测任何层）

// 常见于动态构建掩码失败
LayerMask emptyMask = 0; // 不检测任何层// 防护：添加默认层
if (mask == 0)
{mask = 1 << 0; // 至少包含默认层Debug.LogWarning("Empty layer mask, using default layer");
}

4. 混淆层索引和掩码值 这个最常见

// 错误：传入层索引而非掩码
int enemyLayer = LayerMask.NameToLayer("Enemy");
Physics.Raycast(..., enemyLayer); // 应该传入 1 << enemyLayer// 正确：始终使用位掩码
Physics.Raycast(..., 1 << enemyLayer);

三、总结

 基本范围检测函数

​函数名​	​返回值​	​核心功能​
Physics.OverlapBox	Collider[]	检测盒状区域内的碰撞器
Physics.OverlapSphere	Collider[]	检测球形区域内的碰撞器
Physics.OverlapCapsule	Collider[]	检测胶囊区域内的碰撞器

高效 NonAlloc 版本

​函数名​	​返回值​	​核心优势​
Physics.OverlapBoxNonAlloc	int	零GC分配，适合高频调用
Physics.OverlapSphereNonAlloc	int	预分配数组，性能稳定
Physics.OverlapCapsuleNonAlloc	int	返回实际碰撞数量而非数组

---

 关键参数详解表

通用参数（所有检测函数）

​参数名​	​类型​	​说明​
layerMask	int	层级掩码（位运算值），决定检测哪些层
queryTriggerInteraction	enum	触发器处理方式： UseGlobal-用项目设置 Collide-包含触发器 Ignore-忽略触发器

盒状检测特有参数

​参数名​	​类型​	​说明​	​注意事项​
center	Vector3	盒子中心点（世界坐标）
halfExtents	Vector3	三边尺寸的一半​（非全尺寸）	例：2x2x2盒子需传入(1,1,1)
orientation	Quaternion	盒子的旋转角度	默认Quaternion.identity

球形检测特有参数

​参数名​	​类型​	​说明​
position	Vector3	球心位置（世界坐标）
radius	float	球体半径

胶囊检测特有参数

​参数名​	​类型​	​说明​
point0	Vector3	胶囊底部球心（世界坐标）
point1	Vector3	胶囊顶部球心（世界坐标）
radius	float	胶囊半径

NonAlloc 版本特有参数

​参数名​	​类型​	​说明​
results	Collider[]	预分配的碰撞器数组（避免GC分配）

---

 LayerMask 操作指南

​操作类型​	​代码示例​	​说明​
单层选择	1 << LayerMask.NameToLayer("Enemy")	位左移构建掩码
多层合并	LayerMask.GetMask("Enemy", "Boss")	官方推荐的多层获取方式
动态添加层	`mask	= (1 << LayerMask.NameToLayer("Projectile"))`
排除特定层	LayerMask filteredMask = ~0 & ~(1 << LayerMask.NameToLayer("UI"))	取反+位与实现层排除
所有层	Physics.AllLayers 或 ~0	32位全1掩码

---

 高频错误及解决方案

​错误类型​	​错误示例​	​正确写法​	​解决方案​
层名拼写错误	NameToLayer("Enemi")	验证层名是否存在	添加层名检查逻辑
位运算优先级错误	`1 << 8	1 << 9`	`(1 << 8)
空掩码	LayerMask mask = 0	添加默认层兜底	mask = mask==0 ? 1<<0 : mask
混淆层索引与掩码	Physics.Raycast(..., enemyLayer)	Physics.Raycast(..., 1<<enemyLayer)	始终使用位掩码格式
盒状尺寸参数错误	OverlapBox(center, fullSize, ...)	OverlapBox(center, fullSize/2, ...)	牢记用半长尺寸