Matter.js MouseConstraint Configuration Options

In Matter.js, a MouseConstraint enables user interaction by allowing bodies in the physics simulation to be clicked, dragged, and thrown using a mouse or touch inputs. This article details the full range of configuration options that can be passed to the MouseConstraint.create() method, including pointer bindings, collision filters for selective grabbing, and spring constraint physics parameters.

Basic Usage

To configure a MouseConstraint, you pass an engine instance along with an optional options object to Matter.MouseConstraint.create(engine, options).

const mouse = Matter.Mouse.create(render.canvas);

const mouseConstraint = Matter.MouseConstraint.create(engine, {
  mouse: mouse,
  constraint: {
    stiffness: 0.2,
    render: {
      visible: true
    }
  },
  collisionFilter: {
    mask: 0x0001
  }
});

Core Configuration Options

1. mouse

• Type: Matter.Mouse
• Default: Automatically created if omitted
• Description: The Mouse instance used to track input coordinates and click/touch events. Typically, you initialize this explicitly using Matter.Mouse.create(render.canvas) to ensure mouse coordinates properly map to the canvas render bounds and account for pixel ratio scaling.

2. constraint

• Type: Object
• Default: Internal default constraint
• Description: Defines the spring constraint connecting the mouse pointer to the grabbed body. It accepts any standard Matter.Constraint properties:
  • stiffness (Number, default 0.1): Controls how rigidly the object follows the pointer. Lower values create a looser, elastic pull; higher values (up to 1) make the connection rigid and immediate.
  • damping (Number, default 0): The damping applied to the spring constraint, reducing oscillation when moving bodies.
  • angularStiffness (Number, default 0): Controls rotational resistance when dragging an object off-center.
  • render (Object): Visual properties for debugging constraint lines.
    • visible (Boolean, default true): Toggles rendering of the line between pointer and anchor.
    • lineWidth (Number): Width of the drawn constraint line.
    • strokeStyle (String): Color definition (e.g., '#90EE90').

3. collisionFilter

• Type: Object
• Default: { category: 0x0001, mask: 0xFFFFFFFF, group: 0 }
• Description: Determines which bodies the mouse can interact with. By default, the mouse can grab any body. By configuring collision masks, you can restrict interactions to specific object layers:
  • category (Number): The collision category bitmask for the mouse pointer.
  • mask (Number): The bitmask defining which categories of bodies the mouse can interact with.
  • group (Number): An integer specifying collision group rules.

4. type

• Type: String
• Default: 'mouseConstraint'
• Description: An internal identifier string used by Matter.js to differentiate composite types. This is rarely modified manually.

Read-Only State Properties

Once configured, the MouseConstraint exposes dynamic state properties that can be monitored inside your game or simulation loop:

• body: References the current Matter.Body being dragged (evaluates to null when no body is held).
• point: A Vector representing the local coordinate anchor point on the dragged body where the mouse is attached.