melonjs-physics
Use this skill for collision, physics bodies, movement, and spatial queries in melonJS — the built-in SAT world and the planck/matter adapters. Covers bodyDef vs Body, collision types and masks, the collision callback family and their firing rules, raycast/queryAABB/querySphere, the behaviour differences between adapters, and which one to pick for a given game. Triggers on: which physics engine, choosing an adapter, rotation collision, rotating body, torque, joints, stacking, Body, bodyDef, collision, collisionType, collisionMask, onCollision, onCollisionStart, onCollisionActive, raycast, queryAABB, querySphere, PlanckAdapter, MatterAdapter, gravity, velocity, applyForce, isGrounded, SAT.
melonjs · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add melonjs/melonJS --skill melonjs-physicsAbout this skill
name: melonjs-physics description: "Use this skill for collision, physics bodies, movement, and spatial queries in melonJS — the built-in SAT world and the planck/matter adapters. Covers bodyDef vs Body, collision types and masks, the collision callback family and their firing rules, raycast/queryAABB/querySphere, the behaviour differences between adapters, and which one to pick for a given game. Triggers on: which physics engine, choosing an adapter, rotation collision, rotating body, torque, joints, stacking, Body, bodyDef, collision, collisionType, collisionMask, onCollision, onCollisionStart, onCollisionActive, raycast, queryAABB, querySphere, PlanckAdapter, MatterAdapter, gravity, velocity, applyForce, isGrounded, SAT." license: MIT
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
bulletmode for fast movers. It works in metres, so it has apixelsPerMeterscale 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
Read the complete source ↗