wave5-collision-filter-layer-masking

Collision Filter Layer Masking

Intent

Control which physics bodies interact with each other and with spatial queries using CollisionFilter bitmask layer assignment, reducing broadphase pairs and query false positives.

Use When

• Physics simulation should exclude certain body pairs (enemies don't collide with each other, bullets pass through allies)
• Spatial queries should hit only specific layers
• Performance optimization in dense scenes by reducing broadphase pairs

Avoid When

• Only 2-3 bodies need selective collision — trigger-only colliders or kinematic bodies may be simpler
• More than 32 distinct layer categories needed — CollisionFilter has exactly 32 bits

Senior Pattern

// Define layer constants in one shared location:
public static class PhysicsLayer
{
    public const uint Ground     = 1u << 0;
    public const uint Player     = 1u << 1;
    public const uint Enemy      = 1u << 2;
    public const uint Projectile = 1u << 3;
    public const uint Trigger    = 1u << 4;
}

// Interaction rule: A and B interact iff:
//   (A.BelongsTo & B.CollidesWith) != 0  AND  (B.BelongsTo & A.CollidesWith) != 0

// Query-time filter — projectile only hits ground and enemies:
var input = new RaycastInput
{
    Start = origin,
    End   = origin + direction * 100f,
    Filter = new CollisionFilter
    {
        BelongsTo    = PhysicsLayer.Projectile,
        CollidesWith = PhysicsLayer.Ground | PhysicsLayer.Enemy,
        GroupIndex   = 0
    }
};
physicsWorld.CollisionWorld.CastRay(input, out RaycastHit hit);

// Authoring-time — set on PhysicsCollider via Baker:
public override void Bake(ProjectileAuthoring authoring)
{
    var entity = GetEntity(TransformUsageFlags.Dynamic);
    AddComponent(entity, new PhysicsCollider
    {
        Value = Unity.Physics.BoxCollider.Create(
            geometry,
            new CollisionFilter
            {
                BelongsTo    = PhysicsLayer.Projectile,
                CollidesWith = PhysicsLayer.Ground | PhysicsLayer.Enemy,
                GroupIndex   = 0
            })
    });
}