How the isSensor Property Works in Matter.js

In Matter.js, configuring a body as a sensor fundamentally alters how it interacts with other physics objects in a simulation. This article explains the technical behavior of setting the isSensor property to true, how it eliminates physical collisions while retaining detection events, and how to implement it effectively for triggers, boundaries, and detection zones in your 2D physics projects.

What isSensor Does

By default, every rigid body in Matter.js has solid physical boundaries. When two non-sensor bodies collide, the physics engine computes restitution, friction, and collision resolution forces to prevent them from overlapping and to bounce or push them apart.

Setting isSensor: true disables this physical response entirely:

• No Physical Displacement: The body becomes non-solid and intangible. Other bodies will pass through it seamlessly without being blocked, slowed down, or pushed away.
• Collision Events Still Fire: Even though there is no physical reaction, the engine's collision detection pipeline remains fully active. Matter.js continues to compute intersection pairs and triggers collisionStart, collisionActive, and collisionEnd events for the sensor body.

How to Set a Body as a Sensor

You can define a body as a sensor upon creation or toggle it dynamically during runtime.

Defining at Creation

Pass isSensor: true within the options object when creating a body:

const triggerZone = Matter.Bodies.rectangle(400, 300, 200, 100, {
  isSensor: true,
  isStatic: true // Frequently made static to serve as a fixed zone
});

Matter.Composite.add(engine.world, triggerZone);

Changing at Runtime

You can update the property directly on an existing body instance:

myBody.isSensor = true;

Handling Sensor Events

Because sensor bodies do not produce impulses, their primary utility comes from listening to collision events via the Matter.Events module.

Matter.Events.on(engine, 'collisionStart', (event) => {
  const pairs = event.pairs;

  for (let i = 0; i < pairs.length; i++) {
    const { bodyA, bodyB } = pairs[i];

    if (bodyA === triggerZone || bodyB === triggerZone) {
      // Logic for when another object enters the sensor area
      console.log('Object entered the trigger zone');
    }
  }
});

Common Use Cases

• Checkpoints and Goal Areas: Detecting when a player or projectile crosses a finish line or hits a target without altering the object's trajectory.
• Collectibles: Creating coins, power-ups, or items that detect when a character touches them so they can be removed and awarded.
• Proximity Triggers: Setting up invisible boundaries around enemies or mechanisms to detect when an entity enters a specific field of view or detection radius.
• Environmental Zones: Creating regions like water or low-gravity fields where you want to detect presence and apply custom forces programmatically rather than using standard collision mechanics.