Readonlycapabilitiesadvertised capabilities; user code may branch on these
world gravity. Mutate to change at runtime.
Back-reference to the owning melonJS world (set in init).
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.
ReadonlypixelsSpatial conversion factor between melonJS pixels and Box2D meters.
ReadonlyplanckRaw planck namespace — escape hatch for planck-specific features the portable PhysicsAdapter interface doesn't cover (joints, compound fixtures, native queries, etc.).
Saves you from adding a transitive import * as planck from "planck"
just to reach the factories you need:
const joint = adapter.planck.RevoluteJoint(
{ collideConnected: false },
a.body as PlanckAdapter.Body,
b.body as PlanckAdapter.Body,
adapter.planck.Vec2(0, 0),
);
adapter.world.createJoint(joint);
Game code that touches adapter.planck.* is planck-only — it will
not work under any other physics adapter. Use the
PhysicsAdapter methods for anything that should stay
portable.
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.
The underlying planck world; exposed for advanced use cases.
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: Vector2dOptionalpoint: 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
pixel coordinates. Planck computes fixture AABBs in world meters;
we union them, convert to pixels, then subtract renderable.pos
so the debug plugin (which translates to renderable origin before
drawing) gets local-space bounds.
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 planck.js (https://piqnt.com/planck.js/).
Planck is a JavaScript/TypeScript port of Box2D 2.3.0 — a mature, battle-tested rigid-body simulator with continuous collision detection, sleeping bodies, and joint constraints. This adapter implements the full PhysicsAdapter interface so the same game code that runs on the built-in SAT physics also runs under planck — with the upgrade in capabilities Box2D brings (CCD for fast-moving bodies, restitution- based stacking, real rotational dynamics).
Box2D operates in meters / seconds / radians internally. melonJS stays in pixels for positions and radians for angles; the adapter handles the spatial unit conversion through PlanckAdapterOptions.pixelsPerMeter (default
32). Times are passed through directly (planck expects seconds, the adapter divides the incoming milliseconddtby 1000).Example