# 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. See also (added 2026-11-10): [[Combat Feel and Hit Feedback]] / [[3. Hitboxes and Hurtboxes]] - dedicated hit/hurt layers and OverlapBoxNonAlloc during the active window.