the parent object this body is attached to
Optionalshapes: a initial shape, list of shapes, or JSON object defining the body
OptionalonBodyUpdate: Functioncallback for when the body is updated (e.g. add/remove shapes)
a reference to the parent object that contains this body, or undefined if it has not been added to one.
Current rotation angle (radians). Visual-only under the built-in
SAT solver — the collision shapes themselves are NOT rotated by
angular integration; only renderable.currentTransform is.
Defaults to 0 and is integrated each step from
Body#angularVelocity. Set directly via
Body#setAngle or as a side effect of integration.
Per-step exponential decay applied to Body#angularVelocity
— analog of frictionAir for rotation. 0 = no damping
(bodies spin forever); 1 = full damping per step (rotation
stops instantly). Typical values are small (0.01 – 0.05)
so spin decays naturally over a few seconds. Negative values
are ignored (treated as 0); values > 1 flip the sign each
step (overdamped — usually a foot-gun).
Angular velocity in radians per frame. Default 0 — bodies that
never touch the angular API pay no integration cost. See
Body#setAngularVelocity and Body#applyTorque.
the body bounciness level when colliding with other solid bodies : a value of 0 will not bounce, a value of 1 will fully rebound.
The AABB bounds box representing this body
define the collision type of the body for collision filtering
Readonlyfallingfalling state of the body
true if the object is falling
false if the object is standing on something
body force to apply to this the body in the current step. (any positive or negative force will be cancelled after every world/body update cycle)
// define a default maximum acceleration, initial force and friction
this.body.force.set(1, 0);
this.body.friction.set(0.4, 0);
this.body.setMaxVelocity(3, 15);
// apply a positive or negative force when pressing left of right key
update(dt) {
if (me.input.isKeyPressed("left")) {
this.body.force.x = -this.body.maxVel.x;
} else if (me.input.isKeyPressed("right")) {
this.body.force.x = this.body.maxVel.x;
}
}
body friction
The degree to which this body is affected by the world gravity
If true this body won't be affected by the world gravity.
since 19.5.0 — use gravityScale = 0 (or
bodyDef.gravityScale = 0 at construction, or
body.setGravityScale(0) at runtime) instead. gravityScale
is part of the portable PhysicsBody surface and works
on every adapter; ignoreGravity is a builtin-only field that
the matter adapter silently ignores. The two-field check
(!ignoreGravity && gravityScale !== 0) used by builtin is
redundant — set gravityScale = 0 and both branches agree.
Whether this body is a sensor. A sensor detects collisions and
fires the onCollision* events on the renderable, but does not
physically respond to the contact (the SAT solver skips the
positional push-out). Useful for triggers, ground-snap assists,
etc. — same role as Matter's isSensor.
ReadonlyisEither this body is a static body or not. A static body is completely fixed and can never change position or angle.
Readonlyjumpingjumping state of the body
equal true if the body is jumping
the body mass
max velocity (to limit body velocity)
Moment-of-inertia analog used when converting force-at-offset
and torque into angular velocity: Δω = τ / pseudoInertia.
Defaults to a geometry-derived approximation
(width² + height²) / 12 matching the moment of inertia of a
unit-mass rectangle. Override directly to make a body harder or
easier to spin. Auto-recomputed after every Body#addShape
call — manual overrides must come AFTER the body is fully built.
The current velocity of the body. See to apply a force if you need to modify a body velocity
add the given vertices to the body shape
an array of me.Vector2d points defining a convex hull
Optionalindex: number = 0the shape object for which to set the vertices
accumulate a force on this body for the current step. Repeated calls
within a single update add together; the engine clears the
accumulator at the end of each integration step. Force magnitude
conventions differ between adapters — consult the active adapter's
docs for tuning ranges (builtin: px/frame²; Matter: Newtonian
force/mass·dt², typically ~100× smaller than builtin).
force along the X axis
force along the Y axis
OptionalpointX: numberworld X of the application point; when
present (along with pointY) and different from the body centroid,
the resulting lever arm generates a torque
τ = (r.x · F.y) − (r.y · F.x) that bumps Body#angularVelocity
by τ / pseudoInertia. Omit both pointX and pointY for the
linear-only behaviour that's compatible with code written before
the angular API was added.
OptionalpointY: numberworld Y of the application point
// pure linear thrust (2-arg form, unchanged behaviour):
ship.body.applyForce(0, -0.05);
// off-centre push on a crate: the contact point at the top of the
// crate is above its centroid, so the same horizontal force now
// both translates AND tips the crate forward.
const topX = crate.pos.x + crate.width / 2;
const topY = crate.pos.y;
crate.body.applyForce(1.5, 0, topX, topY);
// wind pushing on the top of a flag-pole: pole tilts, base stays put
// (only meaningful here if the base is anchored / static).
pole.body.applyForce(0.3, 0, pole.pos.x + pole.width / 2, pole.pos.y);
apply an instantaneous impulse to this body — a single-step velocity
change scaled by inverse mass (dv = J / m). Useful for one-shot
events like a cue strike, projectile launch, or knockback, where
mass should influence the resulting velocity change. Repeated calls
within a single update accumulate. Static bodies (mass 0) ignore
the call. Identical signature on the Matter adapter, where the
adapter integrates the impulse the same way (matter has no native
applyImpulse).
impulse along the X axis
impulse along the Y axis
Apply an instantaneous angular impulse: Δω = τ / pseudoInertia.
The angular analog of Body#applyImpulse — bypasses the
lever-arm computation in Body#applyForce for the
"just spin this up directly" case (a power-up's intrinsic spin,
an explicit thruster, a knockback spin effect on hit).
angular impulse magnitude. Positive values produce clockwise rotation on screen (matching the Y-down canvas convention); negative values rotate counter-clockwise.
The forEach() method executes a provided function once per body shape element.
the callback function is invoked with three arguments:
function to execute on each element
OptionalthisArg: objectvalue to use as this(i.e reference Object) when executing callback.
add collision mesh based on a JSON object (this will also apply any physic properties defined in the given JSON file)
a JSON object as exported from a Physics Editor tool
Optionalid: stringan optional shape identifier within the given the json object
how many shapes were added to the body
Read absolute rotation angle (radians).
remove the shape at the given index from the body shape list
the shape object at the specified index
the shape array length
Rotate this body (counter-clockwise) by the specified angle (in radians). Unless specified the body will be rotated around its center point
The angle to rotate (in radians)
Optionalv: Vector2d = ...an optional point to rotate around
Reference to this object for method chaining
Set absolute rotation angle (radians). Updates the body's angle
field and re-syncs the renderable's currentTransform immediately
so the visual rotation reflects the new value without waiting for
the next integration step.
target angle in radians
Set angular velocity directly. Bypasses inertia — the value is the actual rad/frame that integration will apply next step. Use this for "set and hold" rotation (a coin that always spins at the same rate); use Body#applyTorque for impulse-style spin-up.
target angular velocity (rad / frame)
set this body's restitution / bounce factor. 0 = no bounce (energy
absorbed on contact); 1 = perfect elastic rebound; values in
between dampen the rebound. Applied by Body.respondToCollision —
see BuiltinAdapter docs for the cancellation math.
Matches the bodyDef.restitution field name used at registration
time; the body-side property has historically been called bounce,
which is the canonical legacy name and is preserved.
restitution factor, typically in [0, 1]
By default all physic bodies are able to collide with all other bodies,
but it's also possible to specify 'collision filters' to provide a finer
control over which body can collide with each other.
Optionalbitmask: number = collision.types.ALL_OBJECTthe collision mask
// filter collision detection with collision shapes, enemies and collectables
body.setCollisionMask(me.collision.types.WORLD_SHAPE | me.collision.types.ENEMY_OBJECT | me.collision.types.COLLECTABLE_OBJECT);
...
// disable collision detection with all other objects
body.setCollisionMask(me.collision.types.NO_OBJECT);
set the body default friction
horizontal friction
vertical friction
set this body's per-body gravity multiplier. 1 = world gravity
(default), 0 = ignore world gravity (e.g. flying enemy, underwater
float), 2 = 2× gravity (heavy-feel objects). Multiplied with the
world's gravity.y each frame inside applyGravity.
gravity scale factor
set this body's mass. Useful for variable-mass entities (projectiles
loaded with ammo, weight pickups, characters carrying objects).
Mass affects applyImpulse (via dv = J / m) and the proportional
push-out response in dynamic-dynamic collisions. A mass of 0 makes
the body inert to forces and impulses (without going static).
new mass, non-negative
cap the body velocity (body.maxVel property) to the specified value
max velocity on x axis
max velocity on y axis
toggle this body between solid and sensor. Sensor bodies still emit
collision events (onCollisionStart, onCollisionActive,
onCollisionEnd) but the solver does not physically resolve the
contact — same semantics as Matter's isSensor. Useful for one-way
platforms, trigger zones, and ground-snap assists.
OptionalisSensor: boolean = trueset the body as a static body static body do not move automatically and do not check against collision with others
OptionalisStatic: boolean = trueset this body's linear velocity. Portable across physics adapters —
under the builtin adapter this mutates body.vel; under Matter it
delegates to Matter.Body.setVelocity.
velocity along the X axis
velocity along the Y axis
set the body vertices to the given one
an array of me.Vector2d points defining a convex hull
Optionalindex: number = 0the shape object for which to set the vertices
Optionalclear: boolean = trueeither to reset the body definition before adding the new vertices
ProtectedupdateProtectedUpdates the parent's position as well as computes the new body's velocity based
on the values of force/friction. Velocity changes are proportional to the
me.timer.tick value (which can be used to scale velocities). The approach to moving the
parent renderable is to compute new values of the Body.vel property then add them to
the parent.pos value thus changing the position by the amount of Body.vel each time the
update call is made.
Updates to Body.vel are bounded by maxVel (which defaults to viewport size if not set)
At this time a call to Body.Update does not call the onBodyUpdate callback that is listed in the constructor arguments.
true if resulting velocity is different than 0
a Generic Physic Body Object with some physic properties and behavior functionality, to add as a member of a Renderable.
See
Renderable.body