melonjs 20.6.0 → 20.7.0

package/skills/melonjs-3d/SKILL.md

@@ -527,6 +527,22 @@ and spot, a stylised quadratic falloff, not inverse-square),
 **`Light2d` is 2D-only** and produces visible artifacts under perspective
 projection. Do not combine it with `Camera3d`.
 
+**`lit: true` only does anything under a `Camera3d`.** Lighting a mesh needs
+world-space normals and a world-space fragment position, and the 2D-camera path
+has neither: its vertices are already the projected output, so there is no world
+space left to light in. Such a mesh degrades to unlit and warns once, naming the
+fix. If you want lit 3D props in an otherwise 2D game, set
+`cameraClass: Camera3d` on the application. (For 2D **sprites**, lighting is a
+separate system that works under a 2D camera as normal, see the lighting skill.)
+
+A `lit` mesh takes a **tangent-space normal map**, so relief comes from the
+material rather than from geometry — `settings.normalMap` (a loader key or any
+image-like source), or MTL `map_bump` / `bump` / `norm`, which the MTL loader
+fetches and applies per material. The tangent frame is derived per fragment, so
+the model needs no tangent attribute, and an unmapped mesh is unaffected. This
+is the 3D counterpart of the `Sprite` normal maps in the lighting skill; they
+are separate systems and a `Mesh` uses this one.
+
 Ground shadows are **on by default** (the `castGroundShadow` application
 setting), and need a GPU backend and a `Camera3d`. As a blanket default they
 skip geometry with no vertical extent — a ground plane. Per object,

package/skills/melonjs-3d-assets/SKILL.md

@@ -63,6 +63,32 @@ level.load("diorama", { scale: 50, onLoaded: () => {
 }});
 ```
 
+### The same options from a Tiled `Trigger`
+
+A `Trigger` authored in Tiled forwards these to `level.load()`, so a trigger that
+walks the player into a glTF level carries the scene's settings as Tiled
+properties:
+
+```js
+world.addChild(new Trigger(x, y, {
+    shapes: [new Rect(0, 0, 100, 100)],
+    to: "diorama",              // the level id — `to`, not `level`
+    scale: 50,
+    rightHanded: false,
+    castGroundShadow: false,
+}));
+```
+
+`scale`, `rightHanded`, `lights`, `lightIntensityScale`, `castGroundShadow` and
+`shadowGroundY` all travel, and so do `container`, `onLoaded`, `flatten` and
+`setViewportBounds`. That list is **hardcoded** in `Trigger` — a `level.load`
+option outside it is dropped without a warning.
+
+**`async` is deliberately excluded.** A trigger with a `color` + `duration`
+sets it itself, because it needs the promise to sequence its fade and reveal; a
+trigger without one loads fire-and-forget and never sets it. Either way an
+authored `async` property is ignored rather than honoured.
+
 ## `rightHanded` — and the default that differs between the two APIs
 
 glTF is authored **Y-up, right-handed**; melonJS is **Y-down, +Z forward**.
@@ -226,16 +252,33 @@ const mesh = new Mesh(400, 300, {
 world.addChild(mesh);
 ```
 
-**The MTL loader fetches the textures it references itself** — `map_Kd` and
-`map_d` are resolved relative to the `.mtl` and preloaded for you, so there is
-no image entry in the manifest above. Passing `texture:` explicitly overrides
-that and pins *one* binding over the whole model, which on a multi-material
-model suppresses the per-material texture split; leave it out unless you mean
-that.
+**The MTL loader fetches the textures it references itself** — `map_Kd`,
+`map_d` and `map_bump` are resolved relative to the `.mtl` and preloaded for
+you, so there is no image entry in the manifest above. Passing `texture:`
+explicitly overrides that and pins *one* binding over the whole model, which on
+a multi-material model suppresses the per-material texture split; leave it out
+unless you mean that.
 
 MTL contributes `Kd` (diffuse tint), `d` / `Tr` (opacity), `Ke` (emissive),
-`Ks` + `Ns` (specular highlight), `map_Kd` (diffuse texture) and `map_d`
-(per-texel opacity). Normal and specular *maps* are not supported.
+`Ks` + `Ns` (specular highlight), `map_Kd` (diffuse texture), `map_d`
+(per-texel opacity) and `map_bump` / `bump` / `norm` (tangent-space normal
+map — needs `lit: true`, and the tangent frame is derived per fragment, so the
+model needs no tangent attribute). All three normal-map spellings are read as
+normal maps even though the format specifies two of them as height maps, which
+is what every exporter actually writes. Specular *maps* (`map_Ks`) and the PBR
+extension's `map_Pr` / `map_Pm` are not supported and warn — the `Pr` / `Pm`
+*scalars* are read and approximated onto the specular terms, the maps would
+need a real PBR model.
+
+`Ka` (ambient) and `illum` (illumination model) are read onto the material and
+readable from `loader.getMTL(name)`, but take no part in shading. That is
+deliberate rather than pending: `Ka` predates scene-wide ambient light and would
+fight `Stage.ambientLightingColor`, and `illum` enumerates fixed-function
+behaviours this renderer has no equivalent for. In particular an `illum` of 0 or
+1 nominally means "no specular", and the engine does **not** honour that — `Ns`
+stays the only gate, so a model that renders correctly today is not restyled by
+a field its exporter wrote inconsistently.
+
 `loader.getOBJ(name)` and `loader.getMTL(name)` return the parsed data if you
 want it directly. OBJ has no scene graph, no lights, no animation — use glTF for
 anything beyond a single static model.

package/skills/melonjs-lighting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-lighting
-description: "Use this skill for 2D dynamic lighting in melonJS — Light2d, ambient light on a Stage, multiple lights, and per-pixel normal-mapped sprites authored in SpriteIlluminator. Covers the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness."
+description: "Use this skill for 2D dynamic lighting in melonJS — Light2d, ambient light on a Stage, multiple lights, and per-pixel normal-mapped sprites authored in SpriteIlluminator. Covers specular highlights via shininess, the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, specular, shininess, highlight, glint, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness."
 license: MIT
 ---
 
@@ -83,6 +83,50 @@ atlas can carry one too: `new TextureAtlas(json, image, { normalMap })` pairs a
 normal texture sharing the colour texture's UVs, and a `Sprite` built from that
 atlas picks it up in preference to its own `settings.normalMap`.
 
+## Specular highlights
+
+A normal map gives a sprite **shape**: the light knows which way each texel
+faces, so a torch reveals bumps and crevices. `shininess` decides whether it
+also **shines**:
+
+```js
+const sword = new Sprite(x, y, {
+    image: "sword",
+    normalMap: "sword_n",
+    shininess: 64,        // 0 (the default) is matte
+});
+```
+
+The difference is what the highlight *does*. Diffuse brightness depends only on
+the angle between the surface and the light, so a torch moving past just makes
+the sprite brighter. A specular highlight only appears where a texel reflects
+the light **toward the screen**, so it slides across the surface as the light
+moves: armour that glints as you walk by, rather than armour that is merely lit.
+
+Low values give a broad sheen (worn metal, wet stone); high values a tight glint
+(polished steel, glass). It is gated on the exponent exactly as MTL `Ns` is on
+the 3D path, so `0` means matte however bright the scene, and a sprite that
+never sets it renders exactly as it always did.
+
+Three things worth knowing:
+
+- **It needs a `normalMap`.** With no surface directions there is nothing to
+  reflect, and the sprite stays matte whatever `shininess` says.
+- **The normal map's alpha channel masks it per texel.** 255 is fully
+  reflective, 0 is dead matte, so one sprite can be a shiny blade with a matte
+  leather grip. A normal map with no alpha detail (the usual case) shines
+  uniformly. Note the corollary: if your normal map already uses alpha for
+  something, that channel now also decides gloss.
+- **It accumulates per light.** Each light contributes its own highlight in its
+  own colour, so a sprite between a warm lamp and a cool one carries two
+  distinct glints that move independently.
+
+The highlight takes the light's own colour and is *added* on top of the lit
+result rather than multiplied into it, which is why a glint blows out toward
+white on a dark sprite instead of tinting with it.
+
+See it running: [Normal Map example](https://melonjs.github.io/melonJS/examples/#/normal-map).
+
 Unlit areas of a normal-mapped sprite render pure black unless you raise
 `Stage.ambientLightingColor` (default black) — that is the base level added to
 every lit pixel, and it is a different knob from `Stage.ambientLight`.

package/skills/melonjs-loading-assets/SKILL.md

@@ -39,7 +39,7 @@ The type strings are melonJS-specific — this is not a generic loader:
 | type | for |
 |---|---|
 | `"image"` | textures, sprite sheets, normal maps |
-| `"json"` | data, texture-atlas descriptors |
+| `"json"` | data, texture-atlas descriptors, collision shapes from a shape editor |
 | `"tmx"` / `"tsx"` | Tiled maps and external tilesets |
 | `"audio"` | sound — **`src` is a directory**, see below |
 | `"video"` | video textures |

package/skills/melonjs-physics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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, and the behaviour differences between adapters. Triggers on: 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 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
 ---
 
@@ -19,6 +19,61 @@ license: MIT
 | **`@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:
 
 ```js
@@ -44,6 +99,34 @@ 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.
 
@@ -72,6 +155,19 @@ 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
@@ -106,6 +202,166 @@ For contacts reported per *shape pair* rather than per body pair, define
 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:
+
+```js
+// 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:
+
+```js
+// 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 |
+| `Point`, `Box3d`, `Sphere` | 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).
+
+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
 
 ```js
@@ -311,6 +567,13 @@ 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`
@@ -319,8 +582,7 @@ real rigid-body engine:
 - **`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. Note the rotation is visual: SAT
-  collisions stay axis-aligned.
+  `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.
@@ -342,6 +604,50 @@ 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
+
+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:
@@ -389,11 +695,22 @@ use them. `adapter.capabilities` (`constraints`,
 | `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 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

package/skills/melonjs-renderables/SKILL.md

@@ -215,6 +215,18 @@ sprite.alpha = 0;              // hides it
 
 Use `alpha` for a blink, or remove the child for a long absence.
 
+## A mask belongs to you, not to the renderable
+
+`renderable.mask` takes a shape you created, and `destroy()` releases the
+reference without recycling it: the same instance may still be masking
+something else, so the engine has no claim on it. If you pool masks, release
+them yourself.
+
+Before 20.7.0 `destroy()` tried to recycle it and **threw** for every type
+`mask` accepts, because it used the legacy name-keyed pool and no geometry
+class is registered there. It failed mid-teardown, so a masked renderable
+could not be destroyed or removed without keepalive at all.
+
 ## Update and draw
 
 ```js
@@ -260,6 +272,7 @@ Hand-rolled equivalents miss the batching and the multi-backend support.
 | object draws at its parent's origin, ignores its position | `draw()` not reading `this.pos` |
 | pointer handler registered but never fires | `isKinematic` left at its `true` default |
 | wrong draw order | anything other than `addChild(child, z)` — see section 3 |
+| `me.pool: object ... cannot be recycled` while destroying | a mask on a renderable, before 20.7.0 |
 | effect cannot be re-enabled after removal | `removePostEffect()` destroyed it |
 | effect silently does nothing | running on the Canvas renderer |
 | object appears frozen while its state changes | `update()` not returning `true` |

package/skills/melonjs-tilemaps/SKILL.md

@@ -100,6 +100,15 @@ melonJS pre-registers `Renderable`, `Sprite`, `NineSliceSprite`, `Text`,
 `BitmapText`, `ImageLayer`, `ColorLayer`, `Light2d`, `Collectable` and `Trigger`
 as Tiled classes, so `Collectable` and `Trigger` work out of the box.
 
+A `Trigger` forwards a **fixed list** of settings to `level.load()` — not
+whatever you pass it. Today that list is `container`, `onLoaded`, `flatten`,
+`setViewportBounds` and the glTF scene options (`scale`, `rightHanded`,
+`lights`, `lightIntensityScale`, `castGroundShadow`, `shadowGroundY`); see the
+3D assets skill. Anything outside it is **dropped silently**, which is worth
+knowing before you spend an afternoon on a map that loads at the wrong scale.
+`async` is excluded deliberately — the trigger needs to sequence its own
+transition.
+
 ## Camera bounds
 
 `level.load` sets the viewport bounds to the map size for you —