How to Use Matter.Composites.car in Matter.js

This article explains how to quickly create and simulate a functioning 2D vehicle using the built-in Matter.Composites.car method in Matter.js. You will learn the parameters required to construct the vehicle, how to place it within a physics world alongside ground terrain, and how to apply controls to make the car move.

Understanding Matter.Composites.car

Matter.js includes several composite factories to simplify the creation of complex assemblies. The Matter.Composites.car factory creates a composite body consisting of:

• A rectangular chassis.
• Two circular wheels.
• Four spring constraints that attach the wheels to the chassis and act as basic suspension.

The method signature is:

Matter.Composites.car(xx, yy, width, height, wheelSize)

• xx: The X-coordinate position where the vehicle is spawned.
• yy: The Y-coordinate position where the vehicle is spawned.
• width: The total width of the chassis.
• height: The height of the chassis.
• wheelSize: The radius of the front and rear wheels.

Basic Setup and Creation

To render a car, initialize the standard Matter.js modules (Engine, Render, Runner, Composite, and Bodies), create the car instance, and add it to the physics world.

const { Engine, Render, Runner, Composite, Composites, Bodies } = Matter;

// Create engine and world
const engine = Engine.create();
const world = engine.world;

// Create renderer
const render = Render.create({
    element: document.body,
    engine: engine,
    options: {
        width: 800,
        height: 600,
        wireframes: false
    }
});

Render.run(render);

// Create runner
const runner = Runner.create();
Runner.run(runner, engine);

// Create the car composite
const car = Composites.car(150, 100, 120, 30, 25);

// Create static ground and ramp for the car to drive on
const ground = Bodies.rectangle(400, 580, 810, 40, { isStatic: true });
const ramp = Bodies.rectangle(600, 500, 200, 20, { 
    isStatic: true, 
    angle: -Math.PI / 6 
});

// Add all objects to the world
Composite.add(world, [car, ground, ramp]);

Driving the Car

By default, the car behaves purely as a passive physics object that rolls under the influence of gravity. To make it driveable, you must apply torque or set the angular velocity on the wheels.

The composite contains three bodies in its bodies array:

1. car.bodies[0]: The chassis
2. car.bodies[1]: The rear wheel
3. car.bodies[2]: The front wheel

You can listen for keyboard events and change the angular velocity of the wheel bodies to move forward or backward:

const { Body } = Matter;

const wheelA = car.bodies[1];
const wheelB = car.bodies[2];
const driveSpeed = 0.15;

window.addEventListener('keydown', (event) => {
    if (event.key === 'ArrowRight') {
        Body.setAngularVelocity(wheelA, driveSpeed);
        Body.setAngularVelocity(wheelB, driveSpeed);
    } else if (event.key === 'ArrowLeft') {
        Body.setAngularVelocity(wheelA, -driveSpeed);
        Body.setAngularVelocity(wheelB, -driveSpeed);
    }
});

Customizing Physical Properties

You can modify friction and restitution on the wheels to alter handling. Higher friction on the wheel bodies provides better traction when climbing inclines:

wheelA.friction = 0.9;
wheelB.friction = 0.9;

Similarly, adjusting the stiffness of the constraints inside car.constraints allows you to customize the softness or rigidity of the suspension.