matter

The global object for interacting with matter.js. Has a handful of methods for creating physics-aware objects and manipulating the environment. Before you go any further, here are a couple of general notes about the library.

Throughout the docs, I will refer to Matter.Body properties. These properties are used to configure some more advanced settings for your object. You should pass all the properties you want to configure as a JavaScript object. The most interesting ones are angle, friction, frictionAir, and restitution. You can find the full list of properties at http://brm.io/matter-js/docs/classes/Body.html#property_angle. (When you create the options Object, do not prefix the properties with body., e.g. if I want to set the initial angle to 30 degrees, my options would look like { angle: radians(30) }.)

All the positioning is done from the center of the object. Note that this differs slightly from p5.js's default system, which interprets the first two arguments to rect and text as being the top-left corner of the object. The system used by this library is more or less equivalent to setting rectMode(CENTER) and textAlign(CENTER). Although not technically necessary, it might be helpful to set those modes anyway as a reminder.

For those of you coming from matter.js, here are some of the analogues between the two libraries. matter.init calls Matter.Engine.create and, depending on the passed argument, Matter.Engine.run. matter.makeBall and matter.makeBlock correspond to Matter.Body.circle and Matter.Body.rectangle, respectively. There is no direct equivalent to matter.makeSign as far as I am aware. matter.connnect creates a new Matter.Constraint and adds it to the world. The gravity functions, e.g. matter.changeGravity, are equivalent to manipulating Matter.World#gravity. matter.forget removes a Matter.Body or Matter.Constraint from the world, and also removes all constraints / bodies connected to it. matter.manualTick calls Matter.Engine.update. matter.mouseInteraction creates a new Matter.Mouse with the appropriate canvas and pixelRatio, creates a new Matter.MouseConstraint with the newly created mouse, and adds it to the world.

matter
Author: Palmer Paul

matter.init

Set everything up. It is recommended that you call this in the setup function of your p5.js sketch. It is not a big deal if you forget to do this though, as we will call it for you when you use any other method.

matter.init(manual: boolean)
Parameters
manual (boolean = false) Stop matter.js from automatically updating. If you choose to do this, use matter.manualTick in your draw function. In general, this is a bad idea, but it is here in case you need more control.

matter.makeBall

Make a ball with the given parameters.

matter.makeBall(x: number, y: number, diameter: number, options: Object?): Ball
Parameters
x (number) The initial x-coordinate measured from the center.
y (number) The initial y-coordinate measured from the center.
diameter (number) The diameter of the ball.
options (Object?) An object with any Matter.Body properties. See the second paragraph of matter .
Returns
Ball:

matter.makeBlock

Make a block with the given parameters.

matter.makeBlock(x: number, y: number, width: number, height: number, options: Object?): Block
Parameters
x (number) The initial x-coordinate measured from the center.
y (number) The initial y-coordinate measured from the center.
width (number) The width of the block.
height (number) The height of the block.
options (Object?) An object with any Matter.Body properties. See the second paragraph of matter .
Returns
Block:

matter.makeBarrier

Make a barrier with the given parameters. Barriers are essentially frozen / immovable blocks. Good for making floor, walls, bumpers, etc.

matter.makeBarrier(x: number, y: number, width: number, height: number, options: Object?): Barrier
Parameters
x (number) The initial x-coordinate measured from the center.
y (number) The initial y-coordinate measured from the center.
width (number) The width of the barrier.
height (number) The height of the barrier.
options (Object?) An object with any Matter.Body properties. See the second paragraph of matter .
Returns
Barrier:

matter.makeSign

Make physics-aware text. The trick is putting a bounding rectangle Block around the text. The width and the height of the rectangle are determed dynamically at creation time by inspecting the textSize.

matter.makeSign(text: string, x: number, y: number, options: Object?): Sign
Parameters
text (string) The text to display.
x (number) The initial x-coordinate measured from the center.
y (number) The initial y-coordinate measured from the center.
options (Object?) An object with any Matter.Body properties. See the second paragraph of matter .
Returns
Sign:

matter.connect

Connects two objects so that they move together. By giving some options, it can be used to make springs and other elastic objects.

matter.connect(physicalObjectA: PhysicalObject, physicalObjectB: PhysicalObject, options: Object?)
Parameters
physicalObjectA (PhysicalObject) One of the physical objects to connect.
physicalObjectB (PhysicalObject) The other physical object to connect.
options (Object?) An object with any Matter.Constraint properties ( http://brm.io/matter-js/docs/classes/Constraint.html#property_bodyA ). The most interesting properties are length and stiffness , which respectively control the "rest length" and elasticity of the spring.

matter.normalGravity

Change the gravity to be the default. Alias for matter.changeGravity(0, 1).

matter.normalGravity()

matter.invertedGravity

Change the gravity to be upside-down. Alias for matter.changeGravity(0, -1).

matter.invertedGravity()

matter.zeroGravity

Change the gravity to be zero, i.e. disable gravity. Alias for matter.changeGravity(0, 0).

matter.zeroGravity()

matter.changeGravity

Change the strength and direction of gravity.

matter.changeGravity(x: number, y: number)
Parameters
x (number) The gravitational acceleration along the x-axis. A sensible value is somewhere in the range of [ -1.. 1 ] .
y (number) The gravitational acceleration along the y-axis. A sensible value is somewhere in the range of [ -1.. 1 ] .

matter.forget

Stop tracking a particular object or connection. Even if an object goes out of view, calculations will continue to be performed for that object unless you call this method. It is important to use this method when you are done with an object in order for things to run smoothly.

matter.forget(physicalObjectOrConnection: (PhysicalObject | Connection))
Parameters
physicalObjectOrConnection ((PhysicalObject | Connection))

matter.manualTick

Manually trigger an update of the physics engine. You only should be using this if you initially passed a value of true to matter.init.

matter.manualTick()

matter.mouseInteraction

Enable mouse interaction for the given canvas. This lets you apply forces to physical objects by clicking and dragging on them.

matter.mouseInteraction(canvas: Object?)
Parameters
canvas (Object?) The canvas for which to enable mouse interaction. You can get the canvas object for your sketch by storing the return value of createCanvas . If not supplied, defaults to window.canvas .

PhysicalObject

Represents any object that obeys physics. Serves as the parent class for Ball, Block, and Barrier. It basically wraps a matter.js body and provides some getters and convenience methods.

PhysicalObject is an abstract class, meaning that it is impossible to create instances of it. You do not need to worry about this though.

new PhysicalObject(body: Matter.Body, width: number, height: number)
Author: Palmer Paul
Parameters
body (Matter.Body)
width (number)
height (number)
Instance Members
getPositionX()
getPositionY()
setPosition(xPos, yPos)
setPositionX(xPos)
setPositionY(yPos)
getVelocityX()
getVelocityY()
setVelocity(xVel, yVel)
setVelocityX(xVel)
setVelocityY(yVel)
getWidth()
getHeight()
getAngle()
setAngle(angle)
isFrozen()
freeze()
unfreeze()
isOffCanvas(bufferZone)
isActive()
show()
getX()
getY()

Ball

Represents a circle that obeys physics.

The constructor for Ball is private. Use matter.makeBall instead.

new Ball(x: number, y: number, diameter: number, options: Object?)

Extends PhysicalObject

Author: Palmer Paul
Parameters
x (number) The initial x-coordinate measured from the center.
y (number) The initial y-coordinate measured from the center.
diameter (number) The diameter of the ball.
options (Object?) An object with any Matter.Body properties. See the second paragraph of matter .
Instance Members
getDiameter()
getRadius()

Block

Represents a rectangle that obeys physics.

The constructor for Block is private. Use matter.makeBlock instead.

new Block(x: number, y: number, width: number, height: number, options: Object?)

Extends PhysicalObject

Author: Palmer Paul
Parameters
x (number) The initial x-coordinate measured from the center.
y (number) The initial y-coordinate measured from the center.
width (number) The width of the block.
height (number) The height of the block.
options (Object?) An object with any Matter.Body properties. See the second paragraph of matter .

Sign

Represents physics-aware text.

The constructor for Sign is private. Use matter.makeSign instead.

new Sign(text: string, x: number, y: number, options: Object?)

Extends Block

Author: Palmer Paul
Parameters
text (string)
x (number) The initial x-coordinate measured from the center.
y (number) The initial y-coordinate measured from the center.
options (Object?) An object with any Matter.Body properties. See the second paragraph of matter .
Instance Members
getText()

Connection

Represents a connection between two physical objects.

The constructor for Connection is private. Use matter.connect instead.

new Connection(constraint: Matter.Constraint, physicalObjectA: PhysicalObject, physicalObjectB: PhysicalObject)
Author: Palmer Paul
Parameters
constraint (Matter.Constraint)
physicalObjectA (PhysicalObject) One of the physical objects to connect.
physicalObjectB (PhysicalObject) The other physical object to connect.
Instance Members
isActive()
show()