1.0.0
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.
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.
(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.
Make a ball with the given parameters.
(number)
The initial x-coordinate measured from the center.
(number)
The initial y-coordinate measured from the center.
(number)
The diameter of the ball.
Ball
:
Make a block with the given parameters.
(number)
The initial x-coordinate measured from the center.
(number)
The initial y-coordinate measured from the center.
(number)
The width of the block.
(number)
The height of the block.
Block
:
Make a barrier with the given parameters. Barriers are essentially frozen / immovable blocks. Good for making floor, walls, bumpers, etc.
(number)
The initial x-coordinate measured from the center.
(number)
The initial y-coordinate measured from the center.
(number)
The width of the barrier.
(number)
The height of the barrier.
Barrier
:
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
.
(string)
The text to display.
(number)
The initial x-coordinate measured from the center.
(number)
The initial y-coordinate measured from the center.
Sign
:
Connects two objects so that they move together. By giving some options, it can be used to make springs and other elastic objects.
(PhysicalObject)
One of the physical objects to
connect.
(PhysicalObject)
The other physical object to
connect.
(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.
Change the gravity to be the default. Alias for
matter.changeGravity(0, 1)
.
Change the gravity to be upside-down. Alias for
matter.changeGravity(0, -1)
.
Change the gravity to be zero, i.e. disable gravity. Alias for
matter.changeGravity(0, 0)
.
Change the strength and direction of gravity.
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.
((PhysicalObject | Connection))
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
.
Enable mouse interaction for the given canvas. This lets you apply forces to physical objects by clicking and dragging on them.
(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
.
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.
Freeze the object in place, causing it to stop moving.
Unfreeze the object, causing it to start moving again.
Determine if the object is being tracked and updated or if it was
forgotten (see matter.forget
).
boolean
:
Draw the object to the screen. Respects the current style settings. Using this is optional, feel free to draw the objects however you would like.
getPositionX
.
getPositionY
.
Represents a circle that obeys physics.
The constructor for Ball is private. Use
matter.makeBall
instead.
Extends PhysicalObject
(number)
The initial x-coordinate measured from the center.
(number)
The initial y-coordinate measured from the center.
(number)
The diameter of the ball.
Represents a rectangle that obeys physics.
The constructor for Block is private. Use matter.makeBlock instead.
Extends PhysicalObject
Represents physics-aware text.
The constructor for Sign is private. Use matter.makeSign instead.
Extends Block
(string)
(number)
The initial x-coordinate measured from the center.
(number)
The initial y-coordinate measured from the center.
Represents a connection between two physical objects.
The constructor for Connection is private. Use matter.connect instead.
(Matter.Constraint)
(PhysicalObject)
One of the physical objects to
connect.
(PhysicalObject)
The other physical object to
connect.
Determine if the connection is being tracked and updated or if it was
forgotten (see matter.forget
).
boolean
:
Draw a line between the connected objects.