19.5 sweep: planck-adapter coverage, portable raycast/queryAABB, new BuiltinAdapter divergence quirks
Bring all three physics-adapter wiki pages in line with what actually
shipped in 19.5.
Migrating-to-the-Physics-Adapter-API.md
- Mention `@melonjs/planck-adapter` alongside matter (it's shipping in
19.5, not "future Box2D")
Switching-Physics-Adapters.md
- "Picking an adapter" example imports PlanckAdapter too; mention the
`physic: "planck"` shortcut.
- Rewrite the "Optional / capability-gated APIs" section: `raycast` and
`queryAABB` are portable across every adapter (previously described
as matter-only — wrong). `queryAABB` is mandatory on the interface;
`raycast` is capability-gated via `capabilities.raycasts` (all three
official adapters return `true`).
- Add an explicit capability matrix (builtin / matter / planck columns)
for `constraints`, `continuousCollisionDetection`, `sleepingBodies`,
`raycasts`, `velocityLimit`, `isGrounded`.
- Behavioural-differences table grows a planck column.
- Joints/Constraints recipe gets a planck sibling (DistanceJoint as
spring, RevoluteJoint as hinge — reached via `adapter.world.createJoint`).
- Sleeping-bodies recipe gets a planck sibling (planck sleeps per-body
by default; toggle via `world.setAllowSleeping` / `body.setAwake`).
- New porting-pitfall: `setVelocity` units are px/step on builtin+matter
but px/s on planck — surfaced when writing the parity tests, real
porting trap.
BuiltinAdapter-Quirks.md
- Add planck-adapter to the "won't carry across" list.
- §6 (inline vs deferred dispatch): planck behaves like matter — events
fire post-step via begin-contact / end-contact listeners.
- Three new quirks (#10, #11, #12) surfaced when writing the parity tests:
- #10 `isGrounded` is flag-based (`!falling && !jumping`), not
contact-based — diverges from matter / planck for resting bodies
under gravity. Already documented in the bug-hunt spec but not on
the wiki.
- #11 `BuiltinAdapter.raycast` / `queryAABB` require a prior
`world.update` to populate the broadphase; matter / planck index
on `addBody` and work immediately. Planned for 19.6 lazy-populate
parity.
- #12 `BuiltinAdapter.step` gates integration on `inViewport ||
alwaysUpdate`; matter / planck don't. Test-environment quirk, but
useful to document.
No code changes — pure documentation alignment with 19.5 reality.
obiot
committed
May 21, 2026
docs(physics): reconcile response-shape and migration pages with Path 2 + supersedes rule
obiot
committed
May 15, 2026
docs(physics): add legacy-to-adapter migration page; link as prerequisite from switching guide
obiot
committed
May 15, 2026