Readonlycapabilitiesadvertised capabilities; user code may branch on these
world gravity. Mutate to change at runtime.
Optional 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").
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.
OptionalqueryOptional 3D sphere region query — returns renderables whose
getAbsolutePosition() lies within radius of center.
The narrow phase is a point-in-sphere test against each
candidate's centre; callers wanting bounding-sphere overlap
should intersect with the candidate's bounds afterwards.
Two call shapes:
querySphere(center: Vector3d, radius: number) — loose formquerySphere(sphere: Sphere) — packaged form, the
idiomatic surface once a query shape needs to be passed
around or cachedActive only under a 3D broadphase (Octree, set when
world.sortOn === "depth"). Adapters that don't expose a 3D
spatial index omit the method.
// Loose form — quick one-off query:
const nearby = world.adapter.querySphere?.(enemy.pos, HIT_RADIUS);
// Idiomatic form — give an entity its own bounding sphere and
// reuse it each frame:
import { Sphere } from "melonjs";
class Enemy extends Renderable {
collider = new Sphere(0, 0, 0, 30);
update(dt) {
// keep the sphere glued to this renderable's pose
this.collider.pos.set(this.pos.x, this.pos.y, this.pos.z);
// query — returns every renderable whose centre is within
// this enemy's collider
const nearby = world.adapter.querySphere?.(this.collider) ?? [];
for (const r of nearby) {
// narrow-phase / kind filter / etc.
}
return super.update(dt);
}
}
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).
Optionalraycast3dOptional 3D variant of PhysicsAdapter.raycast. Walks
the world's Octree (active only under cameraClass: Camera3d) and returns the nearest renderable whose bounding
sphere the ray intersects. 2D adapters omit this method;
call sites should check capabilities.raycasts3d first.
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.