Readonlycapabilitiesadvertised capabilities; user code may branch on these
the underlying Matter engine; exposed for advanced use cases.
world gravity. Mutate to change at runtime.
ReadonlymatterRaw matter-js namespace — escape hatch for matter-specific features
the portable PhysicsAdapter interface doesn't cover (constraints,
compound bodies, events on the Matter engine, queries, etc.).
Saves you from adding a transitive import * as Matter from "matter-js"
just to reach the factories you need. The Matter modules are accessed
by the same names matter's own docs use, so examples from the
matter-js docs copy-paste without renaming:
const spring = adapter.matter.Constraint.create({
bodyA: a.body, bodyB: b.body, stiffness: 0.04, length: 80,
});
adapter.matter.Composite.add(adapter.engine.world, spring);
Game code that touches adapter.matter.* is matter-only — it will
not work under any other physics adapter. Use the
PhysicsAdapter methods for anything that should stay portable.
Official matter-js documentation
for the full module reference (Matter.Constraint, Matter.Composite,
Matter.Bodies, Matter.Events, Matter.Query, Matter.Vector, …).
ReadonlynameOptional display name reported on the startup banner. Falls back to the
adapter's physicLabel, then its class name — avoid relying on the latter,
as it is mangled in minified builds. Third-party packages typically set
this to their npm package id (e.g. "@melonjs/matter-adapter").
ReadonlyphysicShort adapter identifier exposed as world.physic. User code uses
it to branch on which physics implementation is active without
importing the adapter class — e.g.
if (app.world.physic === "matter") {
// matter-only setup (constraints, etc.)
}
Convention: a single lowercase token. The first-party labels are
"builtin" (default — BuiltinAdapter) and "matter"
(@melonjs/matter-adapter). Third-party adapters should pick a
concise identifier that won't collide with future official ones.
The reserved value "none" is set on world.physic only when the
user passes physic: "none" to Application to disable physics
entirely; adapters should not use it.
Defaults to "builtin" if an adapter doesn't declare its own — keeps
legacy adapters wired in before this field was added still working.
ReadonlyurlOptional URL (npm / homepage / repo) reported on the startup banner. Convention matches the debug-plugin's startup line.
ReadonlyversionOptional package version reported on the startup banner. Set this when shipping the adapter as a separate npm package so users can tell which version is wired in at a glance.
back-reference to the owning melonJS world (set in init).
Register a body with the simulation. Returns an opaque handle that
becomes renderable.body. Each adapter chooses its own concrete
body type — see the class doc for the convention.
Prefer the declarative path. Set renderable.bodyDef and call
Container.addChild(renderable) — the container auto-invokes
addBody AND inserts the renderable into the world's broadphase
(QuadTree) in one atomic step. Direct calls to addBody only
register the body with this adapter; they do NOT add the renderable
to the world's container hierarchy, so the broadphase won't return
it as a collision candidate. A body registered via direct addBody
without a matching addChild will integrate (velocity, forces) but
never collide.
Optionalpoint: Vector2dApply an angular impulse (Δω = τ / inertia).
Called when the adapter is being torn down; release native resources.
Read absolute rotation angle (radians). Returns 0 if not tracked.
Read angular velocity (rad / frame). Returns 0 if not tracked.
Adapter-side debug surface: the body's AABB in renderable-local
coordinates. Matter tracks body.bounds in WORLD space; we
subtract renderable.pos so the result matches melonJS's local-
space convention (the debug plugin translates to the renderable
origin before drawing, and would otherwise see the bounds drawn
offset by the renderable's world position).
the renderable whose body bounds to read
destination Bounds (filled in place, also returned)
Adapter-side debug surface: the body's collision shapes in renderable-local coordinates, at the body's current rotation.
The authored def.shapes are the pose the body was created with;
rotation lives in the physics body, not in them. Returning them
unrotated made anything reading this — the debug overlay most visibly —
describe a spinning body with an axis-aligned shape. Read-only.
the renderable whose body shapes to read
Read the body's current velocity cap (mirror of
setMaxVelocity). Returns plain {x, y} so callers don't
need to import a vector type. Optional — adapters that don't
implement velocity caps omit this method.
Portable velocity / force / position API. Every adapter implements these by routing to its native engine. Use these instead of mutating the body handle directly when writing adapter-agnostic code.
Optionalout: Vector2dCalled once after the adapter is attached to a World. Adapters may register internal listeners, allocate native engine state, or read world bounds here.
Whether the body has at least one active contact with a surface below it (collision normal pointing up). Capability-gated by AdapterCapabilities.isGrounded. melonJS extension — Matter has no direct equivalent and the MatterAdapter implements it by scanning active pairs each call.
Spatial queries.
raycast is capability-gated by AdapterCapabilities.raycasts.
Adapters that don't support it may omit the method entirely
(typeof adapter.raycast === "function").
queryAABB is mandatory — every adapter must support a region query
(a broadphase walk is already needed for collision detection, so
exposing it costs nothing).
Unregister a body. Called automatically when Container.removeChild
detaches the renderable; direct calls are the inverse of a direct
addBody (rare — use removeChild for the normal lifecycle).
Set angular velocity (rad / frame).
Toggle a body between solid and sensor mode. A sensor still fires
collision events (onCollisionStart / onCollisionActive /
onCollisionEnd) but the engine does not push the bodies apart on
contact — useful for one-way platforms, trigger zones, ground-snap
ground assists, etc.
Adapters without a native sensor flag emulate by toggling the
collision mask between its previous value and NO_OBJECT.
Runtime body-property mutators. Each maps to the corresponding
BodyDefinition field and lets game code change a body's
physical properties without re-creating it. Adapter implementations
route to their native engine (BuiltinAdapter writes to the Body
handle; MatterAdapter calls Matter's Body.set* helpers).
Advance the simulation by one frame. Called from World.update(dt).
Copy physics-engine body positions back to renderable.pos and
rotations to the renderable's transform. Called after step
each frame. Adapters that mutate the renderable directly during
step (e.g. BuiltinAdapter) may leave this a no-op.
Replace the body's collision geometry without re-creating the body.
melonJS physics adapter wrapping matter-js (https://brm.io/matter-js/).
Implements the full PhysicsAdapter interface so the same game code that runs on the built-in SAT physics also runs under Matter — with the upgrade in capabilities Matter brings (real rotational dynamics, restitution-based stacking, constraints, sleeping bodies, native raycasts).
Example