What is a sensor fixture in planck.js?

This article provides a comprehensive overview of sensor fixtures in planck.js, a 2D physics engine for JavaScript. It explains what a sensor fixture is, how it differs from standard solid fixtures, and the precise mechanism it uses to detect overlaps between game objects without causing physical collisions.

Understanding Sensor Fixtures in planck.js

In planck.js (which is based on the Box2D physics engine), a fixture binds a shape to a rigid body and defines its physical properties like density, friction, and restitution. By default, when two fixtures collide, the physics engine responds by bouncing them off each other or preventing them from passing through one another.

A sensor fixture, however, is a fixture that has its isSensor flag set to true. When a fixture is designated as a sensor, it acts as a “ghost” zone. It completely disables the physical collision response, meaning other objects can pass right through it. Instead of forcing a physical bounce, its sole purpose is to listen for and report when another object intersects its boundary.

How Sensor Fixtures Detect Overlaps

Sensor fixtures rely on the engine’s broad-phase and narrow-phase collision detection to identify overlaps. Because they don’t generate contact forces, the process is highly efficient and follows a specific lifecycle managed by the world’s contact listener.

The Contact Listener Mechanism

To detect when an object enters or leaves a sensor’s zone, you must implement a ContactListener on your planck.js world. The engine triggers specific callbacks during its step simulation:

• BeginContact: This event fires the exact frame another fixture starts overlapping with the sensor fixture. This is typically where you trigger game logic, such as collecting an item, opening a door, or applying a regional effect like gravity or damage.
• EndContact: This event fires the frame the external fixture completely exits the sensor’s boundary. It is useful for turning off effects or tracking when a player leaves an area.

Distinguishing Sensors in Code

Inside the contact listener callbacks, you can verify if the collision involves a sensor by calling the isSensor() method on the fixtures involved.

world.on('begin-contact', function(contact) {
    let fixtureA = contact.getFixtureA();
    let fixtureB = contact.getFixtureB();

    if (fixtureA.isSensor() || fixtureB.isSensor()) {
        // Handle the overlap logic here
        console.log('An overlap has been detected!');
    }
});

Common Use Cases for Sensors

Because sensors detect spatial overlaps without affecting movement trajectories, they are ideal for several game development scenarios:

• Trigger Zones: Scripting cutscenes, spawning enemies, or saving checkpoints when a player enters a specific region.
• Collectible Items: Overlapping with coins, health packs, or power-ups so the player “absorbs” them rather than bumping into them.
• Proximity and Vision Cones: Attaching a cone-shaped sensor to an enemy body to simulate a field of view or an aggro radius.