# Unity Physicscore2d Filtering

> Unity Physicscore2d Filtering is an Agent Skill for development published in the Unity-Technologies/PhysicsExamples2D repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Collision filtering, layer-based interactions, custom collision filters, and trigger areas

- Skill name: `unity-physicscore2d-filtering`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/Unity-Technologies/PhysicsExamples2D/blob/HEAD/.claude/skills/unity-physicscore2d-filtering/SKILL.md
- Repository: Unity-Technologies/PhysicsExamples2D (730 GitHub stars when collected)

## SKILL.md

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

---

Source: https://www.openparable.com/skill/development/unity-physicscore2d-filtering (OpenParable). Cite the canonical URL above.
