OpenParable
Skip to content
← Back to skills

Unity Physicscore2d Filtering

Development
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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Unity-Technologies/PhysicsExamples2D/blob/HEAD/.claude/skills/unity-physicscore2d-filtering/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/unity-physicscore2d-filtering, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

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.