melonjs 20.12.0 → 20.14.0

package/skills/melonjs-physics/SKILL.md

@@ -1,12 +1,12 @@
 ---
 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."
+description: "Use this skill for collision, physics bodies, movement, and spatial queries in melonJS — the built-in SAT world and the planck, matter and Rapier 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, switching adapters, setAdapter, PhysicsAdapterClass, create, rotation collision, rotating body, torque, joints, stacking, Body, bodyDef, collision, collisionType, collisionMask, onCollision, onCollisionStart, onCollisionActive, raycast, queryAABB, querySphere, raycast3d, PlanckAdapter, MatterAdapter, RapierAdapter, rapier2d, enableCcd, gravity, velocity, applyForce, isGrounded, isSensor, isTrigger, onShapeCollisionStart, kinematic, subSteps, pixelsPerMeter, Box3d, Sphere, getBodyShapes, hitbox offset, slope, SAT."
 license: MIT
 ---
 
 # Physics and collision
 
-> melonJS has a built-in SAT collision world and two optional rigid-body
+> melonJS has a built-in SAT collision world and three 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.
@@ -18,6 +18,7 @@ license: MIT
 | **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. |
+| **`@melonjs/rapier2d-adapter`** | Same again, backed by Rapier compiled to WebAssembly: many bodies, per-body continuous collision, a character controller. Loaded asynchronously. |
 
 ### Picking one
 
@@ -57,22 +58,50 @@ 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, matter or Rapier?** All three are real rigid-body engines and any
+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.
+  stress: better stacking, better joint behaviour, continuous collision for
+  fast movers. Box2D's `bullet` mode is not a `bodyDef` field: set it on the
+  native body with `(this.body as PlanckAdapter.Body).setBullet(true)`. 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.
+  It is the softer solver: stacks settle less crisply, and it has no continuous
+  collision, so fast bodies need `subSteps`.
+- **Rapier** (`@melonjs/rapier2d-adapter`) is a Rust engine compiled to
+  WebAssembly. It handles many bodies at once, has continuous collision per
+  body for fast projectiles (`(this.body as RapierAdapter.Body).enableCcd(true)`),
+  a kinematic character controller, and simulates a concave polygon exactly.
+  It works in **metres** like planck, with the same `pixelsPerMeter`. The cost
+  is the download: about 3 MB of WebAssembly, fetched and compiled on demand,
+  so the adapter must be made with `await RapierAdapter.create()`.
+
+**By game type**, the same choice from the other end:
+
+| game | adapter | why |
+|---|---|---|
+| tile platformer, jumps authored as curves | built-in | movement is designed, not simulated; a body resting on flat static ground is exact to the pixel |
+| platformer with slopes the player stands still on | any rigid-body adapter | the built-in has no surface friction, so a body on an incline slides down it. Walking up one is your own code on matter and planck (the `platformer-matter` example snaps its player onto sensor slopes); Rapier's character controller does it, through Rapier's own API, not the portable one |
+| platformer with moving platforms that carry the player | planck or Rapier | true kinematic bodies, moved by their velocity; the built-in and matter build a dynamic body for `kinematic` |
+| top-down RPG or adventure, grid or tile puzzle | built-in | collision is "did these touch" plus a push-out; no dependency, smallest bundle |
+| shoot-'em-up, bullet hell | built-in | bullets need detection, not a physical response |
+| 2.5D with height: isometric, beat-'em-up lanes | built-in only | the only backend that takes `Box3d` and `Sphere`; the 2D engines refuse them |
+| fighting game or brawler, hitboxes and hurtboxes on one body | built-in, planck or Rapier | matter ignores a shape's own `collisionType`, `collisionMask` and `isTrigger` |
+| stacking, towers, catapult and destruction puzzles | planck, or Rapier for many pieces | an iterative solver keeps a pile crisp; Rapier is built for many bodies at once |
+| pool, billiards, mini-golf: few bodies, a capped top speed | any rigid-body adapter, matter included | give matter enough `subSteps` that a ball moves less than its radius per sub-step: the `pool-matter` example's break, about 30 px a frame on 16 px balls, runs on 2 |
+| pinball, physical bullets: bodies much faster than their own size, with no useful cap | planck or Rapier | continuous collision (planck's `setBullet`, Rapier's `enableCcd`); matter has none, and each sub-step is a full extra solve |
+| vehicles, ragdolls, ropes, chains | planck or Rapier | joint solvers; on every adapter a joint is made through the engine's own API |
+| casual physics toy, prototype, game jam | matter | it works in pixels, so there is nothing to convert; its softer stacking does not show |
+| sandbox with lots of debris | Rapier | many bodies at once, concave pieces simulated exactly |
+| playable ad, size-capped portal, instant load | built-in, not Rapier | Rapier downloads and compiles about 3 MB of WebAssembly |
+
+One game can use more than one: `world.setAdapter()` swaps the backend between
+screens, so a platformer on the built-in can run a physics mini-game on planck
+(see [Switching adapters while the game runs](#switching-adapters-while-the-game-runs)).
 
 An adapter is an `Application` setting, not a plugin:
 
@@ -81,7 +110,7 @@ import { PlanckAdapter } from "@melonjs/planck-adapter";
 
 const app = new Application(800, 600, {
     parent: "screen",
-    physic: new PlanckAdapter({
+    physic: await PlanckAdapter.create({
         gravity: { x: 0, y: 320 },   // pixels/s², default {x: 0, y: 320}
         pixelsPerMeter: 32,          // default 32
         subSteps: 2,                 // default 1
@@ -90,14 +119,45 @@ const app = new Application(800, 600, {
 await app.init();
 ```
 
+**Make an adapter with `await X.create(options)`.** Every adapter class has
+the same static pair (`PhysicsAdapterClass`): `load()` resolves once the
+adapter can be built, and `create()` waits for it, then constructs. The
+builtin, matter and planck adapters are plain JavaScript, so their `load()`
+resolves at once and `new X(options)` is equivalent and still supported; an
+adapter whose engine is WebAssembly downloads and compiles it in `load()`, and
+only `create()` works for it without a prior `load()`. Write `create()` and
+the code is the same for every adapter.
+
+The Rapier adapter is that case. `new RapierAdapter()` before its `load()` has
+finished throws "Rapier is not loaded yet"; `RapierAdapter.loaded` says
+whether it has. `load()` returns one shared promise, so start it early and the
+download runs alongside the game's own assets:
+
+```js
+const rapierReady = RapierAdapter.load();   // starts the download now
+await loader.preload(assets);
+await rapierReady;
+app.world.setAdapter(new RapierAdapter());
+```
+
 `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.
+pixels. `RapierAdapter` takes `gravity` (pixels/s², default `{x: 0, y: 320}`),
+`pixelsPerMeter` (default `32`) and `subSteps` (default `1`); Rapier's own
+solver settings stay writable on `adapter.world.integrationParameters`.
+
+`subSteps` is the anti-tunnelling knob when per-frame motion exceeds a body
+radius. matter and planck clear forces after every sub-step, so a force applied
+once per frame acts on the first sub-step only: raising `subSteps` weakens
+every `applyForce`, and forces need re-tuning after it changes. Rapier keeps a
+force for the whole frame, across every sub-step, so its forces do not change.
+
+Pick **one** adapter per game (it can be switched later, see
+[Switching adapters while the game runs](#switching-adapters-while-the-game-runs));
+`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
@@ -105,19 +165,22 @@ 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²** |
+| built-in | `0.98` | pixels per STEP², 60 steps a second | **~3600 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²** |
+| rapier | `320` | pixels per second², as planck | **~320 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.
+That is a roughly **elevenfold 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.
+To match a backend you are porting FROM, pick a target in px/s² and convert,
+scaling each default by its measured fall: planck and Rapier take it directly;
+matter takes `target / 900`; the built-in takes `0.98 * target / 3600`,
+because it applies gravity per step, 60 steps a second, 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
@@ -128,7 +191,35 @@ 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.
+`"matter"`, `"rapier"`, `"none"`), so game code can branch without importing
+the class.
+
+### Switching adapters while the game runs
+
+`world.adapter` is read-only. `app.world.setAdapter(adapter)` replaces it, for
+example to move from planck to matter between two screens:
+
+```ts
+import { MatterAdapter } from "@melonjs/matter-adapter";
+
+app.world.setAdapter(await MatterAdapter.create({ gravity: { x: 0, y: 1 } }));
+```
+
+The old adapter is destroyed, and the new one builds every body in the world
+again from its renderable's `bodyDef`, where the renderable stands.
+`world.physic` takes the new adapter's label.
+
+- Nothing else carries over: velocities, forces, contacts and joints start
+  from rest, and gravity is the new adapter's own, in its own unit (see the
+  table above).
+- A body added with a direct `adapter.addBody()` call rather than a `bodyDef`
+  is not built again. A legacy `Body` without a `bodyDef` works on the
+  built-in adapter only.
+- Called from a collision handler, the swap waits for the end of the physics
+  step, so `world.adapter` is still the old adapter for the rest of that
+  handler.
+- Code that kept the old adapter in a field (`this.adapter = app.world.adapter`)
+  must read `app.world.adapter` again after the swap.
 
 ## Two ways to declare a body
 
@@ -152,27 +243,48 @@ class Player extends Sprite {
 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()`.
+Nesting is fine: adding a container registers the body of every renderable
+below it, at any depth, and removing it — destroyed, pooled or kept alive —
+takes them all out again, so moving a whole group with `other.addChild(group)`
+keeps each body simulated, once. A persistent container's children keep their
+bodies through `world.reset()` (a state change or `level.load`).
 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
+renderable out of the scene graph. On the built-in adapter that body is then
+outside the broadphase, so it never collides, and it does not move either
+unless the renderable has `alwaysUpdate` set. On matter, planck and Rapier the
+body is in the engine's world and collides, but its renderable is never drawn.
+
+`type` is `"static"`, `"dynamic"` or `"kinematic"`, but only planck and Rapier
+have a kinematic body: moved by its velocity (`setVelocity`), not by gravity.
+The built-in and matter adapters build `"kinematic"` as a dynamic body, which
+falls under gravity. For a moving platform that works on every backend, use
+`type: "static"` and move it with `app.world.adapter.setPosition()`.
+
+**`fixedRotation` follows the engine, so bodies rotate.** matter, planck and
+Rapier all default it to `false`, and so do their 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
+`frictionAir` damps **rotation as well as translation** on matter, planck and
+Rapier, 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.
+stops, which only became visible once rotation stopped being locked. The same
+holds for `adapter.setFrictionAir()` at runtime (on planck, from
+planck-adapter 1.7.0).
 
 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.
+`isSensor`, `userData`. Not every adapter honours every one. The built-in
+adapter ignores `friction` and `fixedRotation`, and no adapter reads
+`userData`. The built-in maps `frictionAir` onto its per-axis `body.friction`
+vector, a per-step deceleration in pixels rather than the damping the adapters
+use (a fraction per step on matter, a rate per second on planck and Rapier), so
+the same number is not the same drag. The adapters average an `{x, y}` value
+into one.
 
 **`new Body(this, shape)`** — the built-in-native API. Fine, but ties the entity
 to the built-in world.
@@ -180,8 +292,11 @@ 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.
+`isTrigger` (default `false`) and `isActive` (default `true`). On the built-in
+adapter a shape can only **narrow** what its body allows: the body's type/mask
+are checked first. On planck and Rapier a shape's own `collisionType` /
+`collisionMask` replace the body's for that shape, so they can widen it too.
+matter filters per body and ignores them.
 
 ```js
 const feet = new Rect(0, 24, 32, 8);
@@ -192,10 +307,19 @@ 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.
+without shrinking the body's bounds, on every backend. matter, planck and
+Rapier read it only when the body is built, so after changing it call
+`app.world.adapter.updateShape(renderable, renderable.bodyDef.shapes)`, which
+works on every adapter. On those three `updateShape()` builds a new body: its
+velocity carries over, its angle and any joints do not. The built-in also
+reads `isActive` live, from the shapes the body holds; those are not always
+the ones you authored, since a `Rect` is stored as a converted `Polygon`, so
+toggle `body.getShape(i)` there.
+
+`isTrigger` works on the built-in, planck and Rapier; matter ignores it, as it
+does the per-shape filter. Under planck and Rapier the body-wide setters
+(`setCollisionType` / `setCollisionMask` / `setSensor`) write every shape and
+so overwrite per-shape values.
 
 For contacts reported per *shape pair* rather than per body pair, define
 `onShapeCollisionStart` / `onShapeCollisionActive` / `onShapeCollisionEnd`.
@@ -216,7 +340,7 @@ from `bodyDef.shapes` with `id` naming the body to read:
 this.bodyDef = { type: "dynamic", shapes: "shapes", id: "hotdog" };
 ```
 
-This works identically on the built-in, matter and planck adapters — the file is
+This works identically on every adapter — 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.
@@ -224,8 +348,9 @@ 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
+definition. The format carries these per fixture, but the built-in and matter
+cannot honour that, so they reduce onto the body and a file whose fixtures
+disagree warns. An
 explicit field on the definition always wins:
 
 ```js
@@ -252,23 +377,39 @@ 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** |
+| shape | builtin | matter | planck | rapier |
+|---|---|---|---|---|
+| `Rect` | exact | exact | exact | exact |
+| convex `Polygon` | exact | exact | exact, up to 12 vertices | exact, all its points |
+| concave `Polygon` | **wrong**: SAT is convex-only | exact, split into convex parts | its convex hull | exact, as triangles |
+| `RoundRect` | exact | exact | sampled down to 12 vertices | exact, all its points |
+| `Ellipse` | exact | circle of the average radius | circle of the average radius | circle of the average radius |
+| `Line` | exact | thin quad along the segment | thin quad along the segment | exact segment on a static or kinematic body, thin quad on a dynamic one |
+| `Box3d`, `Sphere` | exact, and in 3D | **throws** | **throws** | **throws** |
+| `Point` | supported | **throws** | **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.
+samples it down and keeps the extent. Rapier has no such cap. Anything the 2D
+backends cannot express is refused loudly on each of them, rather than leaving a
+body with no collision geometry that silently never collides.
+
+A concave polygon is a third. A Tiled map is safe: the loader splits a
+concave collision polygon into convex triangles before any backend sees it,
+and a shape editor exports one already split. A concave `Polygon` you build
+yourself is simulated exactly by matter (split into convex parts) and Rapier
+(as triangles); the built-in tests it as if it were convex and planck fills it
+in to its hull, so on those two split it into convex pieces yourself.
+
+A polygon may be wound either way: its edge normals are oriented outward from
+its signed area. Before 20.13 they pointed inward on a counter-clockwise
+polygon — a Tiled polygon drawn that way, anything mirrored with
+`scale(-1, 1)` or a `Rect` of negative width — and the built-in circle test
+then collided a circle with it from tens of pixels away, as soon as their
+bounding boxes met. Polygon against polygon was never affected.
 
 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.
@@ -277,11 +418,13 @@ debug panel is the fastest way to see an approximation for what it is.
 
 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
+matter and planck have no 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.
+be. Neither logged anything. Rapier has a segment, and uses it on a static or
+kinematic body, which is what Tiled terrain is; on a dynamic body, where a
+segment would carry no mass, it uses the same 2px quad.
 
 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
@@ -294,8 +437,8 @@ 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.
+matter, planck and Rapier all 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
@@ -315,7 +458,7 @@ 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
+sloped one, use a rigid-body adapter, 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.
@@ -413,7 +556,20 @@ 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
+These two are methods of the built-in `Body` and are not functions on matter,
+planck or Rapier. The portable forms go through the adapter, or the
+`bodyDef`'s `maxVelocity` / `frictionAir`:
+
+```js
+app.world.adapter.setMaxVelocity(this, { x: 3, y: 15 });
+app.world.adapter.setFrictionAir(this, { x: 0.4, y: 0 }); // the adapters average the axes
+```
+
+A velocity cap is in the adapter's velocity unit: pixels per step on the
+built-in and matter, pixels per second on planck and Rapier (see *Porting*
+below).
+
+Under matter, planck and Rapier, `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
@@ -447,24 +603,36 @@ interface Contacts {
     onCollisionStart?: (response: CollisionResponse, other: Renderable) => void;
 }
 (rock as Contacts).onCollisionStart = (response, other) => { … };
-``` The legacy `onCollision` still exists and has a trap:
+```
+
+How often the lifecycle fires depends on the adapter. The built-in fires each
+hook once per body pair, per side, per step. matter, planck and Rapier report
+contacts per SHAPE pair, so a body touching through two of its shapes gets two
+calls (on Rapier a concave polygon is one shape per triangle), and matter fires
+`onCollisionActive` once per sub-step; planck and Rapier fire it once per
+frame. Guard a one-shot reaction (a pickup, a landing sound) with a flag of
+your own.
+
+The legacy `onCollision` still exists and has a trap:
 
 > 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.
+> "still touching" phase and fires once per side. There it receives the same
+> response as `onCollisionActive` (`a`, `b`, `normal`, `depth`, `pair`), so
+> `overlap`, `overlapN` and `overlapV` are `undefined`.
 
 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.
+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.
+`onCollision` skips the built-in SAT push-out; the other adapters ignore it, and
+what `onCollisionStart` / `onCollisionActive` return is discarded everywhere.
+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:
 
@@ -475,15 +643,22 @@ The two handler families do **not** get the same response object:
 | contact axis | `response.overlapN` / `overlapV` | `response.normal` |
 | also carries | `aInB`, `bInA`, `indexShapeA/B`, `isTriggerContact` | `pair` (adapter-native, absent on built-in) |
 
+The left-hand column is the built-in's. On matter, planck and Rapier
+`onCollision` gets the right-hand one too. On Rapier `pair` is
+`{ collider1, collider2 }`, two collider handles for `adapter.world.getCollider()`.
+
 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`.
+`@deprecated` (and `undefined` under every adapter but the built-in) — use
+`depth` and `normal`. `depth` is in pixels on every adapter (on planck from
+planck-adapter 1.7.0; before, it was always `0`). `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.
+`undefined` as the response; the other adapters pass a real one. Guard it. On
+Rapier a sensor contact, and every `onCollisionEnd`, carries a `normal` of
+`(0, 0)` and a `depth` of `0`: Rapier computes no contact for them, so read
+only `other` there.
 
 ## Never mutate the world during contact dispatch
 
@@ -508,13 +683,19 @@ What actually happens per adapter:
   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.
+  Removing one there is safe from planck-adapter 1.7.0: the body leaves every
+  event and query at once and is destroyed when the step ends. Before that,
+  `removeChildNow()` left an invisible body behind that still collided.
   `onCollisionActive` is dispatched after the step and is the safe one.
 - **matter** — callbacks come from matter's `collisionStart` / `collisionActive`
   / `collisionEnd` events during `Engine.update`.
+- **Rapier**: the adapter reads Rapier's events once its step has returned
+  and dispatches them after, so adding and removing bodies in any handler is
+  safe. A partner still touching a removed body gets its `onCollisionEnd`.
 
 ## Spatial queries
 
-`raycast` and `queryAABB` are implemented by all three adapters:
+`raycast` and `queryAABB` are implemented by every adapter:
 
 ```js
 import { Rect, Vector2d } from "melonjs";
@@ -529,20 +710,42 @@ 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`.
+`Camera3d` sets. So is `raycast3d`. `world.adapter.capabilities.raycasts3d`
+says whether the adapter has them at all, and it stays `true` on the built-in
+under a 2D camera, where `raycast3d` returns `null` and `querySphere` returns
+`[]`: check `world.sortOn === "depth"` as well. `raycast` itself is
+capability-gated by `capabilities.raycasts`.
+
+`queryAABB` does not return the same set everywhere. On the built-in it
+returns every non-kinematic renderable whose bounds overlap the rectangle, with
+a body or without; matter, planck and Rapier query their own world, so they
+return only renderables that have a body. On every adapter a ray skips a body
+it starts inside, so a body casting from its own centre does not hit itself
+(before 20.14 the built-in and matter-adapter < 1.6.0 returned that body); on
+Rapier it hits sensors like any other body.
+
+On the built-in adapter a 2D ray measures each shape the way the narrowphase
+measures it against a planar shape: polygons, `Rect`, `RoundRect` and `Line`
+by their edges, an `Ellipse` with its rotation, a `Box3d` by its XY footprint
+and a `Sphere` as a circle of its radius (a 2D ray is unbounded along Z). A
+`Point` has no area to cross and is skipped, as is an unknown shape type,
+with a one-time console warning. Before 20.13 a body carrying a `Point`,
+`Sphere` or `Box3d` made every ray that reached it throw, and a rotated
+ellipse was hit where it would have been unrotated.
 
 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:
+Two prerequisites on the built-in adapter 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.
+  Rapier behaves the same: it indexes bodies for queries when its world
+  steps, so a body added this frame is found from the next one on.
 
 ## 3D collision: `Box3d`, `Sphere` and the Z pushback
 
@@ -553,10 +756,11 @@ along **Z** as well as X and Y.
 ```js
 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));
+// a box: its centre, measured from the frame's top-left corner like any
+// shape, then its FULL width, height and depth (not half-extents)
+crate.body.addShape(new Box3d(crate.width / 2, crate.height / 2, 0, 40, 60, 40));
+// a sphere: its centre, then one radius
+rock.body.addShape(new Sphere(rock.width / 2, rock.height / 2, 0, 30));
 ```
 
 Reach for these for anything moving in the XZ plane under a `Camera3d` — a
@@ -600,7 +804,7 @@ 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
+`Rect`, `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
@@ -629,8 +833,9 @@ 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
+list on every update (after the children have moved, and before each culling
+check while it is off screen) — 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
@@ -650,19 +855,35 @@ real rigid-body engine:
   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`
+  `physic: await BuiltinAdapter.create({ gravity: new Vector2d(0, g) })` to override
+  it (a `Vector2d` here, where the adapters take `{x, y}`). `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.
+  `applyTorque(τ)` is the direct form. The point is in **world** coordinates,
+  as on the other adapters, and the lever arm is measured from the centre of
+  the shapes where they collide: the renderable's drawn frame (so the anchor
+  counts) plus any parent container's position. `renderable.getBounds()` is
+  in that space, so `b.centerX, b.top` is the top centre.
 - **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.
+- **`isGrounded` reads the last step's push-out, not a live contact test** —
+  `true` when a collision in the last step pushed the body up out of
+  something below it (a floor or a slope, not a wall) and neither
+  `body.falling` nor `body.jumping` is set. Before 20.14 it read the two flags
+  alone, so a body never stepped, or held still in mid-air with
+  `gravityScale` 0, read as grounded. The DIRECTION of the push-out decides
+  the flags: pushed up out of a floor while not rising is a landing, pushed down
+  by a ceiling while rising (or `jumping`) ends the jump and falls, and a
+  side contact, a body touched from above while standing, or a body with
+  `gravityScale` 0 leaves them alone. Before 20.13 a magnitude test decided
+  instead, so anything that sank a pixel or more per step — gravity above
+  about `1.02`, mass above about `1.03`, `timer.tick > 1` at a low frame
+  rate, a floor moving up under it — stayed `falling` while sitting flush on
+  the floor, and could never jump.
 - **`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.
@@ -678,7 +899,7 @@ real rigid-body engine:
 - **`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
+### Rotation collides on planck, matter and Rapier, but not on the built-in solver
 
 This is the sharpest behaviour difference between the adapters, and it is
 silent — nothing warns you.
@@ -686,14 +907,20 @@ 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 |
+| **planck** / **matter** / **rapier** | 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
+rotated needs a rigid-body adapter. 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()`.
 
+The visual turn pivots on the centre of the body's shapes, where they are
+drawn and collide, whatever the renderable's `anchorPoint`. Before 20.13 it
+ignored the anchor, so a centre-anchored renderable turned about its
+bottom-right corner and swung away from where it stood; only a `(0, 0)`
+anchor turned in place.
+
 `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
@@ -701,19 +928,20 @@ Track it yourself if you need to read it back. Before 20.7 it also threw on a
 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
+the engine is actually simulating on planck, matter and Rapier (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
+On the adapters 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
+convex parts matter splits it into, the triangles Rapier builds or the hull
+planck fills it in to, 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
+**If you need rotation to affect collision, use planck, matter or Rapier.** 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
@@ -728,61 +956,140 @@ 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.
+  adapter; reaching for the raw handle (`body.setLinearVelocity` on planck,
+  `body.setLinvel` on Rapier) puts you in metres per second, scaled by
+  `pixelsPerMeter`.
+- **Time base differs.** Built-in `body.vel` and matter's velocity are pixels
+  *per step* (60 steps a second); planck's and Rapier's are pixels *per
+  second*, so the same number is about 60× off there. `maxVelocity` follows the
+  same split, and so does angular velocity: radians per step on the built-in
+  and matter, per second on planck and Rapier.
 - **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.
+  reuse. `applyForce` is cleared after each step, so call it every frame; on
+  matter and planck that step is a sub-step, which is why `subSteps` weakens it
+  there, while Rapier keeps it for the whole frame. `applyImpulse` is the
+  one-shot. planck and Rapier apply
+  `adapter.applyImpulse(renderable, impulse, point)` at its point. The built-in
+  and matter ignore the point; matter has no native impulse, so the adapter
+  emulates it as `Δv = J / mass`.
+- **Pausing stops the whole simulation** on matter, planck and Rapier; the
+  built-in keeps moving a renderable with `updateWhenPaused`.
 - **`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.
+  wherever its `anchorPoint` puts it. The adapter stores a per-body offset so
+  `renderable.pos` stays correct — but read `body.position` directly and you
+  get the centroid.
+- **The default collision type differs.** With no `collisionType`, a body is
+  `ENEMY_OBJECT` on the built-in but category `1` (`PLAYER_OBJECT`) on matter,
+  planck and Rapier. With no `collisionMask`, it collides with every type on
+  every adapter (before planck-adapter 1.7.0, planck stopped at bit 15, so a
+  user type from `collision.types.USER << 9` up never hit it; Rapier filters on
+  the full 32 bits). Set `collisionType` on every `bodyDef`.
+- **`type: "kinematic"` is planck and Rapier only**; the built-in and matter
+  build a dynamic body (see *Two ways to declare a body*).
+- **A `Line` (what Tiled emits for a polyline) is a thin 2px rectangle along
+  the segment on matter**, which is what `getBodyShapes()` reports (since
+  matter-adapter 1.5.0; before that it fell back to its axis-aligned bounding
+  box). Only a degenerate (zero-area, collinear) `Polygon` still falls back to
+  its bounding box. Any other shape type throws `unsupported shape type`.
+- **Ellipses become circles on matter, planck and Rapier**, 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.
+  differently per adapter: the last step's push-out on built-in, a live scan of
+  active contacts on matter, planck and Rapier, counting a solid contact that
+  pushes the body up (a sensor contact counts when the other body is below).
+  On every adapter the side of a wall is not ground.
 
 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.
+`velocityLimit`, `isGrounded`) is the portable way to branch. matter reports
+`continuousCollisionDetection: false` (from matter-adapter 1.6.0; earlier
+versions claimed `true`): it has none, and `subSteps` is the remedy for fast
+bodies. Its `sleepingBodies` needs `matterEngineOptions: { enableSleeping: true }`.
+Rapier reports `continuousCollisionDetection: true`, but it is opt-in per body.
+
+Rapier's escapes are `adapter.rapier` (the Rapier module) and `adapter.world`
+(the Rapier world), with the body typed as `RapierAdapter.Body`:
+
+```ts
+const adapter = app.world.adapter as RapierAdapter;
+const { rapier, world } = adapter;
+(bullet.body as RapierAdapter.Body).enableCcd(true);    // continuous collision
+const hinge = rapier.JointData.revolute({ x: 0, y: 0 }, { x: 0, y: 0 }); // metres, body-local
+world.createImpulseJoint(hinge, door.body as RapierAdapter.Body, frame.body as RapierAdapter.Body, true);
+const controller = world.createCharacterController(0.01);   // 0.01 m skin
+```
+
+The other joints are `JointData.fixed`, `spring`, `rope` and `prismatic`.
+Rapier's objects live in WebAssembly memory, which the garbage collector does
+not reclaim. The adapter's `destroy()`, which `setAdapter()` calls on the
+adapter it replaces, frees its world; free a joint or a character controller
+you made yourself with `world.removeImpulseJoint()` /
+`world.removeCharacterController()`.
 
 ## Symptom → cause
 
 | symptom | cause |
 |---|---|
 | entity jitters or does not move | assigning `pos` instead of applying force |
+| `world.adapter = …` throws a `TypeError` | `world.adapter` is read-only; call `world.setAdapter(adapter)` |
+| a body stops simulating after `world.setAdapter()` | it was added with a direct `adapter.addBody()`; give it a `bodyDef` |
 | 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"`) |
+| `new RapierAdapter()` throws "Rapier is not loaded yet" | its WebAssembly loads asynchronously; use `await RapierAdapter.create(options)`, or `await RapierAdapter.load()` first |
+| a fast body passes through a thin one (Rapier) | continuous collision is per body and off by default: `(body as RapierAdapter.Body).enableCcd(true)` |
+| `normal` is `(0, 0)` and `depth` is `0` (Rapier) | a sensor contact or an `onCollisionEnd`: Rapier computes no contact there |
+| `querySphere` / `raycast3d` is not a function | matter, planck or Rapier: all are 2D-only and omit them |
+| `querySphere` returns `[]` and `raycast3d` returns `null` (built-in) | no 3D broadphase: `world.sortOn !== "depth"`; they need a `Camera3d` stage |
+| `queryAABB` misses objects that have no body (matter, planck, Rapier) | those adapters query their own world, which holds bodies only |
 | 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` |
+| `response.depth` / `response.normal` are `undefined` (built-in) | reading a legacy `onCollision` response — it carries `overlap` / `overlapN` |
+| `response.overlapV` / `overlapN` are `undefined` (matter, planck, Rapier) | the adapters hand `onCollision` the modern response too; use `normal` / `depth` |
+| a pickup or a landing sound fires twice (matter, planck, Rapier) | contacts are reported per shape pair, and `onCollisionActive` once per sub-step on matter; guard with a flag |
+| a `type: "kinematic"` platform falls (built-in, matter) | only planck and Rapier have kinematic bodies; use `type: "static"` and `adapter.setPosition()` |
+| `this.body.setMaxVelocity is not a function` (matter, planck, Rapier) | it is a built-in `Body` method; use `app.world.adapter.setMaxVelocity(this, { x, y })` |
+| every force got weaker after raising `subSteps` (matter, planck) | forces are cleared after each sub-step, so they act on the first one only; re-tune (Rapier keeps a force for the whole frame) |
+| `isActive = false` on a shape changes nothing (matter, planck, Rapier) | read only when the body is built; call `adapter.updateShape(renderable, shapes)` |
 | `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 |
+| 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 a rigid-body adapter |
 | 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 |
+| 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 the rigid-body adapters are for |
+| `applyForce` with a point spins a body pushed through its centre, or tips it the wrong way (built-in) | before 20.13 the point was measured against the body's LOCAL bounds, so only a body at the world origin got the right torque; upgrade, and drop any `pos` you subtracted to compensate |
 | 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 |
+| `body.position` disagrees with `renderable.pos` on matter | matter stores the centroid, while `renderable.pos` sits where its `anchorPoint` puts it; the adapter offsets between them |
+| a `bodyDef` two containers down never falls nor collides (`body` stays `undefined`) | before 20.13 only the added container's own children were registered; upgrade |
+| `other.addChild(group)` throws "renderable is already adapter-managed" | before 20.13 a group detached with keepalive (which moving it does) left its children's bodies registered, still simulated off-stage; upgrade |
+| the children of a persistent container stop falling and colliding after a state change or `level.load` | before 20.13 `world.reset()` kept only the bodies whose own renderable was persistent; upgrade, or flag each child `isPersistent` |
 | `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)` |
+| a rotated sprite collides as if upright | the built-in solver rotates visually only — `body.angle` never rotates the shapes. Use a rigid-body adapter, or `body.rotate(angle)` |
+| `setAngle` swings a sprite away from where it stood (built-in) | before 20.13 the pivot ignored `anchorPoint`, so a centre-anchored renderable turned about its bottom-right corner; upgrade |
+| `isGrounded()` stays `false` on the floor, so the player cannot jump (built-in) | before 20.13 a body sinking 1px or more per step (gravity or mass above ~1.02, `timer.tick > 1`, a rising floor) never landed; upgrade |
+| `isGrounded()` is `true` in mid-air, for a body with `gravityScale` 0 or one not yet stepped (built-in) | before 20.14 it read the `falling` / `jumping` flags alone, without a surface under the body; upgrade |
+| a ray cast from a body's centre hits that body (built-in, matter) | before 20.14 / matter-adapter 1.6.0 a ray did not skip a body it starts inside; upgrade |
+| `raycast()` / `queryAABB()` find nothing right after the bodies are added (built-in, Rapier) | both index bodies for queries during a world step: query from the next frame on |
+| a circle body is shoved by a polygon it is nowhere near (built-in) | before 20.13 a counter-clockwise polygon (Tiled, mirrored with `scale(-1, 1)`) had inward edge normals; upgrade |
+| `raycast` throws "reading 'x'" / "reading 'length'" (built-in) | before 20.13 a body carrying a `Point`, `Sphere` or `Box3d` broke the ray walk; upgrade |
+| a ray passes through a rotated ellipse, or stops short of it (built-in) | before 20.13 the raycast ignored `Ellipse#angle`; upgrade |
 | 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 |
+| a Tiled polyline becomes a solid box on matter | matter-adapter < 1.5.0 built a `Line` as its AABB; upgrade (a degenerate `Polygon` still falls back to one) |
+| the player climbs a tall wall with repeated jumps (matter, planck) | matter-adapter < 1.5.3 / planck-adapter < 1.6.3 counted any contact with a lower body as ground; upgrade |
+| a hero made of several shapes is never grounded, so it cannot jump (matter) | matter-adapter < 1.5.3 missed contacts on the parts of a compound body; upgrade |
+| `setSensor(true)` on a platform under the player does nothing, so it cannot be dropped through (matter) | matter-adapter < 1.5.3 did not update a contact already in place; upgrade |
+| `raycast` misses a body made of several shapes, or a concave one (matter) | matter-adapter < 1.6.0 did not resolve the part it hit to its body; upgrade |
+| a shape hook's `normal` points the opposite way to `onCollisionStart`'s (matter) | matter-adapter < 1.6.0 reversed it; upgrade |
+| `response.depth` is always `0` (planck) | planck-adapter < 1.7.0 read the depth from the wrong place; upgrade |
+| an invisible body keeps colliding after `removeChildNow()` from `onCollisionStart` (planck) | planck-adapter < 1.7.0 could not destroy a body while the world was locked; upgrade, or use `removeChild()` |
+| a spin never settles after `adapter.setFrictionAir()` (planck) | planck-adapter < 1.7.0 damped movement only there; upgrade |
 
 ## Related skills