Readonlycapabilitiesadvertised capabilities; user code may branch on these
world gravity. Mutate to change at runtime.
Optional ReadonlynameOptional display name reported on the startup banner. Defaults to
the adapter class name. Third-party packages typically set this to
their npm package id (e.g. "@melonjs/matter-adapter").
Optional 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.
Optional ReadonlyurlOptional URL (npm / homepage / repo) reported on the startup banner. Convention matches the debug-plugin's startup line.
Optional 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.
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: Vector2dOptionalapplyApply an angular impulse (Δω = τ / inertia).
OptionaldestroyCalled when the adapter is being torn down; release native resources.
OptionalgetRead absolute rotation angle (radians). Returns 0 if not tracked.
OptionalgetRead angular velocity (rad / frame). Returns 0 if not tracked.
Return the body's axis-aligned bounding box in renderable-local
coordinates (relative to renderable.pos). Writes into the
supplied out Bounds so callers can poll allocation-free each
frame. Returns undefined if the renderable has no registered
body.
Used by ecosystem tooling — most notably @melonjs/debug-plugin
— to visualize the body's effective collision extent. The adapter
owns coordinate-system conversion: builtin Body already stores
bounds in local space, matter stores them in world space and the
adapter subtracts renderable.pos before writing.
Required by the adapter contract: any adapter that registers bodies MUST implement this. The output is the canonical, local- space representation tools rely on regardless of which engine the adapter wraps.
Return a snapshot of the body's collision shapes in renderable-local coordinates. The returned array is intended for read-only inspection (debug drawing, hit-region queries) — adapters may return a live reference for performance, so callers MUST NOT mutate it. Returns an empty array if no body.
Pairs with getBodyAABB as the adapter-side debug surface; lets each adapter own its coordinate convention without polluting the underlying physics-engine body objects. Required by the adapter contract.
OptionalgetRead 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: Vector2dOptionalinitOptionalisWhether 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.
OptionalraycastSpatial 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).
OptionalsetOptionalsetOptionalsetToggle 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.
OptionalsyncOptional inverse of syncFromPhysics — push a single renderable's current pos/angle into the physics engine. Called by the engine when game code teleports a renderable. Adapters may also expose this via setPosition and skip implementing it directly.
OptionalupdateReplace the body's collision geometry without re-creating the body.
Swappable physics engine integration.
BuiltinAdapterships with melonjs and wraps the engine's native SAT-based physics; third-party adapters (e.g.@melonjs/matter-adapter) implement this interface to plug a different engine in.Lifecycle contract: one adapter per World, instantiated and passed to
Applicationat construction, never swapped at runtime. Adapter state (bodies, constraints, sleeping flags, etc.) does not migrate between adapters.Body handle convention: PhysicsAdapter.addBody returns an opaque handle that becomes
renderable.body. Each adapter chooses its own concrete body type —BuiltinAdapterreturns the legacy Body class so existing property-based code (body.vel.x = 5,body.isStatic = true) keeps working unchanged. Third-party adapters return their engine's native body type. For adapter-agnostic code, use the portable methods on the adapter itself (setVelocity, applyForce, etc.) instead of mutating the handle directly.