ReadonlybodiesActive physics bodies in this simulation.
ReadonlycapabilitiesAdvertised capabilities; user code may branch on these.
Collision detector instance, created in init.
World gravity. Mutate to change at runtime.
ReadonlyphysicShort adapter identifier exposed as world.physic. Lets user code
branch on the active physics implementation without importing the
concrete adapter class.
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.
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.
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: Vector2dWhether 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.
Optional 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);
}
}
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).
Optional 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).
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.
Default PhysicsAdapter that wraps melonJS's native SAT-based physics. Owns the active body set, the Detector, gravity, and the simulation step. Returns the legacy Body class as its body handle so existing property-based game code (
body.vel.x = 5,body.isStatic = true) keeps working unchanged.Instantiated by default during
Applicationconstruction; user code only touches this directly when explicitly wiring it vianew Application(w, h, { physic: { adapter: new BuiltinAdapter() } }).