How to Configure Planck.js Bullet Body for Precision?

This article provides a quick guide on configuring high-speed bodies in planck.js to prevent “tunneling”—a common physics engine glitch where fast-moving objects pass straight through static barriers. By leveraging continuous collision detection (CCD) through the bullet property, you can ensure precise, frame-by-frame collision handling for projectiles and rapid actors in your JavaScript games.

Understanding the Tunneling Problem

In discrete physics simulations, object positions are updated at fixed time steps. If an object is moving fast enough, its velocity vector might jump entirely across a thin wall from one frame to the next. Because the shapes never actually overlap during a specific time step, the engine misses the collision entirely.

To solve this, planck.js (a 2D physics engine based on Box2D) features Continuous Collision Detection. When CCD is enabled for a body, the engine calculates the “Time of Impact” (TOI) to catch collisions that happen between frames.

Setting the Bullet Property

To flag a moving body for precise collision detection, you must explicitly set its bullet status to true. This instructs the solver to use CCD against all other dynamic and static bodies.

You can enable this setting during body creation or toggle it dynamically at runtime.

Method 1: Configuration During Creation

When defining your body definition object, simply include the bullet key:

// Create a fast-moving projectile body
const bulletBody = world.createBody({
  type: 'dynamic',
  position: pl.Vec2(0, 0),
  bullet: true // Enables CCD for this body
});

// Attach a fixture (shape and density) to the body
bulletBody.createFixture(pl.Circle(0.1), {
  density: 1.0,
  friction: 0.3
});

Method 2: Dynamic Configuration

If an object only needs precision tracking at specific moments—such as after a speed boost—you can toggle the state using the built-in setter method:

// Check if the body is currently set as a bullet
if (!myBody.isBullet()) {
  // Turn on precise collision detection
  myBody.setBullet(true);
}

Best Practices for Precise Physics

While marking every moving entity as a bullet might seem like an easy way to ensure perfect physics, it comes with performance trade-offs. Use these guidelines to keep your simulation running smoothly: