# 3. Layers Matrix and Queries
Part of [[Physics 3D]]. Previous: [[2. Colliders and Physics Materials]]. Next: [[4. Joints]].
**Docs:** [Layer-based collision detection](https://docs.unity3d.com/6000.5/Documentation/Manual/LayerBasedCollision.html) · [Physics.RaycastNonAlloc](https://docs.unity3d.com/6000.5/Documentation/ScriptReference/Physics.RaycastNonAlloc.html)
## 3.1 Layers vs Layer Collision Matrix
**GameObject Layer** (Inspector top) is a category. The **Layer Collision Matrix** (`Edit > Project Settings > Physics`) is a checkbox grid: unchecked pairs **never** generate physics collisions ([Manual](https://docs.unity3d.com/6000.5/Documentation/Manual/LayerBasedCollision.html)).
Typical project layout:
| Layer | Collides with |
|---|---|
| Default | World, props |
| Player | World, props, enemies — **not** Player |
| Enemy | World, Player — maybe not Enemy (or yes for crowding) |
| IgnoreRaycast | Matrix + query masks |
| Projectile | Enemy, World — not Player ally projectiles |
Query `layerMask` bits are **independent** of the collision matrix: a Raycast can hit a layer even if that layer does not *physically collide* with the caster's layer. Use both deliberately — sensing ([[Organic Enemy Sensing]], [[Enemy AI State Machine]]) often raycasts layers that do not block movement.
## 3.2 Raycast (allocating vs NonAlloc)
```csharp
using UnityEngine;
public class GroundProbe : MonoBehaviour
{
[SerializeField] float distance = 1.2f;
[SerializeField] LayerMask groundMask;
readonly RaycastHit[] _hits = new RaycastHit[8];
public bool TryGetGround(out RaycastHit hit)
{
// Allocating convenience API — fine for editor tools / rare checks
if (Physics.Raycast(transform.position, Vector3.down, out hit, distance, groundMask,
QueryTriggerInteraction.Ignore))
return true;
hit = default;
return false;
}
public int OverlapGroundHits()
{
// NonAlloc: writes into preallocated buffer, returns count
return Physics.RaycastNonAlloc(
transform.position,
Vector3.down,
_hits,
distance,
groundMask,
QueryTriggerInteraction.Ignore);
}
}
```
> [!warning] Code not compiled in Unity
> Not compiled in Editor for this write-up.
`RaycastNonAlloc` returns the **number of hits written**. Only read `_hits[0..count)`.
Default `layerMask` in many overloads is not "everything" in the way beginners expect — pass explicit masks in gameplay code.
## 3.3 SphereCast, CapsuleCast, Overlap
| API | Use |
|---|---|
| `Physics.SphereCast` / `SphereCastNonAlloc` | Thick ray — footsteps, mantle checks, bullet with radius |
| `Physics.CapsuleCast` | Character-shaped sweeps |
| `Physics.OverlapSphere` / `OverlapSphereNonAlloc` | Explosion radius, aggro ([[Organic Enemy Sensing]]) |
| `Physics.OverlapBox` / NonAlloc | Door volumes, AABB queries |
| `Physics.CheckSphere` / `CheckBox` | Boolean occupancy |
```csharp
using UnityEngine;
public class ExplosionQuery : MonoBehaviour
{
[SerializeField] float radius = 5f;
[SerializeField] LayerMask affected;
static readonly Collider[] Buffer = new Collider[32];
public int CollectTargets(Vector3 origin)
{
return Physics.OverlapSphereNonAlloc(origin, radius, Buffer, affected,
QueryTriggerInteraction.Collide);
}
public void ApplyImpulse(Vector3 origin, float force)
{
int count = CollectTargets(origin);
for (int i = 0; i < count; i++)
{
if (Buffer[i].attachedRigidbody == null) continue;
Buffer[i].attachedRigidbody.AddExplosionForce(force, origin, radius, 0.5f, ForceMode.Impulse);
}
}
}
```
> [!warning] Code not compiled in Unity
> Not compiled in Editor for this write-up.
## 3.4 QueryTriggerInteraction
| Value | Meaning |
|---|---|
| `UseGlobal` | Honor **Physics.queriesHitTriggers** project setting |
| `Ignore` | Skip triggers |
| `Collide` | Include triggers |
Ground probes: **Ignore**. Hurtbox sweeps that use trigger colliders: **Collide**.
## 3.5 Multiplayer note
Queries are local simulation truth. With [[Multiplayer with Netcode for GameObjects]], decide **who** runs the query (server/host authority vs client prediction) before you trust a hit for damage.
## Next
[[4. Joints]] — connecting Rigidbodies with constraints.