Static Protected _baseStatic Protected _inertiaStatic Protected _nextStatic Protected _nextStatic Protected _nextStatic Protected _timeStatic Protected _initInitialises body properties.
Optional _original?: null | ({ restitution?: number | undefined; friction?: number | undefined; mass?: number | undefined; inertia?: number | undefined; density?: number | undefined; inverseMass?: number | undefined; inverseInertia?: number | undefined; })Optional angle?: numberA Number specifying the angle of the body, in radians.
0
Optional angleOptional angularA Number that measures the current angular speed of the body after the last Body.update. It is read-only and always positive (it's the magnitude of body.angularVelocity).
0
Optional angularA Number that measures the current angular velocity of the body after the last Body.update. It is read-only.
If you need to modify a body's angular velocity directly, you should apply a torque or simply change the body's angle (as the engine uses position-Verlet integration).
0
Optional area?: numberA Number that measures the area of the body's convex hull, calculated at creation by Body.create.
Optional axes?: IAxesAn array of unique axis vectors (edge normals) used for collision detection.
These are automatically calculated from the given convex hull (vertices array) in Body.create.
They are constantly updated by Body.update during the simulation.
Optional bounds?: { min?: { x?: number | undefined; y?: number | undefined; } | undefined; max?: { x?: number | undefined; y?: number | undefined; } | undefined; }A Bounds object that defines the AABB region for the body.
It is automatically calculated from the given convex hull (vertices array) in Body.create and constantly updated by Body.update during simulation.
Optional chamfer?: { radius?: number | number[] | undefined; quality?: number | undefined; qualityMin?: number | undefined; qualityMax?: number | undefined; }Optional circleOptional collisionAn Object that specifies the collision filtering properties of this body.
Collisions between two bodies will obey the following rules:
collisionFilter.group,
they will always collide if the value is positive, and they will never collide
if the value is negative.collisionFilter.group or if one
(or both) of the bodies has a value of 0, then the category/mask rules apply as follows:Each body belongs to a collision category, given by collisionFilter.category. This
value is used as a bit field and the category should have only one bit set, meaning that
the value of this property is a power of two in the range [1, 2^31]. Thus, there are 32
different collision categories available.
Each body also defines a collision bitmask, given by collisionFilter.mask which specifies
the categories it collides with (the value is the bitwise AND value of all these categories).
Using the category/mask rules, two bodies A and B collide if each includes the other's
category in its mask, i.e. (categoryA & maskB) !== 0 and (categoryB & maskA) !== 0
are both true.
Optional constraintOptional deltaOptional density?: numberA Number that defines the density of the body, that is its mass per unit area.
If you pass the density via Body.create the mass property is automatically calculated for you based on the size (area) of the object.
This is generally preferable to simply setting mass and allows for more intuitive definition of materials (e.g. rock has a higher density than wood).
0.001
Optional events?: { sleepStart?: BodyEventFunction[] | undefined; sleepEnd?: BodyEventFunction[] | undefined; }Optional force?: { x?: number | undefined; y?: number | undefined; }A Vector that specifies the force to apply in the current step. It is zeroed after every Body.update. See also Body.applyForce.
{ x: 0, y: 0 }
Optional friction?: numberA Number that defines the friction of the body. The value is always positive and is in the range (0, 1).
A value of 0 means that the body may slide indefinitely.
A value of 1 means the body may come to a stop almost instantly after a force is applied.
The effects of the value may be non-linear.
High values may be unstable depending on the body.
The engine uses a Coulomb friction model including static and kinetic friction.
Note that collision response is based on pairs of bodies, and that friction values are combined with the following formula:
Math.min(bodyA.friction, bodyB.friction)
0.1
Optional frictionA Number that defines the air friction of the body (air resistance).
A value of 0 means the body will never slow as it moves through space.
The higher the value, the faster a body slows when moving through space.
The effects of the value are non-linear.
0.01
Optional frictionA Number that defines the static friction of the body (in the Coulomb friction model).
A value of 0 means the body will never 'stick' when it is nearly stationary and only dynamic friction is used.
The higher the value (e.g. 10), the more force it will take to initially get the body moving when nearly stationary.
This value is multiplied with the friction property to make it easier to change friction and maintain an appropriate amount of static friction.
0.5
Optional id?: numberAn integer Number uniquely identifying number generated in Body.create by Common.nextId.
Optional inertia?: numberA Number that defines the moment of inertia (i.e. second moment of area) of the body.
It is automatically calculated from the given convex hull (vertices array) and density in Body.create.
If you modify this value, you must also modify the body.inverseInertia property (1 / inertia).
Optional inverseA Number that defines the inverse moment of inertia of the body (1 / inertia).
If you modify this value, you must also modify the body.inertia property.
Optional inverseA Number that defines the inverse mass of the body (1 / mass).
If you modify this value, you must also modify the body.mass property.
Optional isA flag that indicates whether a body is a sensor. Sensor triggers collision events, but doesn't react with colliding body physically.
false
Optional isA flag that indicates whether the body is considered sleeping. A sleeping body acts similar to a static body, except it is only temporary and can be awoken.
If you need to set a body as sleeping, you should use Sleeping.set as this requires more than just setting this flag.
false
Optional isA flag that indicates whether a body is considered static. A static body can never change position or angle and is completely fixed.
If you need to set a body as static after its creation, you should use Body.setStatic as this requires more than just setting this flag.
false
Optional label?: stringAn arbitrary String name to help the user identify and manage bodies.
"Body"
Optional mass?: numberA Number that defines the mass of the body, although it may be more appropriate to specify the density property instead.
If you modify this value, you must also modify the body.inverseMass property (1 / mass).
Optional motion?: numberA Number that measures the amount of movement a body currently has (a combination of speed and angularSpeed). It is read-only and always positive.
It is used and updated by the Matter.Sleeping module during simulation to decide if a body has come to rest.
0
Optional parent?: { angle?: number | undefined; anglePrev?: number | undefined; angularSpeed?: number | undefined; angularVelocity?: number | undefined; area?: number | undefined; axes?: IAxes | undefined; ... 41 more ...; _original?: { ...; } | ... 1 more ... | undefined; }A self reference if the body is not a part of another body.
Otherwise this is a reference to the body that this is a part of.
See body.parts.
Optional parts?: IBody[]An array of bodies that make up this body.
The first body in the array must always be a self reference to the current body instance.
All bodies in the parts array together form a single rigid compound body.
Parts are allowed to overlap, have gaps or holes or even form concave bodies.
Parts themselves should never be added to a World, only the parent body should be.
Use Body.setParts when setting parts to ensure correct updates of all properties.
Optional plugin?: ({}) | ({ name?: string | undefined; version?: string | undefined; for?: string | undefined; uses?: string[] | undefined; install?: { apply?: {} | undefined; call?: {} | undefined; bind?: {} | undefined; ... 6 more ...; [Symbol.hasInstance]?: {} | undefined; } | undefined; _warned?: boolean | undefined; })An object reserved for storing plugin-specific properties.
Optional position?: { x?: number | undefined; y?: number | undefined; }A Vector that specifies the current world-space position of the body.
{ x: 0, y: 0 }
Optional positionOptional positionOptional region?: { id?: string | undefined; startCol?: number | undefined; endCol?: number | undefined; startRow?: number | undefined; endRow?: number | undefined; }Optional render?: ({ text?: { content?: string | undefined; font?: string | undefined; align?: CanvasTextAlign | undefined; color?: string | undefined; size?: number | undefined; isBold?: boolean | undefined; isStroke?: boolean | undefined; paddingX?: number | undefined; paddingY?: number | undefined; } | undefined; ... 4 more ...; op...) | ({ visible?: boolean | undefined; fillStyle?: string | undefined; lineWidth?: number | undefined; strokeStyle?: string | undefined; opacity?: number | undefined; }) | ({ sprite?: { texture?: string | undefined; xScale?: number | undefined; yScale?: number | undefined; xOffset?: number | undefined; yOffset?: number | undefined; } | undefined; visible?: boolean | undefined; fillStyle?: string | undefined; lineWidth?: number | undefined; strokeStyle?: string | undefined; opacity?: nu...)An Object that defines the rendering properties to be consumed by the module Matter.Render.
Optional restitution?: numberA Number that defines the restitution (elasticity) of the body. The value is always positive and is in the range (0, 1).
A value of 0 means collisions may be perfectly inelastic and no bouncing may occur.
A value of 0.8 means the body may bounce back with approximately 80% of its kinetic energy.
Note that collision response is based on pairs of bodies, and that restitution values are combined with the following formula:
Math.max(bodyA.restitution, bodyB.restitution)
0
Optional sleepOptional sleepA Number that defines the number of updates in which this body must have near-zero velocity before it is set as sleeping by the Matter.Sleeping module (if sleeping is enabled by the engine).
60
Optional slop?: numberA Number that specifies a tolerance on how far a body is allowed to 'sink' or rotate into other bodies.
Avoid changing this value unless you understand the purpose of slop in physics engines.
The default should generally suffice, although very large bodies may require larger values for stable stacking.
0.05
Optional speed?: numberA Number that measures the current speed of the body after the last Body.update. It is read-only and always positive (it's the magnitude of body.velocity).
0
Optional timeA Number that allows per-body time scaling, e.g. a force-field where bodies inside are in slow-motion, while others are at full speed.
1
Optional torque?: numberA Number that specifies the torque (turning force) to apply in the current step. It is zeroed after every Body.update.
0
Optional totalOptional type?: "body"A String denoting the type of object.
Optional velocity?: { x?: number | undefined; y?: number | undefined; }A Vector that measures the current velocity of the body after the last Body.update. It is read-only.
If you need to modify a body's velocity directly, you should either apply a force or simply change the body's position (as the engine uses position-Verlet integration).
{ x: 0, y: 0 }
Optional vertices?: IVertex[]An array of Vector objects that specify the convex hull of the rigid body.
These should be provided about the origin (0, 0). E.g.
[{ x: 0, y: 0 }, { x: 25, y: 50 }, { x: 50, y: 0 }]
When passed via Body.create, the vertices are translated relative to body.position (i.e. world-space, and constantly updated by Body.update during simulation).
The Vector objects are also augmented with additional properties required for efficient collision detection.
Other properties such as inertia and bounds are automatically calculated from the passed vertices (unless provided via options).
Concave hulls are not currently supported. The module Matter.Vertices contains useful methods for working with vertices.
_initProperties
Static Protected _setStatic Private _totalStatic applyApplies the force to the body from the force origin position in world-space, over a single timestep, including applying any resulting angular torque.
Forces are useful for effects like gravity, wind or rocket thrust, but can be difficult in practice when precise control is needed. In these cases see Body.setVelocity and Body.setPosition as an alternative.
The force from this function is only applied once for the duration of a single timestep, in other words the duration depends directly on the current engine update delta and the rate of calls to this function.
Therefore to account for time, you should apply the force constantly over as many engine updates as equivalent to the intended duration.
If all or part of the force duration is some fraction of a timestep, first multiply the force by duration / timestep.
The force origin position in world-space must also be specified. Passing body.position will result in zero angular effect as the force origin would be at the centre of mass.
The body will take time to accelerate under a force, the resulting effect depends on duration of the force, the body mass and other forces on the body including friction combined.
applyForce
Static createCreates a new rigid body model. The options parameter is an object that specifies any properties you wish to override the defaults.
All properties have default values, and many are pre-calculated automatically based on other properties.
Vertices must be specified in clockwise order.
See the properties section below for detailed information on what you can pass via the options object.
Optional _original?: null | ({ restitution?: number | undefined; friction?: number | undefined; mass?: number | undefined; inertia?: number | undefined; density?: number | undefined; inverseMass?: number | undefined; inverseInertia?: number | undefined; })Optional angle?: numberA Number specifying the angle of the body, in radians.
0
Optional angleOptional angularA Number that measures the current angular speed of the body after the last Body.update. It is read-only and always positive (it's the magnitude of body.angularVelocity).
0
Optional angularA Number that measures the current angular velocity of the body after the last Body.update. It is read-only.
If you need to modify a body's angular velocity directly, you should apply a torque or simply change the body's angle (as the engine uses position-Verlet integration).
0
Optional area?: numberA Number that measures the area of the body's convex hull, calculated at creation by Body.create.
Optional axes?: IAxesAn array of unique axis vectors (edge normals) used for collision detection.
These are automatically calculated from the given convex hull (vertices array) in Body.create.
They are constantly updated by Body.update during the simulation.
Optional bounds?: { min?: { x?: number | undefined; y?: number | undefined; } | undefined; max?: { x?: number | undefined; y?: number | undefined; } | undefined; }A Bounds object that defines the AABB region for the body.
It is automatically calculated from the given convex hull (vertices array) in Body.create and constantly updated by Body.update during simulation.
Optional chamfer?: { radius?: number | number[] | undefined; quality?: number | undefined; qualityMin?: number | undefined; qualityMax?: number | undefined; }Optional circleOptional collisionAn Object that specifies the collision filtering properties of this body.
Collisions between two bodies will obey the following rules:
collisionFilter.group,
they will always collide if the value is positive, and they will never collide
if the value is negative.collisionFilter.group or if one
(or both) of the bodies has a value of 0, then the category/mask rules apply as follows:Each body belongs to a collision category, given by collisionFilter.category. This
value is used as a bit field and the category should have only one bit set, meaning that
the value of this property is a power of two in the range [1, 2^31]. Thus, there are 32
different collision categories available.
Each body also defines a collision bitmask, given by collisionFilter.mask which specifies
the categories it collides with (the value is the bitwise AND value of all these categories).
Using the category/mask rules, two bodies A and B collide if each includes the other's
category in its mask, i.e. (categoryA & maskB) !== 0 and (categoryB & maskA) !== 0
are both true.
Optional constraintOptional deltaOptional density?: numberA Number that defines the density of the body, that is its mass per unit area.
If you pass the density via Body.create the mass property is automatically calculated for you based on the size (area) of the object.
This is generally preferable to simply setting mass and allows for more intuitive definition of materials (e.g. rock has a higher density than wood).
0.001
Optional events?: { sleepStart?: BodyEventFunction[] | undefined; sleepEnd?: BodyEventFunction[] | undefined; }Optional force?: { x?: number | undefined; y?: number | undefined; }A Vector that specifies the force to apply in the current step. It is zeroed after every Body.update. See also Body.applyForce.
{ x: 0, y: 0 }
Optional friction?: numberA Number that defines the friction of the body. The value is always positive and is in the range (0, 1).
A value of 0 means that the body may slide indefinitely.
A value of 1 means the body may come to a stop almost instantly after a force is applied.
The effects of the value may be non-linear.
High values may be unstable depending on the body.
The engine uses a Coulomb friction model including static and kinetic friction.
Note that collision response is based on pairs of bodies, and that friction values are combined with the following formula:
Math.min(bodyA.friction, bodyB.friction)
0.1
Optional frictionA Number that defines the air friction of the body (air resistance).
A value of 0 means the body will never slow as it moves through space.
The higher the value, the faster a body slows when moving through space.
The effects of the value are non-linear.
0.01
Optional frictionA Number that defines the static friction of the body (in the Coulomb friction model).
A value of 0 means the body will never 'stick' when it is nearly stationary and only dynamic friction is used.
The higher the value (e.g. 10), the more force it will take to initially get the body moving when nearly stationary.
This value is multiplied with the friction property to make it easier to change friction and maintain an appropriate amount of static friction.
0.5
Optional id?: numberAn integer Number uniquely identifying number generated in Body.create by Common.nextId.
Optional inertia?: numberA Number that defines the moment of inertia (i.e. second moment of area) of the body.
It is automatically calculated from the given convex hull (vertices array) and density in Body.create.
If you modify this value, you must also modify the body.inverseInertia property (1 / inertia).
Optional inverseA Number that defines the inverse moment of inertia of the body (1 / inertia).
If you modify this value, you must also modify the body.inertia property.
Optional inverseA Number that defines the inverse mass of the body (1 / mass).
If you modify this value, you must also modify the body.mass property.
Optional isA flag that indicates whether a body is a sensor. Sensor triggers collision events, but doesn't react with colliding body physically.
false
Optional isA flag that indicates whether the body is considered sleeping. A sleeping body acts similar to a static body, except it is only temporary and can be awoken.
If you need to set a body as sleeping, you should use Sleeping.set as this requires more than just setting this flag.
false
Optional isA flag that indicates whether a body is considered static. A static body can never change position or angle and is completely fixed.
If you need to set a body as static after its creation, you should use Body.setStatic as this requires more than just setting this flag.
false
Optional label?: stringAn arbitrary String name to help the user identify and manage bodies.
"Body"
Optional mass?: numberA Number that defines the mass of the body, although it may be more appropriate to specify the density property instead.
If you modify this value, you must also modify the body.inverseMass property (1 / mass).
Optional motion?: numberA Number that measures the amount of movement a body currently has (a combination of speed and angularSpeed). It is read-only and always positive.
It is used and updated by the Matter.Sleeping module during simulation to decide if a body has come to rest.
0
Optional parent?: { angle?: number | undefined; anglePrev?: number | undefined; angularSpeed?: number | undefined; angularVelocity?: number | undefined; area?: number | undefined; axes?: IAxes | undefined; ... 41 more ...; _original?: { ...; } | ... 1 more ... | undefined; }A self reference if the body is not a part of another body.
Otherwise this is a reference to the body that this is a part of.
See body.parts.
Optional parts?: IBody[]An array of bodies that make up this body.
The first body in the array must always be a self reference to the current body instance.
All bodies in the parts array together form a single rigid compound body.
Parts are allowed to overlap, have gaps or holes or even form concave bodies.
Parts themselves should never be added to a World, only the parent body should be.
Use Body.setParts when setting parts to ensure correct updates of all properties.
Optional plugin?: ({}) | ({ name?: string | undefined; version?: string | undefined; for?: string | undefined; uses?: string[] | undefined; install?: { apply?: {} | undefined; call?: {} | undefined; bind?: {} | undefined; ... 6 more ...; [Symbol.hasInstance]?: {} | undefined; } | undefined; _warned?: boolean | undefined; })An object reserved for storing plugin-specific properties.
Optional position?: { x?: number | undefined; y?: number | undefined; }A Vector that specifies the current world-space position of the body.
{ x: 0, y: 0 }
Optional positionOptional positionOptional region?: { id?: string | undefined; startCol?: number | undefined; endCol?: number | undefined; startRow?: number | undefined; endRow?: number | undefined; }Optional render?: ({ text?: { content?: string | undefined; font?: string | undefined; align?: CanvasTextAlign | undefined; color?: string | undefined; size?: number | undefined; isBold?: boolean | undefined; isStroke?: boolean | undefined; paddingX?: number | undefined; paddingY?: number | undefined; } | undefined; ... 4 more ...; op...) | ({ visible?: boolean | undefined; fillStyle?: string | undefined; lineWidth?: number | undefined; strokeStyle?: string | undefined; opacity?: number | undefined; }) | ({ sprite?: { texture?: string | undefined; xScale?: number | undefined; yScale?: number | undefined; xOffset?: number | undefined; yOffset?: number | undefined; } | undefined; visible?: boolean | undefined; fillStyle?: string | undefined; lineWidth?: number | undefined; strokeStyle?: string | undefined; opacity?: nu...)An Object that defines the rendering properties to be consumed by the module Matter.Render.
Optional restitution?: numberA Number that defines the restitution (elasticity) of the body. The value is always positive and is in the range (0, 1).
A value of 0 means collisions may be perfectly inelastic and no bouncing may occur.
A value of 0.8 means the body may bounce back with approximately 80% of its kinetic energy.
Note that collision response is based on pairs of bodies, and that restitution values are combined with the following formula:
Math.max(bodyA.restitution, bodyB.restitution)
0
Optional sleepOptional sleepA Number that defines the number of updates in which this body must have near-zero velocity before it is set as sleeping by the Matter.Sleeping module (if sleeping is enabled by the engine).
60
Optional slop?: numberA Number that specifies a tolerance on how far a body is allowed to 'sink' or rotate into other bodies.
Avoid changing this value unless you understand the purpose of slop in physics engines.
The default should generally suffice, although very large bodies may require larger values for stable stacking.
0.05
Optional speed?: numberA Number that measures the current speed of the body after the last Body.update. It is read-only and always positive (it's the magnitude of body.velocity).
0
Optional timeA Number that allows per-body time scaling, e.g. a force-field where bodies inside are in slow-motion, while others are at full speed.
1
Optional torque?: numberA Number that specifies the torque (turning force) to apply in the current step. It is zeroed after every Body.update.
0
Optional totalOptional type?: "body"A String denoting the type of object.
Optional velocity?: { x?: number | undefined; y?: number | undefined; }A Vector that measures the current velocity of the body after the last Body.update. It is read-only.
If you need to modify a body's velocity directly, you should either apply a force or simply change the body's position (as the engine uses position-Verlet integration).
{ x: 0, y: 0 }
Optional vertices?: IVertex[]An array of Vector objects that specify the convex hull of the rigid body.
These should be provided about the origin (0, 0). E.g.
[{ x: 0, y: 0 }, { x: 25, y: 50 }, { x: 50, y: 0 }]
When passed via Body.create, the vertices are translated relative to body.position (i.e. world-space, and constantly updated by Body.update during simulation).
The Vector objects are also augmented with additional properties required for efficient collision detection.
Other properties such as inertia and bounds are automatically calculated from the passed vertices (unless provided via options).
Concave hulls are not currently supported. The module Matter.Vertices contains useful methods for working with vertices.
body
create
Static getGets the current rotational speed of the body. Equivalent to the magnitude of its angular velocity.
angular speed
getAngularSpeed
Static getGets the current rotational velocity of the body.
angular velocity
getAngularVelocity
Static getGets the current linear speed of the body. Equivalent to the magnitude of its velocity.
speed
getSpeed
Static getStatic isReturns true if the render is a IBodySpriteRender, otherwise false.
True if the render is a IBodySpriteRender, otherwise false
isSpriteRender
Static isReturns true if the render is a IBodyTextRender, otherwise false.
True if the render is a IBodyTextRender, otherwise false
isTextRender
Static nextStatic nextReturns the next unique group index for which bodies will collide.
If isNonColliding is true, returns the next unique group index for which bodies will not collide.
See body.collisionFilter for more information.
Unique group index
nextGroup
Static rotateStatic scaleStatic setGiven a property and a value (or map of), sets the property(s) on the body, using the appropriate setter functions if they exist. Prefer to use the actual setter functions in performance critical situations.
set
Static setSets the angle of the body. By default angular velocity is unchanged.
If updateVelocity is true then angular velocity is inferred from the change in angle.
setAngle
Static setSets the current rotational speed of the body. Direction is maintained. Affects body angular velocity.
setAngularSpeed
Static setSets the current rotational velocity of the body. Affects body angular speed.
setAngularVelocity
Static setSet the centre of mass of the body.
The centre is a vector in world-space unless relative is set, in which case it is a translation.
The centre of mass is the point the body rotates about and can be used to simulate non-uniform density.
This is equal to moving body.position but not the body.vertices.
Invalid if the centre falls outside the body's convex hull.
setCentre
Static setSets the density of the body. Mass and inertia are automatically updated to reflect the change.
setDensity
Static setSets the moment of inertia of the body. This is the second moment of area in two dimensions. Inverse inertia is automatically updated to reflect the change. Mass is not changed.
setInertia
Static setSets the mass of the body. Inverse mass, density and inertia are automatically updated to reflect the change.
setMass
Static setSets the parts of the body.
See body.parts for details and requirements on how parts are used.
See Bodies.fromVertices for a related utility.
This function updates body mass, inertia and centroid based on the parts geometry.
Sets each part.parent to be this body.
The convex hull is computed and set on this body (unless autoHull is false).
Automatically ensures that the first part in body.parts is the body.
setParts
Static setStatic setSets the current linear speed of the body. Direction is maintained. Affects body velocity.
setSpeed
Static setSets the body as static, including isStatic flag and setting mass and inertia to Infinity.
setStatic
Static setStatic setSets the body's vertices and updates body properties accordingly, including inertia, area and mass (with respect to body.density).
Vertices will be automatically transformed to be orientated around their centre of mass as the origin.
They are then automatically translated to world space based on body.position.
The vertices argument should be passed as an array of Matter.Vector points (or a Matter.Vertices array).
Vertices must form a convex hull. Concave vertices must be decomposed into convex parts.
setVertices
Static translateStatic updatePerforms an update by integrating the equations of motion on the body.
This is applied every update by Matter.Engine automatically.
update
Static updateUpdates properties body.velocity, body.speed, body.angularVelocity and body.angularSpeed which are normalised in relation to Body._baseDelta.
updateVelocities
Generated using TypeDoc
The
Matter.Bodymodule contains methods for creating and manipulating rigid bodies. For creating bodies with common configurations such as rectangles, circles and other polygons see the moduleMatter.Bodies.See the included usage examples.