melonjs 20.7.0 → 20.8.0

package/skills/melonjs-performance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-performance
-description: "Use this skill when a melonJS game drops frames, allocates heavily, or needs to scale to many objects. Covers object pooling, draw-call batching, atlases, baking with CanvasRenderTarget, instancing, culling and alwaysUpdate, the debug plugin, and where the real costs are. Triggers on: performance, slow, frame rate, fps, lag, pool, pool.register, pool.pull, batching, draw calls, InstancedMesh, culling, alwaysUpdate, inViewport, CanvasRenderTarget, optimise, profiling, debug plugin, memory."
+description: "Use this skill when a melonJS game drops frames, allocates heavily, or needs to scale to many objects. Covers object pooling, draw-call batching, atlases, baking with CanvasRenderTarget, instancing, culling and alwaysUpdate, the debug plugin, and where the real costs are. Triggers on: performance, slow, frame rate, fps, lag, pool, pool.register, pool.pull, batching, draw calls, InstancedMesh, culling, alwaysUpdate, inViewport, CanvasRenderTarget, optimise, profiling, debug plugin, memory, render targets, hdr."
 license: MIT
 ---
 
@@ -81,6 +81,23 @@ Two rules that cause subtle bugs when missed:
   successfully recycled object never sees it. Pair event subscriptions with
   `onActivateEvent` / `onDeactivateEvent` instead, or you leak handlers.
 
+- **`removeChild` is DEFERRED, which breaks a pool you re-lend in the same
+  frame.** The removal is queued and runs after the update and draw stack has
+  unwound, so an object you remove and immediately hand out again is torn out
+  from under its new owner when the queue drains: it vanishes, and the frame
+  after that the removal throws `Child is not mine.` Take it out immediately
+  instead, keeping the instance alive for reuse:
+
+  ```js
+  world.removeChildNow(bullet, true);   // keepalive: do NOT destroy it
+  this.freeList.push(bullet);
+  ```
+
+  `removeChildNow(child, keepalive)` with `keepalive` true skips the destroy,
+  which is what you want for anything you own the lifetime of. This is the
+  usual cause of a pooled effect that flickers out one frame after it is
+  recycled.
+
 Engine classes are poolable too: `pool.pull("Tween", target)`. The canonical
 names are unprefixed — `Entity`, `Collectable`, `Trigger`, `Light2d`,
 `Particle`, `Sprite`, `NineSliceSprite`, `Renderable`, `Text`, `BitmapText`,
@@ -95,13 +112,34 @@ name in new code; do not "correct" an `me.`-prefixed one, it is not broken.
 ## `scale()` is multiplicative
 
 A pooled sprite arrives carrying its previous life's transform, and calling
-`scale()` each frame compounds. For absolute scaling:
+`scale()` each frame compounds. `rotate()` is the same. For absolute values,
+reset first:
 
 ```js
 sprite.currentTransform.identity();
 sprite.currentTransform.scale(s, s, 1);
 ```
 
+**Order matters, and it is the opposite of what reads naturally.**
+`Matrix2d.scale` multiplies the matrix ROWS, so it applies AFTER whatever the
+matrix already holds. Scale first and then rotate; rotate first and the scale
+lands in the rotated frame and SHEARS anything non-uniform:
+
+```js
+// correct: a long thin quad, rotated
+t.identity();
+t.scale(length / texW, width / texH);
+t.rotate(angle);
+
+// wrong: the same quad arrives as a parallelogram
+t.identity();
+t.rotate(angle);
+t.scale(length / texW, width / texH);
+```
+
+The symptom is a sprite that looks right at 0 and 90 degrees and skews in
+between, which reads as a bad texture rather than as a transform bug.
+
 ## Culling and update cost
 
 - `Container` recomputes `inViewport` for every child each frame against every
@@ -231,6 +269,45 @@ SwiftShader, where the absolute numbers are wildly pessimistic and the JS
 profile shows the time as `(program)`, outside JS entirely. Ratios transfer;
 milliseconds do not.
 
+## Render targets, and what `hdr` costs
+
+A render target is a canvas-sized GPU surface. The engine allocates them
+lazily and only where a multi-pass chain actually needs one, which is worth
+knowing before assuming an effect is expensive:
+
+- a renderable with **no** post effects: none
+- a renderable with **exactly one** post effect: still none. It takes the
+  `customShader` fast path and draws straight into whatever target is already
+  bound
+- a **camera** with effects: a pair (one capture, one ping-pong intermediate)
+- a sprite with **two or more** effects: its own pair
+
+So the first lever is the count, not the cost of any one effect: going from
+one effect to two on a sprite is what allocates, not going from a cheap shader
+to an expensive one.
+
+`hdr: true` changes the format of that camera pair from 8 bits per channel to
+half-float, which is **8 bytes per pixel instead of 4**. At 1920×1080 that is
+about 8 MB per target instead of 4 MB, so roughly +8 MB for the pair. With
+`antiAlias` on, the capture half is also multisampled and its multisampled
+surface takes the same format, so that part doubles too.
+
+Nothing else moves. Sprite chains and the advanced-blend target stay 8-bit
+whatever `hdr` says, for a correctness reason rather than a thrifty one: their
+final blit composites with `ONE_MINUS_SRC_ALPHA`, and additive blending
+accumulates alpha past 1 in a float target, which would turn that factor
+negative and subtract the backdrop.
+
+**With `hdr` off, nothing changes at all** — every target keeps the 8-bit
+attachment it has always had, and a game that never adds a camera post-effect
+allocates no render targets in the first place. The setting costs nothing
+until something is actually using it.
+
+```js
+// what you actually got, which is not always what you asked for
+if (app.renderer.supportsHDR === false) { /* grade for a chain that clamps */ }
+```
+
 ## Where the costs actually are
 
 In rough order for a typical 2D game:

package/skills/melonjs-physics/SKILL.md

@@ -258,7 +258,8 @@ built-in-only spelling of this and are deprecated since 20.7.0.
 | `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** |
+| `Box3d`, `Sphere` | exact, and in 3D | **throws** | **throws** |
+| `Point` | supported | **throws** | **throws** |
 
 Two of those are worth knowing before you author geometry. Box2D caps a
 polygon's vertex count and says nothing when you go over: measured, a
@@ -329,6 +330,29 @@ body's collision shapes are measured from that same frame, so a shape of
 a shape's own `pos` still offsets it inside that frame (a small hitbox at the
 feet, a hurtbox at the head).
 
+**That frame's origin is its TOP-LEFT corner, which is the trap for a small
+shape.** `new Rect(0, 0, w, h)` reads naturally because it spans the frame.
+A circle or a `Sphere` does not span anything, so `new Sphere(0, 0, 0, r)` on
+a centre-anchored sprite sits on the sprite's corner, not on the sprite. Put
+it at half the frame:
+
+```js
+// centred on a 24x128 sprite whose anchorPoint is (0.5, 0.5)
+bolt.bodyDef = { type: "dynamic", shapes: [new Sphere(24 / 2, 128 / 2, 0, r)] };
+```
+
+Measured on exactly that sprite: with the shape at `(0, 0, 0)`,
+`adapter.getBodyShapes()` reported it at `(-12, -64)` — **64 units up the
+screen, four times its own radius** — so the projectile collided well away
+from where the player saw it, in a way that still looked like a working game
+because the targets were large.
+
+The offset comes from the renderable's own `width` / `height`, NOT from what
+it draws at. Scale a sprite through `currentTransform` and those stay the
+texture's size, so the half-frame term is half the texture, not half the
+drawn quad. The debug overlay is the quickest confirmation: the red shape
+should sit on the art.
+
 This was broken until 20.7: shapes were measured from `pos` regardless of the
 anchor, so anything not anchored at its top-left corner collided where it was
 not drawn, by half a body at the default centred anchor and by a full body
@@ -400,7 +424,30 @@ survives but fights collision resolution and jitters. To teleport, go through
 The lifecycle is `onCollisionStart` (contact begins), `onCollisionActive` (every
 step while it persists) and `onCollisionEnd` (contact breaks). None of them are
 defined on `Renderable` — you just declare the ones you want and the dispatcher
-checks `typeof`. The legacy `onCollision` still exists and has a trap:
+checks `typeof`. That is also why they cannot be declared on the base class: a
+field there would SHADOW the prototype method every subclass that implements
+one defines.
+
+**In TypeScript the response is `CollisionResponse`**, exported from `melonjs`:
+
+```ts
+import type { CollisionResponse, Renderable } from "melonjs";
+
+class Coin extends Sprite {
+    onCollisionStart(response: CollisionResponse, other: Renderable) { … }
+}
+```
+
+On a renderable you do not subclass, declare the hooks you want as OPTIONAL
+members of a local interface and assign through one plain cast — that is the
+opt-in, and it needs no `as unknown as`:
+
+```ts
+interface Contacts {
+    onCollisionStart?: (response: CollisionResponse, other: Renderable) => void;
+}
+(rock as Contacts).onCollisionStart = (response, other) => { … };
+``` 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
@@ -496,50 +543,76 @@ Two prerequisites that produce empty results rather than errors:
 - On the **built-in** adapter, the broadphase is cleared and rebuilt inside
   `world.update()`, so querying before the first update returns nothing.
 
-## 3D collision: `Box3d` and the Z pushback
+## 3D collision: `Box3d`, `Sphere` and the Z pushback
 
-The narrowphase is not 2D-only. `Box3d` is the one shape with a depth extent,
-and a `Box3d`-vs-`Box3d` contact is resolved in three dimensions — it is the
-only pair in the engine that can push back along **Z**.
+The narrowphase is not 2D-only. Two shapes carry a depth extent — `Box3d` and
+`Sphere` — and any pair of them is resolved in three dimensions, pushing back
+along **Z** as well as X and Y.
 
 ```js
-import { Box3d } from "melonjs";
+import { Box3d, Sphere } from "melonjs";
 
-// centre offset from the body, then half-extents on each axis
-rock.body.addShape(new Box3d(0, 0, 0, 40, 60, 40));
-boat.body.addShape(new Box3d(0, 0, 0, 30, 40, 60));
+// a box: centre offset from the body, then half-extents on each axis
+crate.body.addShape(new Box3d(0, 0, 0, 40, 60, 40));
+// a sphere: centre offset, then one radius
+rock.body.addShape(new Sphere(0, 0, 0, 30));
 ```
 
-Reach for this for anything moving in the XZ plane under a `Camera3d` — a
+Reach for these for anything moving in the XZ plane under a `Camera3d` — a
 runner dodging obstacles, a 2.5D platformer, pickups on a course. Hand-rolling
 a distance check there is the usual mistake, and it throws away the
 penetration vector the response already carries.
 
-**Read the Z axis off the response, not `overlapN`.** The MTV is a single
-axis, so exactly one of `overlapN.x`, `overlapN.y` and `overlapNZ` is
-non-zero:
+**Which of the two.** A `Box3d` is world-axis-aligned and cannot be oriented:
+it is right for walls, floors, crates and anything else that stays square to
+the world, and wrong for anything that turns. A `Sphere` has no orientation to
+get wrong, which makes it the shape for things that tumble, and for anything
+laid out over a curved surface — on a globe every object's own "up" points a
+different way, so no single axis-aligned box fits any of them. It is also the
+cheaper test: one distance against a sum of radii.
+
+**Z arrives beside `overlapN`, not inside it.** `overlapN` stays the 2D unit
+vector it always was and `overlapNZ` carries the depth component, because
+`Vector3d` does not extend `Vector2d` and widening the field would have broken
+every existing 2D handler. The two together are a 3D unit vector, and
+`overlapZ = overlapNZ * overlap` exactly as `overlapV = overlapN * overlap`.
+
+**How much of the normal is in each half depends on the shapes.** A `Box3d`
+pair separates along ONE world axis, so a depth contact leaves the 2D fields
+at zero and a legacy 2D handler correctly applies no push. A `Sphere`
+separates along the line between the two centres, which is generally diagonal:
+all three components are non-zero at once. So subtract both halves rather than
+branching on one:
 
 ```js
 onCollision(response, other) {
-    if (response.overlapNZ !== 0) {
-        // a depth-only contact: overlapN / overlapV are BOTH zero here
-        this.pos.z -= response.overlapZ;
-    }
-    return true;
+    // works for either shape: the 2D half is zero when there is no 2D push
+    this.pos.x -= response.overlapV.x;
+    this.pos.y -= response.overlapV.y;
+    this.pos.z -= response.overlapZ;
+    return false;
 }
 ```
 
-That is deliberate: a collision resolved along Z leaves the 2D fields at zero,
-so an existing 2D `onCollision` applies no push rather than a wrong one.
+Branching on `if (response.overlapNZ !== 0)` and then moving only `pos.z` is
+the mistake to avoid: correct for a box pair, and for a sphere it throws away
+the planar half of the contact.
 
-**Mixed pairs degrade to 2D.** `Box3d` against a `Polygon`, `Rectangle`,
-`RoundRect` or `Ellipse` tests the box's XY footprint and treats the planar
-shape as unbounded along Z. Only `Box3d`-vs-`Box3d` gives a depth result, so
-give BOTH sides a `Box3d` when you want one.
+**Mixed pairs degrade to 2D.** A `Box3d` or a `Sphere` against a `Polygon`,
+`Rectangle`, `RoundRect` or `Ellipse` tests the 3D shape's XY footprint and
+treats the planar shape as unbounded along Z, which is what keeps a sphere or
+box body colliding with an ordinary Tiled collision layer. `overlapZ` is zero
+for those, since only one side has a depth to resolve. Give BOTH sides a 3D
+shape when you want a depth result.
 
 This is the narrowphase and is independent of the 3D broadphase queries above
-— `querySphere` / `raycast3d` need `world.sortOn === "depth"`; `Box3d` shapes
-do not.
+— `querySphere` / `raycast3d` need `world.sortOn === "depth"`; a 3D body shape
+does not.
+
+`raycast3d` measures a `Box3d` body as its box and a body that is one `Sphere`
+as that sphere, both exactly. Anything else, including a body mixing the two,
+is measured as the AABB containing its 3D shapes, and a body with none falls
+back to a bounding sphere derived from the renderable's 2D bounds.
 
 **Bounds are what the broadphase sorts by, and they come from the SHAPE.**
 Every item is filed by its renderable's 2D `getBounds()`, so an object with no
@@ -698,6 +771,7 @@ use them. `adapter.capabilities` (`constraints`,
 | a body sinks through one shape of a multi-shape body | fixed in 20.7; before that the compound pass only ever re-resolved the first overlapping pair |
 | a body will not stay put on a slope on the builtin | it is riding the slope and sliding: the builtin has no surface friction, only `frictionAir` damping. Damp it yourself, or use matter/planck |
 | the sprite is drawn offset from its hitbox | pre-20.7 `anchorPoint` moved the drawing but not the collision shapes; upgrade, and drop any offsets you added to compensate |
+| a small shape sits at the sprite's corner | a shape's offset is measured from the drawn frame's TOP-LEFT; `new Sphere(0, 0, 0, r)` is the corner, `(width / 2, height / 2)` is the centre |
 | a rotated renderable reports an unrotated bounding box | `autoTransform: false` opts `updateBounds()` out of the transform |
 | a body in a pile sinks into the floor (built-in) | fixed in 20.7 for anything with an immovable side; bodies pinned only by other DYNAMIC bodies still overlap by a pixel or two, which is what planck/matter are for |
 | forces do nothing after switching adapter | magnitude units differ — re-tune, don't reuse numbers |

package/skills/melonjs-renderables/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-renderables
-description: "Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events on game objects, applying post effects and shaders, or controlling draw order. Covers the pos-relative draw contract, isKinematic and input, addPostEffect vs the deprecated shader property, and z-ordering. Triggers on: Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, anchorPoint, floating."
+description: "Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events on game objects, applying post effects and shaders, or controlling draw order. Covers the pos-relative draw contract, isKinematic and input, addPostEffect vs the deprecated shader property, and z-ordering. Triggers on: Tween, easing, animate, Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, anchorPoint, floating."
 license: MIT
 ---
 
@@ -284,6 +284,7 @@ Hand-rolled equivalents miss the batching and the multi-backend support.
 | `isRenderable = false` did not hide the object | it gates bounds, not drawing — use `alpha` |
 
 ## Related skills
+- `melonjs-scenes-and-state` — `Tween` and the easing families, for animating any of this
 
 - `melonjs-getting-started` — Application lifecycle and the scene graph
 - `melonjs-20-migration` — the deprecated `shader` property and other pre-20 APIs

package/skills/melonjs-scenes-and-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-scenes-and-state
-description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Stage, state, state.set, state.change, state.transition, state.pause, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze."
+description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Tween, easing, fade out, flash, pulse, punch, shrink back, ease in, ease out, animate over time, countdown in update, Stage, state, state.set, state.change, state.transition, state.pause, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze."
 license: MIT
 ---
 
@@ -165,6 +165,18 @@ Returning nothing is falsy and the object can appear frozen while its state move
 `dt` is milliseconds since the last frame and is the right basis for motion —
 the engine already paces it. Do not reach for `performance.now()`.
 
+**Smooth a value toward a target with `math.damp`, not with `lerp` per
+frame.** `lerp(current, target, 0.1)` once per frame moves further on a slow
+frame than on a fast one, so the feel drifts with the frame rate:
+
+```js
+this.speed = math.damp(this.speed, targetSpeed, 5, dt / 1000);
+```
+
+`damp(current, target, lambda, dt)` takes SECONDS, so divide `dt`. Higher
+`lambda` converges faster. See `melonjs-camera-and-drawing` for the camera's
+own `follow()` damping, which is already frame-rate independent for you.
+
 A common idiom for a per-frame game controller with nothing to draw is a
 `Renderable(0, 0, 1, 1)` with `alwaysUpdate = true` and an empty `draw()`.
 
@@ -191,6 +203,59 @@ countdown that should not freeze needs. (That argument was ignored by
 
 ## Tweens
 
+### You are hand-rolling a tween if you write this
+
+The shape, in any of its spellings. If you are adding a field that counts
+milliseconds and dividing it by a constant to get a `0..1`, stop:
+
+```js
+// ✗ a tween, written out longhand
+private flashMs = 0;
+// ... in update(dt)
+if (this.flashMs > 0) {
+    this.flashMs -= dt;
+    const k = this.flashMs / FLASH_MS;      // ← the 0..1
+    effect.setUniform("uIntensity", k * k); // ← and a curve, by hand
+}
+```
+
+```js
+// ✓ the same thing
+const driver = { k: 1 };
+new Tween(driver)
+    .to({ k: 0 }, { duration: FLASH_MS })
+    .easing(Tween.Easing.Quadratic.In)      // the curve, named
+    .onUpdate(() => effect.setUniform("uIntensity", driver.k))
+    .start();
+```
+
+The tells, any one of which is enough: a `*Ms` or `*Age` field that only
+`update()` touches; a division by a `*_MS` constant; `k * k`, `(1 - k) ** 2` or
+`** 1.4` written inline, which is an easing curve spelled by hand; an
+`if (x <= 0)` arm that exists only to clean up at the end, which is
+`onComplete`; a second timer counting the same duration to chain what happens
+next, which is `delay`.
+
+It matters beyond tidiness: a hand-rolled fade needs something to tick it, and
+an effect that is NOT a renderable (one living on the camera, say) has nothing
+that will. That forces an `update(dt)` method and a call site in the game loop
+whose only job is to drive the fade. A tween updates itself, so both disappear.
+
+### When NOT to reach for one
+
+Four shapes that look similar and are not tweens:
+
+| shape | what it is | use |
+| --- | --- | --- |
+| approaching a value that keeps MOVING | a follow, not an animation | `math.damp` |
+| a loop that never ends | oscillation | a sine of your own clock |
+| a gate: cooldown, spawn interval, invulnerability window | a timer, nothing is interpolated | a plain countdown |
+| the same effect on dozens of live objects | per-instance churn | a hand-rolled countdown really is cheaper |
+
+The rule in one line: **fixed duration, known endpoint, one-shot, few
+instances.** All four, or it is not a tween.
+
+
 ```js
 import { Tween, pool } from "melonjs";
 
@@ -216,6 +281,61 @@ Four traps:
 - **Stop a tween before destroying its target**, or `onUpdate` fires against a
   dead renderable.
 
+**To animate something that is not a property, tween a holder and push the
+value in `onUpdate`.** A shader uniform and a light's intensity are both set
+through a method, so there is nothing for `to()` to interpolate directly. The
+callback is invoked with the tweened object as `this` and the eased progress
+`0..1` as its argument:
+
+```js
+const fade = { level: 1 };
+pool.pull("Tween", fade)
+    .to({ level: 0 }, { duration: 400 })
+    .easing(Tween.Easing.Quadratic.Out)
+    .onUpdate(function () {
+        effect.setUniform("uIntensity", this.level);
+        muzzleLight.intensity = this.level * 3;
+    })
+    .start();
+```
+
+Use a `function`, not an arrow, if you want `this` to be the tweened object;
+an arrow keeps the enclosing `this` and you read the holder by name instead.
+For a handful of pooled objects a hand-rolled countdown in `update()` is
+cheaper than a `Tween` each — this is the right tool for one-off effects, not
+for every particle.
+
+### Pick the easing, not just the duration
+
+Eleven families, each with `In`, `Out` and `InOut`. `Out` is what most UI
+wants: the value arrives decisively instead of creeping in. The two worth
+knowing by name beyond the power curves:
+
+| family | what it does |
+| --- | --- |
+| `Back` | **overshoots past the target and settles back**, which is impact: a stamp, a button press, anything that should LAND rather than arrive |
+| `Bounce` | lands and bounces, for something dropping onto a surface |
+
+```js
+// a stamp: scale falls to 1 and springs through it
+const driver = { scale: 5 };
+new Tween(driver)
+    .to({ scale: 1 }, { duration: 420 })
+    .easing(Tween.Easing.Back.Out)
+    .onUpdate(() => { label.currentTransform.identity(); label.scale(driver.scale); })
+    .onComplete(() => camera.shake(12, 400))     // the thump, when it truly lands
+    .start();
+```
+
+`Back` and `Elastic` **leave the range** between your start and end, so clamp
+anything that cannot take it, an opacity or a colour channel above all. The
+overshoot follows the direction of travel: a value tweened DOWN overshoots
+below its target.
+
+Reach for `onComplete` for anything that must happen on arrival, rather than a
+second timer counting the same duration. `delay` in the `to()` options chains
+the next one without a timer either.
+
 ## Guard teardown-adjacent callbacks
 
 Callbacks can fire while a stage is being torn down, when the current state is