Melonjs Physics Agent Skill

Physics and collision

> melonJS has a built-in SAT collision world and two optional rigid-body

> adapters. Movement, collision callbacks and spatial queries all behave

> differently depending on which is active — and several of the differences fail

> silently.

Choosing a world

| | when |

|---|---|

| built-in (default) | Arcade-style: platformers, top-down games. Fast, position-based, not Newtonian. |

| @melonjs/planck-adapter | Full rigid-body dynamics — stacking, joints, realistic restitution. |

| @melonjs/matter-adapter | Same class of thing, backed by matter-js. |

Picking one

Start with the built-in. It is the default for a reason: no dependency, the

smallest bundle, and its position-based model is what most 2D games actually

want — a platformer's jump arc is a designed curve, not a simulated one, and

tuning gravity against a solver you are fighting is a bad afternoon.

Move to an adapter when the game needs something the builtin cannot express,

and these are the usual triggers:

• Rotation that collides. The clearest signal. The builtin's SAT never reads

body.angle, so a spinning shape collides as though it never turned. See

the note in *Built-in world quirks* below.

• Torque, angular velocity, or spin from an impact. Anything that should

start turning *because* it was hit.

• Joints and constraints — ragdolls, chains, ropes, vehicles, hinged doors.

The builtin has no concept of them.

• Stacking and resting contacts. Boxes that pile up and stay put need an

iterative solver. The builtin resolves each contact once per step with no

iteration pass, which splits three ways. A dynamic body resting on STATIC

geometry is exact, to the pixel, which is the platformer case it exists for.

A body squeezed between a dynamic body and static geometry is exact too: the

immovable side gets the casting vote and the other body absorbs the whole

correction, so a crate shoved against a wall stops at the wall. But a body

squeezed between two DYNAMIC bodies has no immovable side to defer to, so

those per-pair corrections still compete and it comes to rest slightly

overlapping. Three stacked 44px boxes rest flush on the floor with about 2px

of overlap inside the pile, and stay there: a stable equilibrium, not jitter

you can wait out or tune away.

• Believable restitution and friction, where a ball's bounce height and roll

should follow from its material rather than from code you wrote per case.

Stay on the built-in when the game is grid or tile based, movement is

authored rather than simulated, collision is "did these two boxes touch" plus a

push-out, or you are shipping to a tight bundle budget. Tiled maps, Trigger

and Collectable all work on every backend, so this is not a fork in the road

for level content.

planck or matter? Both are real rigid-body engines and either will do; the

adapters expose the same portable API, so a game can switch with an import

change and a gravity re-tune.

• planck (a Box2D port) is the more accurate and the more predictable under

stress: better stacking, better joint behaviour, a continuous-collision

bullet mode for fast movers. It works in metres, so it has a

pixelsPerMeter scale to think about, and its tuning vocabulary is Box2D's.

• matter-js works directly in pixels, which makes it the gentler

introduction, and its compound bodies and constraints are pleasant to author.

It is the softer solver: stacks settle less crisply and fast bodies need

subSteps.

If you have no preference and the game leans on stacking, joints or fast

projectiles, take planck. If you want to be up and running with the least

conversion to think about, take matter.

An adapter is an Application setting, not a plugin:

import { PlanckAdapter } from "@melonjs/planck-adapter";

const app = new Application(800, 600, {
    parent: "screen",
    physic: new PlanckAdapter({
        gravity: { x: 0, y: 320 },   // pixels/s², default {x: 0, y: 320}
        pixelsPerMeter: 32,          // default 32
        subSteps: 2,                 // default 1
    }),
});
await app.init();

PlanckAdapter also takes velocityIterations (default 8) and

positionIterations (default 3). MatterAdapter takes a different set —

gravity (default {x: 0, y: 1}, matter's own convention), subSteps and

matterEngineOptions; it has no pixelsPerMeter because it already works in

pixels. subSteps is the anti-tunnelling knob when per-frame motion exceeds a

body radius. Pick one adapter per game; physic: "none" disables physics

entirely — world.step skips the simulation and the world behaves as a pure

scene graph.

**Gravity is a different unit in every backend, and the defaults are NOT the

same speed.** Each is "Earth-like" in its own convention, but measured against

each other by timing a 200px free fall in one scene:

| backend | default | unit | measured fall |

|---|---|---|---|

| built-in | 0.98 | per FRAME, integrated against timer.tick | ~4450 px/s² |

| matter | {x: 0, y: 1} | matter's own, after its internal gravity.scale | ~900 px/s² |

| planck | 320 | pixels per second² | ~330 px/s² |

That is a thirteenfold spread, so swapping the built-in world for an adapter

and keeping everything else the same makes the whole game feel different. It is

not a bug in either one: they simply do not share a unit.

To match a backend you are porting FROM, pick a target in px/s² and convert:

planck takes it directly; matter takes target / 900; the built-in takes

target / 4450 * 0.98, because it applies gravity per frame rather than per

second. Passing one number to two of them compares nothing: hand planck

matter's {x: 0, y: 1} and it runs at a three-hundredth of Earth gravity.

That mistake is quiet and it does not look like a gravity problem. Bodies fall

slowly enough that a spawner keeping a fixed interval starts constructing them

inside each other, and **a body born overlapping another is outside what a

solver promises to fix**: the contact normals of an interlocked pair can cancel

out, leaving the position solver with nowhere to push. The symptom is two

shapes permanently fused at rest, which reads as a broken collision shape

rather than as a bad gravity constant. Spawn clear of anything already there.

world.physic carries the active adapter's label ("builtin", "planck",

"matter", "none"), so game code can branch without importing the class.

Two ways to declare a body

bodyDef — declarative, portable, works on every adapter. Prefer it.

class Player extends Sprite {
    constructor(x, y, settings) {
        super(x, y, settings);
        this.bodyDef = {
            type: "dynamic",
            shapes: [ /* … */ ],
            collisionType: collision.types.PLAYER_OBJECT,
            collisionMask: collision.types.WORLD_SHAPE | collision.types.ENEMY_OBJECT,
            restitution: 0.2,
        };
    }
}

The engine forwards it to the active adapter when the renderable is added with

Container.addChild, and only if that container is already attached to the root

world; the broadphase picks the renderable up on the next world.update().

Calling adapter.addBody() yourself registers the body but leaves the

renderable out of the scene graph, so it integrates but never collides.

fixedRotation follows the engine, so bodies rotate. Both matter and

planck default it to false, and so do the adapters from matter-adapter 1.4.0

and planck-adapter 1.5.0. Pass fixedRotation: true for anything that must

stay upright, such as a platformer actor. Earlier adapter versions locked

rotation unless told otherwise, which inverted the engine they wrap: bodies

landed holding whatever angle they were given and no collision could turn them,

while setAngle() still worked, so a body could look rotated while being

unable to rotate.

frictionAir damps rotation as well as translation on both adapters, so

it is also what settles a spin. Left at 0 a body that starts turning never

stops, which only became visible once rotation stopped being locked.

Other portable bodyDef fields: density, frictionAir (number or {x, y}),

friction, restitution, gravityScale, maxVelocity, fixedRotation,

isSensor, userData. Not every adapter honours every one — the built-in

adapter ignores friction, fixedRotation and userData, and maps

frictionAir onto its per-axis body.friction damping vector.

new Body(this, shape) — the built-in-native API. Fine, but ties the entity

to the built-in world.

Per-shape filtering and triggers

A shape in shapes may carry its own collisionType, collisionMask,

isTrigger (default false) and isActive (default true). A shape can only

narrow what its body allows — the body's type/mask are checked first.

const feet = new Rect(0, 24, 32, 8);
feet.collisionMask = collision.types.WORLD_SHAPE;
const torso = new Rect(0, 0, 32, 24);
torso.collisionMask = collision.types.ENEMY_OBJECT;
torso.isTrigger = true;      // detects hits, never gets pushed by them

isActive: false removes the shape from the narrow phase *and* from raycasts

without shrinking the body's bounds. Honoured by the built-in and planck

adapters; the matter adapter filters per body and ignores them. Under planck the

body-wide setters (setCollisionType / setCollisionMask / setSensor) write

every fixture and so overwrite per-shape values.

For contacts reported per *shape pair* rather than per body pair, define

onShapeCollisionStart / onShapeCollisionActive / onShapeCollisionEnd.

Declaring at least one of them opts into shape-pair enumeration; declaring none

costs nothing.

Shapes drawn in a physics-shape editor

A visual collision-shape editor exports a JSON file holding a map of body name

to the fixtures authored for it. Preload it like any other JSON, then name it

from bodyDef.shapes with id naming the body to read:

// in the preloader
{ name: "shapes", type: "json", src: "data/physics/shapes.json" }

// then, on the renderable
this.bodyDef = { type: "dynamic", shapes: "shapes", id: "hotdog" };

This works identically on the built-in, matter and planck adapters — the file is

resolved into real shapes before any adapter is handed the definition. Circles

and polygons both load, and a concave outline (exported already decomposed into

convex pieces) becomes one Polygon per piece.

The density, friction and bounce the shapes were authored with are carried onto

the body definition too, each honoured by whichever backends support it — the

built-in adapter ignores contact friction, as it does for a hand-written

definition. The format carries these per fixture, but only planck could honour

that, so they reduce onto the body and a file whose fixtures disagree warns. An

explicit field on the definition always wins:

// bounces at 0.9 whatever the file says
this.bodyDef = { type: "dynamic", shapes: "shapes", id: "hotdog", restitution: 0.9 };

The exporting tool's own filter block is not read, in any spelling. Its

category and mask bits are numbers in that tool's namespace rather than

{@link collision.types}, and a template writes its defaults for every fixture

whether or not you set anything — importing them would silently tag a shape as

something it is not and stop it colliding. Set collisionType / collisionMask

on the body definition instead. A file written by hand may carry those two names

per fixture, and isSensor, which mean the same thing here as there.

Authored shapes and imported ones can sit in the same list.

Two bodies must never share one shapes array: a body owns its shapes and

rotating it mutates them in place. Naming the file sidesteps this — every body

resolved from it mints its own shapes.

Body#fromJSON() and passing an exported list to addShape() are the old,

built-in-only spelling of this and are deprecated since 20.7.0.

Which shapes each backend can actually simulate

| shape | builtin | matter | planck |

|---|---|---|---|

| Rect, Polygon | exact | exact | exact, up to 12 vertices |

| RoundRect | exact | exact (decomposed) | sampled down to 12 vertices |

| Ellipse | exact | circle of the average radius | circle of the average radius |

| Line | exact | thin quad along the segment | thin quad along the segment |

| Box3d, Sphere | exact, and in 3D | throws | throws |

| Point | supported | throws | throws |

Two of those are worth knowing before you author geometry. Box2D caps a

polygon's vertex count and says nothing when you go over: measured, a

16-point outline comes back with 12 vertices and a 36-point one collapses

from 70x36 to 47x18. A RoundRect carries 36 points, four corners of nine

arc segments each, so it is the usual way to meet that cap; the adapter now

samples it down and keeps the extent. Anything the 2D backends cannot express

is refused loudly on both, rather than leaving a body with no collision

geometry that silently never collides.

Whatever a backend really simulates is what getBodyShapes() reports, so the

debug panel is the fastest way to see an approximation for what it is.

Line shapes, and why slopes need a rigid-body adapter

A Line is two points and no area, and it is what Tiled emits for every

polyline, so it is the natural way to author a slope or a strip of ground.

Neither rigid-body engine has a segment primitive, so both simulate one as a

thin quad following the segment (2px), which is what getBodyShapes() reports

back. Before 20.7 each substituted something of its own instead: matter the

line's bounding box, planck a one-metre square wherever the body happened to

be. Neither logged anything.

The builtin solver resolves a sloped segment too, and correctly: a body lands

on it and SLIDES down it, holding a constant distance from the surface while

its x advances. What it has no notion of is SURFACE friction. def.friction

is ignored entirely and body.friction is a per-step velocity damping vector

fed from def.frictionAir, so nothing removes the tangential component of

gravity. A body on an incline therefore accelerates down it forever and leaves

at the end, and in a valley of segments it swings from arm to arm for a while

before coming to rest on the flat. (It used to escape through an arm instead;

that was a separate defect in how a body was separated from a shape list, fixed

in 20.7.)

matter and planck both have real surface friction, so the same valley holds a

body still.

Several shapes on one body. A Tiled polyline arrives as ONE body carrying

one shape per segment, and until 20.7 a body resting on such a ground could

sink through one of the segments and drop out. The narrowphase reports the

FIRST overlapping shape pair it finds, and the compound resolution pass

re-ran that same first-hit-wins scan, so it kept re-resolving the pair it had

already resolved while a neighbour was penetrated unmeasured. Every pair is

enumerated now. If you are ever diagnosing something similar, the experiment

that localises it is to re-run the same geometry as SEVERAL single-shape

bodies: if that holds and one multi-shape body does not, the fault is in the

compound path rather than in the shape type.

Do not diagnose this by dropping a body and reading its final y. A body that

slid off the end of a ramp and a body that fell straight through it both end up

far below, and they look identical in that one number. Track the body against

the surface height at its CURRENT x instead: riding the slope shows a constant

offset while x advances.

So segments collide on every backend. If you need a body to come to REST on a

sloped one, use matter or planck, or damp it yourself: the builtin will slide

it down the incline indefinitely. The Line Collision example draws the

authored segment against the geometry each backend reports, which is the

quickest way to see what a backend is really simulating.

anchorPoint moves the collision shapes with the drawing

anchorPoint says where in its own bounds a renderable sits on its pos:

updateBounds() translates its bounds by `-width * anchorPoint.x, -height *

anchorPoint.y, and preDraw` shifts its rendering by the same amount. A

body's collision shapes are measured from that same frame, so a shape of

new Rect(0, 0, width, height) covers the sprite whatever the anchor is, and

a shape's own pos still offsets it inside that frame (a small hitbox at the

feet, a hurtbox at the head).

**That frame's origin is its TOP-LEFT corner, which is the trap for a small

shape.** new Rect(0, 0, w, h) reads naturally because it spans the frame.

A circle or a Sphere does not span anything, so new Sphere(0, 0, 0, r) on

a centre-anchored sprite sits on the sprite's corner, not on the sprite. Put

it at half the frame:

// centred on a 24x128 sprite whose anchorPoint is (0.5, 0.5)
bolt.bodyDef = { type: "dynamic", shapes: [new Sphere(24 / 2, 128 / 2, 0, r)] };

Measured on exactly that sprite: with the shape at (0, 0, 0),

adapter.getBodyShapes() reported it at (-12, -64) — **64 units up the

screen, four times its own radius** — so the projectile collided well away

from where the player saw it, in a way that still looked like a working game

because the targets were large.

The offset comes from the renderable's own width / height, NOT from what

it draws at. Scale a sprite through currentTransform and those stay the

texture's size, so the half-frame term is half the texture, not half the

drawn quad. The debug overlay is the quickest confirmation: the red shape

should sit on the art.

This was broken until 20.7: shapes were measured from pos regardless of the

anchor, so anything not anchored at its top-left corner collided where it was

not drawn, by half a body at the default centred anchor and by a full body

height at the bottom anchor a platformer actor uses. If you compensated by

offsetting your shapes by hand, remove those offsets. Entity and Tiled

objects set their own anchor to (0, 0), so nothing built either of those

ways is affected.

The debug panel is the quickest check: green is the renderable's bounds, red

is what actually collides, and the two now agree.

One renderable does not take that offset at all: one that has cleared

applyAnchorTransform, the flag preDraw reads before shifting anything.

GLTFModel sets it false outright and Mesh clears it under a Camera3d,

because both emit world coordinates and pivot about their own model origin

rather than a bounds box, so they draw at pos whatever their anchorPoint

still holds. Their bodies are built there too, on every backend, and

raycast3d reports hits in that same frame. If you clear the flag on a

renderable of your own, the same applies: you place it, and your shapes are

measured from pos.

autoTransform: false opts out of rotated bounds

updateBounds() only applies currentTransform when autoTransform is

true. Turn it off and the renderable's bounds stay the UNROTATED frame

while the sprite turns inside them, which quietly feeds a wrong box to

frustum culling and to the broadphase. Measured on a 60x20 box at 90

degrees: 20x60 with autoTransform on, 60x20 with it off.

That flag means "I place myself", so it is a fair contract, but reach for it

only when you really are drawing in your own frame, and remember the bounds

are yours to keep honest then.

Move with forces, not by assigning position

// ✗ the adapters overwrite this from the engine body every step
this.pos.x += this.speed;

// ✓ portable — works on every adapter
this.body.applyForce(thrustX, 0);
this.body.setVelocity(vx, vy);

// ✓ built-in only — `force` and `maxVel` are BuiltinAdapter Body fields
this.body.force.x = this.body.maxVel.x;

maxVel is what turns a force into a speed, so the two are set together. Use

the setters rather than writing the vectors — both take an optional THIRD

argument for the depth axis, left unchanged when omitted, so a 2D call keeps

its behaviour:

this.body.setMaxVelocity(3, 15);   // walk speed, jump speed
this.body.setFriction(0.4, 0);     // ground drag, none vertically

friction here is per-axis per-step velocity damping, not a surface

coefficient — see the built-in quirks below.

Under matter and planck, syncFromPhysics() copies the engine body's position

back onto renderable.pos after every step, so a direct write is simply erased

— no error. The built-in world integrates pos in place instead, so a write

survives but fights collision resolution and jitters. To teleport, go through

adapter.setPosition(renderable, p) so the engine body moves with it.

Collision callbacks — which one to use

The lifecycle is onCollisionStart (contact begins), onCollisionActive (every

step while it persists) and onCollisionEnd (contact breaks). None of them are

defined on Renderable — you just declare the ones you want and the dispatcher

checks typeof. That is also why they cannot be declared on the base class: a

field there would SHADOW the prototype method every subclass that implements

one defines.

In TypeScript the response is CollisionResponse, exported from melonjs:

import type { CollisionResponse, Renderable } from "melonjs";

class Coin extends Sprite {
    onCollisionStart(response: CollisionResponse, other: Renderable) { … }
}

On a renderable you do not subclass, declare the hooks you want as OPTIONAL

members of a local interface and assign through one plain cast — that is the

opt-in, and it needs no as unknown as:

interface Contacts {
    onCollisionStart?: (response: CollisionResponse, other: Renderable) => void;
}
(rock as Contacts).onCollisionStart = (response, other) => { … };

> On the built-in world, onCollision fires twice per frame for

> dynamic-dynamic pairs — once per outer-loop visit — and gets the raw SAT

> response with a fixed a/b per pair. On the adapters it is routed to their

> "still touching" phase and fires once per side.

The legacy dedupe idiom is if (this !== response.a) return;. Defining

onCollisionActive suppresses the legacy callback on that renderable (the

"supersedes" rule, applied per side so a and b can migrate independently),

and is deduped to once per pair per side per frame on every adapter.

Return values only work on the legacy handler. return false from

onCollision skips the built-in SAT push-out; what onCollisionStart /

onCollisionActive return is discarded. To opt a body out of the physical

response, set bodyDef.isSensor / body.setSensor(true), or make the shape a

trigger. With no onCollision defined at all, push-out happens by default for

dynamic non-sensor bodies.

The two handler families do not get the same response object:

| | onCollision (legacy) | onCollisionStart / Active / End |

|---|---|---|

| a / b | fixed per pair | receiver-symmetric: a === this, b === other |

| overlap magnitude | response.overlap | response.depth |

| contact axis | response.overlapN / overlapV | response.normal |

| also carries | aInB, bInA, indexShapeA/B, isTriggerContact | pair (adapter-native, absent on built-in) |

On the modern response overlap / overlapN / overlapV are still present but

@deprecated (and undefined under the matter adapter) — use depth and

normal. normal is the direction the receiver must move to separate, in

canvas coordinates: normal.y < -0.7 means "push me up", i.e. I landed on top

of other.

One portability wrinkle: the built-in adapter dispatches onCollisionEnd with

undefined as the response; the matter and planck adapters pass a real one.

Guard it.

Never mutate the world during contact dispatch

Collision callbacks are dispatched from inside the physics step on every

adapter, and each engine has its own tolerance for being mutated there. Flag the

work and drain it from your Stage.update:

onCollisionStart(response, other) {
    this.pendingRemoval = true;    // don't addChild / removeChildNow here
}

What actually happens per adapter:

• built-in — callbacks fire inline during step(). Container.removeChild

is deferred, so it is safe; removeChildNow(), and the internal destroy()

it calls, are immediate,

and the detector only survives them because it re-checks body === undefined

after every user callback.

• planck — onCollisionStart / onCollisionEnd are dispatched from

planck's begin-contact / end-contact events, which fire *while the world

is locked*. Adding a renderable with a bodyDef there makes planck's

createBody return null and the adapter then throws on the null handle.

onCollisionActive is dispatched after the step and is the safe one.

• matter — callbacks come from matter's collisionStart / collisionActive

/ collisionEnd events during Engine.update.

Spatial queries

raycast and queryAABB are implemented by all three adapters:

import { Rect, Vector2d } from "melonjs";

// nearest hit only — returns null when nothing is hit
const hit = app.world.adapter.raycast(new Vector2d(x0, y0), new Vector2d(x1, y1));
// hit → { renderable, point, normal, fraction }

// takes a Rect, not a Bounds
const inArea = app.world.adapter.queryAABB(new Rect(x, y, w, h));

querySphere(centre, radius) (or querySphere(sphere)) is built-in only,

and only active under a 3D broadphase — i.e. world.sortOn === "depth", which

Camera3d sets. So is raycast3d. Check

world.adapter.capabilities.raycasts3d before calling either. raycast itself

is capability-gated by capabilities.raycasts.

The legacy collision.rayCast(line, result) is a different API: it takes a

Line, returns an array of every intersecting renderable, and only exists

on the built-in path.

Two prerequisites that produce empty results rather than errors:

• isKinematic must be false for a renderable to be in the broadphase at

all (a Body sets this for you).

• On the built-in adapter, the broadphase is cleared and rebuilt inside

world.update(), so querying before the first update returns nothing.

3D collision: Box3d, Sphere and the Z pushback

The narrowphase is not 2D-only. Two shapes carry a depth extent — Box3d and

Sphere — and any pair of them is resolved in three dimensions, pushing back

along Z as well as X and Y.

import { Box3d, Sphere } from "melonjs";

// a box: centre offset from the body, then half-extents on each axis
crate.body.addShape(new Box3d(0, 0, 0, 40, 60, 40));
// a sphere: centre offset, then one radius
rock.body.addShape(new Sphere(0, 0, 0, 30));

Reach for these for anything moving in the XZ plane under a Camera3d — a

runner dodging obstacles, a 2.5D platformer, pickups on a course. Hand-rolling

a distance check there is the usual mistake, and it throws away the

penetration vector the response already carries.

Which of the two. A Box3d is world-axis-aligned and cannot be oriented:

it is right for walls, floors, crates and anything else that stays square to

the world, and wrong for anything that turns. A Sphere has no orientation to

get wrong, which makes it the shape for things that tumble, and for anything

laid out over a curved surface — on a globe every object's own "up" points a

different way, so no single axis-aligned box fits any of them. It is also the

cheaper test: one distance against a sum of radii.

Z arrives beside overlapN, not inside it. overlapN stays the 2D unit

vector it always was and overlapNZ carries the depth component, because

Vector3d does not extend Vector2d and widening the field would have broken

every existing 2D handler. The two together are a 3D unit vector, and

overlapZ = overlapNZ * overlap exactly as overlapV = overlapN * overlap.

How much of the normal is in each half depends on the shapes. A Box3d

pair separates along ONE world axis, so a depth contact leaves the 2D fields

at zero and a legacy 2D handler correctly applies no push. A Sphere

separates along the line between the two centres, which is generally diagonal:

all three components are non-zero at once. So subtract both halves rather than

branching on one:

onCollision(response, other) {
    // works for either shape: the 2D half is zero when there is no 2D push
    this.pos.x -= response.overlapV.x;
    this.pos.y -= response.overlapV.y;
    this.pos.z -= response.overlapZ;
    return false;
}

Branching on if (response.overlapNZ !== 0) and then moving only pos.z is

the mistake to avoid: correct for a box pair, and for a sphere it throws away

the planar half of the contact.

Mixed pairs degrade to 2D. A Box3d or a Sphere against a Polygon,

Rectangle, RoundRect or Ellipse tests the 3D shape's XY footprint and

treats the planar shape as unbounded along Z, which is what keeps a sphere or

box body colliding with an ordinary Tiled collision layer. overlapZ is zero

for those, since only one side has a depth to resolve. Give BOTH sides a 3D

shape when you want a depth result.

This is the narrowphase and is independent of the 3D broadphase queries above

— querySphere / raycast3d need world.sortOn === "depth"; a 3D body shape

does not.

raycast3d measures a Box3d body as its box and a body that is one Sphere

as that sphere, both exactly. Anything else, including a body mixing the two,

is measured as the AABB containing its 3D shapes, and a body with none falls

back to a bounding sphere derived from the renderable's 2D bounds.

Bounds are what the broadphase sorts by, and they come from the SHAPE.

Every item is filed by its renderable's 2D getBounds(), so an object with no

extent cannot be placed and silently collides with nothing. A Mesh takes its

extent from its geometry and a GLTFModel from its part meshes, so both report

where they are without being told. A body's shapes do not contribute, so a

custom collidable built on a bare Container has no extent until you give it

one:

// a container reports an EMPTY bounds until it has a size of its own
group.resize(width, height);

enableChildBoundsUpdate also gives it one, but it re-measures the whole child

list on every update — reach for it only when the extent genuinely IS the

members' union and moves with them (a flock, a squad), not to give a fixed

group a size.

Built-in world quirks

These are specific to the default world and surprise people arriving from a

real rigid-body engine:

• Dynamic-dynamic collision is position-based, not Newtonian. Separation is

mass-proportional but the velocity response is per-body cancellation — two

equal-mass bodies do not exchange momentum the way you would expect.

• An immovable contact wins the step. Each step records, per body, which

directions it has already been pushed out of, and a later dynamic-dynamic

contact will not push it back in one of those directions: the other body

takes the whole correction instead. A light body shoving a heavy one against

a wall therefore stops dead at the wall rather than driving it through, and

the shover absorbs all of the separation. The record lasts one step and is

not contact state — it says nothing about what a body is touching.

• Gravity defaults to (0, 0.98) — pixels per frame², not m/s². Mutate

app.world.adapter.gravity at runtime, or pass

physic: new BuiltinAdapter({ gravity }) to override it. body.gravityScale

(default 1) scales it per body; 0 disables gravity for that body and is

the portable replacement for the deprecated body.ignoreGravity.

• applyForce(x, y) is linear only unless you pass the optional

(pointX, pointY) application point, which generates a torque

τ = r × F into body.angularVelocity via body.pseudoInertia.

applyTorque(τ) is the direct form.

• Force accumulators reset at end-of-step — for every body, including

static, paused and off-screen ones — so forces must be applied every frame to

persist.

• isGrounded is flag-based, not contact-based — the adapter returns

!body.falling && !body.jumping, flags updated by the last resolved

collision, not a live contact test.

• def.density maps 1:1 to body.mass (default 1), and def.friction is

ignored entirely. body.friction is a per-axis Vector2d of per-step

velocity damping fed from def.frictionAir, not a surface coefficient.

• body.maxVel defaults to (490, 490) and hard-clamps velocity after

forces and friction. The canonical movement idiom is

this.body.force.x = this.body.maxVel.x.

• Default collisionType is ENEMY_OBJECT, and default collisionMask is

ALL_OBJECT — set both explicitly.

• Integration is gated on inViewport || alwaysUpdate — an off-screen body

stops simulating unless you set alwaysUpdate = true. It is also gated on

updateWhenPaused while the state manager is paused, and static bodies never

integrate.

• addBody throws on double-registration for a renderable that is already

adapter-managed.

Rotation collides on planck and matter, but not on the built-in solver

This is the sharpest behaviour difference between the adapters, and it is

silent — nothing warns you.

| adapter | a rotating body |

| --- | --- |

| builtin | rotates visually only. body.angle, setAngle() and angular integration write renderable.currentTransform; the collision shapes are never rotated, so a spinning sprite collides as if it were upright |

| planck / matter | rotates for real — the solver owns the body's transform and collision follows it |

So a turret, a swinging platform or a tumbling crate that must *collide*

rotated needs planck or matter. Under the builtin solver, approximate it with a

shape that is close enough at every angle (a circle, or a square for

90° steps), or rotate the shapes yourself with body.rotate(angle) — which

does rotate them, unlike setAngle().

body.rotate() applies a delta and does not update body.angle; the two

are unlinked, so a body driven by rotate() still reports an angle of 0.

Track it yourself if you need to read it back. Before 20.7 it also threw on a

Box3d or Point shape, and did not tell its owner that the body's bounds had

grown.

adapter.getBodyShapes(renderable) reports whichever is true: the geometry

the engine is actually simulating on planck and matter (matter-adapter 1.3.0 /

planck-adapter 1.4.0 and later), unrotated shapes on the builtin solver because

there they genuinely are. That is what the debug overlay draws, so the hitbox

you see is the hitbox that collides — a sprite spinning inside a stationary red

box on the builtin is the solver telling you the truth, not a drawing bug.

On planck and matter that report comes from the engine rather than from your

definitions, so it shows the approximations they make: an Ellipse appears as

the circle of average radius it is simulated as, a concave polygon as the

convex pieces it was decomposed into, and a Rect as a Polygon. Your

authored shapes are untouched and still readable on renderable.bodyDef.shapes.

If you need rotation to affect collision, use planck or matter. That is the

dividing line: the builtin is a position-based solver whose SAT never reads

body.angle, so rotation there is a visual property. body.rotate(angle) is

the workaround, not a rotating body — it permanently moves the shapes, does not

track an angle, and gives you no angular velocity, torque or rotational

response from a collision. A game whose collision genuinely turns (a spinning

hazard, a swinging bridge, a car, anything with torque) wants a real rigid-body

adapter rather than a workaround.

Porting between adapters

Same call, different magnitude — these are the ones that waste an afternoon:

• The portable API converts for you, the native handle does not.

adapter.setVelocity / body.setVelocity(x, y) are in pixels on every

adapter; reaching for the raw handle (body.setLinearVelocity on planck) puts

you in metres per second, scaled by pixelsPerMeter.

• Time base differs. Built-in body.vel is pixels *per frame*; planck and

matter integrate in seconds. The same number is ~60× off.

• Force magnitudes are not comparable between adapters; re-tune rather than

reuse. applyForce is a per-step accumulator everywhere (cleared each step,

so call it every frame) — applyImpulse is the one-shot. Matter has no native

impulse, so the adapter emulates it as Δv = J / mass and ignores the

application point.

• body.position is the centroid in matter, while renderable.pos is

top-left in melonJS. The adapter stores a per-body offset so renderable.pos

stays correct — but read body.position directly and you get the centroid.

• **Degenerate (zero-area / collinear) polygons — a Tiled polyline, a Line —

cannot be built by matter and fall back to their axis-aligned bounding box.**

Any other shape type throws unsupported shape type.

• Ellipses become circles on matter, using the average of the two radii.
• isGrounded is capability-gated (capabilities.isGrounded) and computed

differently per adapter: a flag read on built-in, a live scan of active

contacts on matter.

Adapter-specific escapes exist ((this.body as MatterAdapter.Body).frictionAir,

adapter.matter.Constraint.create(...)) but are not portable — flag them if you

use them. adapter.capabilities (constraints,

continuousCollisionDetection, sleepingBodies, raycasts, raycasts3d,

velocityLimit, isGrounded) is the portable way to branch.

Symptom → cause

| symptom | cause |

|---|---|

| entity jitters or does not move | assigning pos instead of applying force |

| collision handler runs twice per frame | legacy onCollision on a dynamic pair (built-in) — use onCollisionActive |

| return false from a handler does nothing | return values are only honoured by legacy onCollision — use isSensor / isTrigger |

| crash or a null body when spawning from onCollisionStart | world mutated during contact dispatch (locked world under planck) |

| raycast / queryAABB finds nothing | isKinematic still true, or no world.update yet (built-in) |

| querySphere / raycast3d is not a function | 2D adapter, or built-in without a 3D broadphase (sortOn !== "depth") |

| a 3D contact reports no overlap to push against | read overlapNZ / overlapZ — a Z-axis MTV leaves overlapN / overlapV at zero |

| two 3D objects never separate in depth | one of them carries a planar shape; a mixed pair is tested as the box's XY footprint, unbounded along Z |

| response.depth / response.normal are undefined | reading a legacy onCollision response — it carries overlap / overlapN |

| onCollisionEnd handler throws on response | built-in dispatches it with undefined |

| off-screen bodies stop simulating | built-in gating on inViewport; set alwaysUpdate |

| a body sinks through one shape of a multi-shape body | fixed in 20.7; before that the compound pass only ever re-resolved the first overlapping pair |

| a body will not stay put on a slope on the builtin | it is riding the slope and sliding: the builtin has no surface friction, only frictionAir damping. Damp it yourself, or use matter/planck |

| the sprite is drawn offset from its hitbox | pre-20.7 anchorPoint moved the drawing but not the collision shapes; upgrade, and drop any offsets you added to compensate |

| a small shape sits at the sprite's corner | a shape's offset is measured from the drawn frame's TOP-LEFT; new Sphere(0, 0, 0, r) is the corner, (width / 2, height / 2) is the centre |

| a rotated renderable reports an unrotated bounding box | autoTransform: false opts updateBounds() out of the transform |

| a body in a pile sinks into the floor (built-in) | fixed in 20.7 for anything with an immovable side; bodies pinned only by other DYNAMIC bodies still overlap by a pixel or two, which is what planck/matter are for |

| forces do nothing after switching adapter | magnitude units differ — re-tune, don't reuse numbers |

| body.position disagrees with renderable.pos on matter | matter stores the centroid, melonJS the top-left — the adapter offsets between them |

| bodyDef.shapes: "…" throws "is not loaded" | the name must match the name the JSON was preloaded under, not its filename |

| everything falls far too fast or too slow after swapping backends | gravity is a different unit per backend; see the table above |

| debris lands holding its spawn angle and never tumbles | fixedRotation: true, or matter-adapter < 1.4.0 / planck-adapter < 1.5.0 |

| a rotated sprite collides as if upright | the built-in solver rotates visually only — body.angle never rotates the shapes. Use planck/matter, or body.rotate(angle) |

| the debug hitbox does not follow a spinning body | pre-1.2.1 matter-adapter / pre-1.3.1 planck-adapter returned the authored shapes rather than the rotated ones |

| a Tiled polyline becomes a solid box on matter | matter cannot build a zero-area polygon; the adapter falls back to its AABB |

Related skills

• melonjs-renderables — isKinematic, which also gates the broadphase
• melonjs-tilemaps — collision shapes authored in Tiled
• melonjs-loading-assets — preloading a shape editor's export as JSON