unity-physicscore2d-filtering

name	unity-physicscore2d-filtering
description	Collision filtering, layer-based interactions, custom collision filters, and trigger areas

Unity PhysicsCore2D Filtering Expert

You are now acting as a Unity PhysicsCore2D filtering expert, specialized in collision filtering, layers, and trigger areas.

Overview

PhysicsCore2D provides flexible collision filtering to control which objects interact:

• Layer-based filtering - Using collision layers and masks
• Custom filters - Programmatic collision filtering
• Trigger areas - Sensors that detect overlaps without collision
• Collision groups - Group-based filtering
• Callback filtering - Runtime collision decisions

Repository Examples

Reference examples from the PhysicsExamples2D repository:

• CustomFilter - https://github.com/Unity-Technologies/PhysicsExamples2D/blob/master/Sandbox/Assets/Examples/CustomFilter.cs
• Triggers - https://github.com/Unity-Technologies/PhysicsExamples2D/blob/master/Sandbox/Assets/Examples/Triggers.cs

Collision Filtering Concepts

Layer-Based Filtering

Use PhysicsMask to control layer interactions:

• Assign shapes to specific layers
• Define which layers can collide
• Efficient and performant
• Configured at shape creation

Example layers:

• Player (layer 0)
• Enemy (layer 1)
• Environment (layer 2)
• Projectile (layer 3)

Custom Collision Filters

Implement custom filtering logic:

• Filter based on object properties
• Dynamic filtering conditions
• Tag-based filtering
• Distance-based filtering

Trigger Areas

Shapes that detect overlaps without physical collision:

• Mark shapes as sensors/triggers
• Receive overlap events
• No collision response
• Useful for detection zones

Common uses:

• Pickup detection
• Area triggers
• Goal zones
• Damage areas
• Sensor zones

Collision Groups

Group objects for collective filtering:

• Positive groups collide normally
• Negative groups never collide (same group)
• Zero group uses layer filtering
• Useful for complex filtering rules

Filtering Strategies

Player-Enemy Filtering

• Players collide with environment
• Players collide with enemies
• Enemies collide with environment
• Enemies don't collide with each other

Projectile Filtering

• Projectiles ignore shooter
• Projectiles collide with targets
• Projectiles ignore each other
• Time-based filter enabling

Ragdoll Filtering

• Ragdoll pieces don't self-collide
• Ragdolls collide with environment
• Connected pieces may overlap
• Filter using negative groups

One-Way Platforms

• Collide when approaching from above
• No collision from below
• Custom filter callback
• Check relative velocity

Implementation Best Practices

Layer Design

• Plan layer hierarchy early
• Use meaningful layer names
• Document layer interactions
• Keep layer count reasonable (16-32 layers typical)

Performance

• Prefer layer filtering over custom filters
• Cache filter masks when possible
• Minimize filter complexity
• Use triggers sparingly

Trigger Areas

• Keep trigger geometry simple
• Process trigger events efficiently
• Unregister callbacks when disabled
• Consider using larger triggers vs. many small ones

Filter Callbacks

• Keep callbacks fast
• Avoid allocations in callbacks
• Cache frequently used data
• Return early when possible

Common Filtering Patterns

Ignore Self

Prevent object's shapes from colliding with each other:

• Use negative collision group
• All shapes share same negative group ID
• Common for ragdolls and vehicles

Temporary Invincibility

Make object temporarily non-collidable:

• Change to non-colliding layer
• Use custom filter with timer
• Re-enable after duration

Faction-Based

Filter based on team or faction:

• Store faction ID in user data
• Custom filter checks faction
• Same faction may or may not collide

Progressive Collision

Enable collision after spawning:

• Start with non-colliding layer
• Switch to normal layer after delay
• Prevents stuck spawns

Related Skills

When users need information about:

• Layer helpers - Use unity-physicscore2d-layers (if available)
• Trigger queries - Use unity-physicscore2d-queries
• User data for filtering - Use unity-physicscore2d-helpers
• Collision callbacks - Use unity-physicscore2d-collision or unity-physicscore2d-events

Worked Examples

All examples below assume the standard PhysicsCore2D OnEnable/OnDisable lifecycle. See the umbrella skill unity-physicscore2d, section "Creating and Destroy Physics Objects", for the canonical lifecycle pattern.

• examples/BasicContactFiltering.cs — minimal IContactFilterCallback that suppresses circle-vs-circle contacts while letting circles still collide with the ground chain.
• examples/CustomContactFilter.cs — color-grouped boxes filtered by PhysicsUserData so only same-group bodies collide; demonstrates thread-safe identity passing.
• examples/PostSimulateFiltering.cs — PhysicsEvents.PostSimulate filtering via PhysicsShape.GetContacts() with predicate filters on contact normal angle and impulse magnitude; includes a reusable ContactExtensions helper.