melonjs 20.7.0 → 20.9.0

package/skills/melonjs-particles-and-trails/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-particles-and-trails
-description: "Use this skill for particle effects and motion trails in melonJS — ParticleEmitter configuration, burst versus stream emission, the referenceSpace frame of reference introduced in 20.2, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: ParticleEmitter, particles, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, Trail, explosion, smoke, sparks, exhaust, emitter."
+description: "Use this skill for particle effects and motion trails in melonJS — ParticleEmitter configuration, burst versus stream emission, the referenceSpace frame of reference introduced in 20.2, 3D particle motion through elevation and minSpread/maxSpread in 20.8, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: Trail3d, ribbon, exhaust trail, speed streak, ski track, tyre mark, ribbonNormal, ParticleEmitter, particles, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter."
 license: MIT
 ---
 
@@ -28,6 +28,142 @@ emitter.burstParticles();      // one shot
 `duration` setting, which defaults to `Infinity` — a stream runs until
 `stopStream()`. `burstParticles(n)` launches `n`, or `totalParticles`.
 
+## Sprite-sheet particles
+
+Use `framewidth` and `frameheight` (the same names as on `Sprite`) to divide
+`image` into a regular grid. Each omitted dimension defaults to that of the
+image. Frames are numbered from zero left-to-right, then top-to-bottom; only
+whole cells count, so partial cells along the right/bottom edges are ignored.
+Margins and spacing are not supported.
+
+```js
+const explosion = new ParticleEmitter(x, y, {
+    image: loader.getImage("explosion-sheet"),
+    framewidth: 32, frameheight: 32,
+    frames: [0, 1, 2, 3],
+    minLife: 400, maxLife: 800,
+});
+world.addChild(explosion);
+explosion.burstParticles();
+```
+
+Omit `frames` to use every cell. Each particle traverses the sequence once
+over its own lifetime, with equal time for each entry; repeated indices hold
+a frame longer. Existing scale, opacity and rotation still apply. Bounds and
+the rotation pivot use one frame's dimensions, rather than the whole sheet.
+
+Set `randomFrame: true` for debris: a particle chooses one entry at birth and
+keeps it until it dies. Different frames share the same image and GPU batch.
+Without sheet settings, particles still draw the whole image as before, and
+that includes `randomFrame` on its own: it needs a grid to choose from, so
+pair it with `framewidth`/`frameheight` or it does nothing.
+
+Note the variety is in SHAPE, not colour. `tint` belongs to the emitter, so
+every particle from one emitter is tinted alike however many frames it picks
+between.
+
+Frame dimensions must be positive integers that fit inside the image, and an
+explicit `frames` sequence must be nonempty and contain valid integer indices.
+Invalid configurations throw `RangeError` before changing an emitter during
+`reset()`. The frame sequence is copied on construction/reset; resetting changes
+only future particles, so ones already alive finish with their original image,
+frame size and sequence.
+
+## Where particles are born
+
+`width` and `height` are the spawn AREA, and both default to `1` — so by
+default every particle launches from the same pixel. That is fine for a
+fountain and wrong for an explosion: additive sprites piled on one point clip
+all three channels there however well they are tinted, so a burst reads as one
+bright flash rather than as debris.
+
+Give it the size of whatever broke. The area is measured from the emitter's own
+position, NOT centred on it, so offset by half or the whole burst sits down and
+to the right of its source:
+
+```js
+const area = radius * 2;
+const emitter = new ParticleEmitter(x - area / 2, y - area / 2, {
+    width: area, height: area,
+});
+```
+
+## Particles in 3D
+
+By default a particle keeps the depth it was born at for its whole life: it
+moves across the emitter's plane and never toward or away from the camera.
+Under a `Camera3d` that reads as a flat sticker anywhere but dead ahead.
+
+`elevation` lifts the launch out of that plane and `elevationVariation` spreads
+it. `angle` is the azimuth within the plane, as it always was:
+
+```js
+const emitter = new ParticleEmitter(x, y, {
+    angle: 0, angleVariation: Math.PI * 2,
+    elevation: 0, elevationVariation: Math.PI / 2,   // a sphere of debris
+    speed: 9,
+});
+world.addChild(emitter, z);     // the depth slice the burst belongs to
+emitter.burstParticles();
+```
+
+`speed` is the length of the whole 3D vector, so an "all directions" burst
+covers the sphere evenly instead of bunching toward the poles.
+
+Both default to `0`, and that is a gate rather than the 3D path with zeros in
+it: an emitter that asks for no elevation runs the same two trig calls it
+always did, writes no depth and starts no sort.
+
+**The launch is in WORLD axes.** `vel.x` and `vel.y` add to the particle's
+`pos.x`/`pos.y` and `velZ` adds to its depth, so `angle` and `elevation`
+describe a direction in the world, not on the screen. Building them from a
+camera basis works only while the camera's axes ARE the world axes, which stops
+being true the moment you pose a `Camera3d`. For a direction `d` already in
+world terms the pair is `angle: Math.atan2(-d.y, d.x)`,
+`elevation: Math.asin(d.z)`.
+
+### Cones, rings and spheres: aiming around an axis
+
+`angleVariation` and `elevationVariation` are sampled INDEPENDENTLY, spreading
+particles over a rectangle of azimuth by elevation. That cannot describe a
+shape defined against a direction. A ring of debris leaving a point on a sphere
+is the set of directions at ninety degrees to that point's normal, and on a
+rectangle the elevation that satisfies it is a function of the azimuth, so no
+pair of variations gets there.
+
+Set `maxSpread` and `angle`/`elevation` become an AXIS instead. Each particle
+leaves at a polar angle between `minSpread` and `maxSpread` off that axis,
+around a uniformly random azimuth:
+
+| `minSpread` … `maxSpread` | shape |
+|---|---|
+| `0` … `0.5` | a tight cone along the axis |
+| `0` … `Math.PI` | the whole sphere |
+| either value at `Math.PI / 2` | a flat disc perpendicular to the axis |
+
+An explosion on a planet's surface is a ring tangent to it: set the axis to the
+surface normal and use `minSpread: Math.PI / 2 - 0.3, maxSpread: Math.PI / 2`.
+Keeping the band at or inside ninety degrees is what stops debris tilting back
+into the body it came off. `angleVariation` and `elevationVariation` are unused
+while `maxSpread` is set.
+
+### Sorting, and why it is keyed off the blend mode
+
+A 3D burst only needs depth sorting when its blend is order dependent, and the
+emitter decides that for you. Additive blending is commutative, so an additive
+burst looks the same however it is ordered and pays nothing; `"normal"` is not,
+so a 3D burst drawn with it is sorted back to front.
+
+The two differ in more than cost. Additive sprites overlapping near the centre
+of a burst sum to white however they are tinted, so debris that has to keep its
+colour wants `textureAdditive: false` and accepts the sort. A common shape is
+two emitters: a solid, sorted body of debris with a sparser additive spray of
+sparks over it.
+
+The default particle sprite is a filled SQUARE, which additive blending hides
+and normal blending does not. Pass your own soft `image` for non-additive
+debris.
+
 For one-shot effects, `autoDestroyOnComplete: true` removes the emitter once its
 particles have finished. The `onComplete` callback fires at that same moment
 either way.
@@ -89,18 +225,48 @@ Omit `target` and feed it yourself with `trail.addPoint(x, y)` — the mode for
 sword slash, where the ribbon follows a weapon tip rather than an object. Points
 closer together than `minDistance` (default 4 px) are dropped.
 
-**`Trail` is 2D.** `addPoint` takes `(x, y)`, points are stored without a `z`,
-and the ribbon is drawn as connected screen-space quads. Under a `Camera3d` it
-draws a flat ribbon that does not recede with perspective — so it is the wrong
-tool for a trail behind an object moving *into* the scene. For that:
+**`Trail` is 2D. Use `Trail3d` in a 3D scene** (20.9.0 and later). `Trail`
+stores points without a `z` and draws connected screen-space quads, which carry
+one depth for the whole renderable, so under a `Camera3d` the ribbon stays flat
+and does not narrow along its own length.
+
+```js
+const exhaust = new Trail3d(0, 0, {
+    target: ship,                 // samples pos.x / pos.y / pos.z
+    width: 6,                     // world units, and free to change per frame
+    lifetime: 260,
+    gradient: ["#eaffff", "#2ea8ff", "#2ea8ff00"],
+});
+exhaust.blendMode = "additive";
+app.world.addChild(exhaust);      // no z: it derives its own from its points
+```
+
+`Trail3d` is a `Mesh`, which is most of the difference:
+
+- `billboard` is spelled and valued exactly as on `Sprite3d` —
+  `"spherical"` (the default here) faces the camera on all axes,
+  `true` / `"cylindrical"` faces it but stays upright, `false` uses the
+  `ribbonNormal` you give it. `billboard: false, ribbonNormal: [0, -1, 0]`
+  lays the ribbon in the ground plane for a tyre mark or a wake.
+- **`tint` works**, and is the per-frame colour lever. On `Trail` it does
+  nothing at all, because the primitive batcher reads the draw colour and never
+  the tint. `setColor()` / `setGradient()` rebuild the gradient for a change of
+  state; they allocate, so they are not per-frame.
+
+  **If the colour is going to change, author the gradient WHITE.** `tint`
+  multiplies, so tinting a cyan ribbon red gives muddy brown rather than red. A
+  neutral gradient hands the hue entirely to the tint, which is what lets one
+  lever take a trail from white through to red as something overheats.
+- A post effect reaches it properly, where `Trail` has to force a screen
+  capture.
+- It is **cheaper**: one indexed draw call, against one filled path per segment.
+- `length` is fixed at construction, because the geometry is sized once.
+  Assigning `maxPoints` throws rather than silently truncating the ribbon, and
+  a `length` that is not a finite number throws at construction.
+- It needs a `Camera3d`. Under a 2D camera it draws nothing and warns once.
 
-- **`ParticleEmitter` with `referenceSpace: "world"`** — particles stay where
-  they were dropped while the emitter moves on, and the emitter propagates its
-  depth to each particle so `Camera3d` projects them correctly. This is the
-  built-in answer for exhaust, ski tracks and speed trails in 3D.
-- **A procedural `Mesh`** built from the object's recent path, with
-  `mesh.vertexColors` for a per-vertex gradient — more work, but a continuous
-  ribbon rather than discrete puffs.
+A world-space `ParticleEmitter` (`referenceSpace: "world"`) is still the right
+answer when you want discrete puffs rather than a continuous ribbon.
 
 ## Performance
 
@@ -123,12 +289,22 @@ tool for a trail behind an object moving *into* the scene. For that:
 
 | symptom | cause |
 |---|---|
-| trail looks flat under a `Camera3d` | `Trail` is 2D — use a world-space emitter or a ribbon mesh |
+| trail looks flat under a `Camera3d` | `Trail` is 2D; use `Trail3d` |
+| `Trail3d` draws nothing, with a console warning | it needs a `Camera3d`; the app's `cameraClass` is still the 2D default |
+| `trail.tint` does nothing | `Trail` cannot be tinted at all; `Trail3d` can |
+| assigning `maxPoints` throws | `Trail3d` sizes its geometry once; pass `length` to the constructor |
+| `Trail3d: \`length\` must be a finite number` | a computed `length` came out `NaN`; it is refused rather than silently rendering nothing |
 | emitter added but nothing appears | `streamParticles()` / `burstParticles()` never called |
 | the cloud follows a moving emitter | default `referenceSpace: "local"` — use `"world"` for trails |
 | particles do not travel far enough | settings tuned pre-20.2, when drawn travel was doubled |
 | one-shot emitters accumulate | missing `autoDestroyOnComplete: true` |
 | frame rate drops with many effects | an emitter per event instead of one re-aimed emitter |
+| a 3D burst is invisible under a `Camera3d` | before 20.8 a particle was culled at twice its depth; update |
+| the whole burst launches from one pixel | `width`/`height` are the spawn area and default to `1` |
+| the burst sits down-right of its source | the spawn area starts at the emitter's position; offset by half |
+| the middle of a burst goes white | additive sprites overlapping — `textureAdditive: false`, or spread them |
+| debris chunks look like squares | the default sprite is a filled square; pass your own `image` |
+| a ring tilts with the camera instead of staying on a surface | the launch axis is in WORLD axes, not the camera basis |
 
 ## Related skills
 

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
 ---
 
@@ -59,16 +59,28 @@ Anything spawned frequently — bullets, particles, pickups, damage numbers —
 should be pooled rather than allocated:
 
 ```js
-pool.register("bullet", Bullet, true);      // third arg = enable recycling
-const b = pool.pull("bullet", x, y);        // recycled: onResetEvent(x, y)
-                                            // fresh:    new Bullet(x, y)
-world.removeChild(b);                        // returns to the pool automatically
+import { createPool } from "melonjs";
+
+const bulletPool = createPool((x, y) => {
+    const instance = new Bullet(x, y);
+    return { instance, reset: (x, y) => instance.onResetEvent(x, y) };
+});
+
+const b = bulletPool.get(x, y);   // recycled: reset(x, y)
+                                  // fresh:    new Bullet(x, y)
+world.removeChild(b);             // returns to bulletPool automatically
 ```
 
-`register` also publishes the class as a Tiled object factory under that name,
-so an object with a matching class or name in a `.tmx` map instantiates it. Set
-`pool.autoRegisterTiled = false` around the call for classes that should stay
-programmatic.
+The container returns a child to whichever pool built it, so removal is enough;
+you only call `release()` yourself for something that was never added to the
+world.
+
+**`me.pool` is the older, string-keyed version and is deprecated since
+18.0.0.** `pool.register(name, Class, true)` / `pool.pull(name)` still work and
+print a one-off console notice, but a recycled object is no longer returned on
+removal, so pooling through it now costs an allocation per spawn. To register a
+class so a Tiled map can name it, use `registerTiledObjectClass` — that is a
+separate registry and is not deprecated.
 
 Two rules that cause subtle bugs when missed:
 
@@ -76,32 +88,89 @@ Two rules that cause subtle bugs when missed:
   alpha, tint, scale, animation, velocity. Anything you forget carries into the
   next use, which looks like a random visual glitch.
 - **Pooled objects do not fire `onDestroyEvent` on removal.** Removal always
-  calls `onDeactivateEvent`, then tries `pool.push`; only when that *fails* does
-  it fall through to `destroy()`, which is what calls `onDestroyEvent`. So a
-  successfully recycled object never sees it. Pair event subscriptions with
-  `onActivateEvent` / `onDeactivateEvent` instead, or you leak handlers.
-
-Engine classes are poolable too: `pool.pull("Tween", target)`. The canonical
-names are unprefixed — `Entity`, `Collectable`, `Trigger`, `Light2d`,
-`Particle`, `Sprite`, `NineSliceSprite`, `Renderable`, `Text`, `BitmapText`,
-`ImageLayer`, `Tween`, `ColorLayer`.
-
-`pool.register` additionally aliases every name under an `me.` prefix, pointing
-at the same entry, so `pool.pull("me.Tween")` resolves identically — and the
-same alias is registered with the Tiled object factory, which is why a map
+  calls `onDeactivateEvent`, then tries to return the object to the pool that
+  built it; only when nothing owns it does it fall through to `destroy()`,
+  which is what calls `onDestroyEvent`. So a 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.
+
+**The engine's own classes are NOT in this pool.** They were registered in it
+once, which bought nothing: most had recycling off, so `pool.pull("Sprite")`
+was a plain construction behind a string key. The ones worth recycling have
+typed pools instead, reached by key and fully typed:
+
+```js
+const tween = getPool("tween").get(target);
+const label = getPool("text").get(x, y, { font: "Arial", size: 12 });
+getPool("text").release(label);          // yours to release, as with particles
+```
+
+A recycled label comes back with its **base-class** state reset as well as its
+own: `floating`, `blendMode`, `alpha`, `tint`, the transform, the anchor, the
+behaviour flags, any mask and any post effect, and `depth` back to 0. The
+settings object names none of those, so set them again after `get()`. A pooled
+HUD number that is not re-marked `floating` is drawn through the camera, i.e.
+somewhere out in the world rather than on the screen, and `addChild(label, z)`
+is what gives it its depth back.
+
+`getPool` covers `vector2d`, `vector3d`, `point`, `matrix2d`, `matrix3d`,
+`bounds`, `color`, `polygon`, `line`, `rectangle`, `roundedRectangle`,
+`ellipse`, `tween`, `particle`, `text`, `colorLayer` and `bitmapTextData`.
+
+`pool.register` still aliases every name you give it under an `me.` prefix,
+pointing at the same entry, so `pool.pull("me.Bullet")` resolves identically —
+and the same alias reaches the Tiled object factory, which is why a map
 authored against melonJS 1.x still finds its classes. Prefer the unprefixed
 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 +300,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
@@ -453,7 +500,8 @@ onCollisionStart(response, other) {
 What actually happens per adapter:
 
 - **built-in** — callbacks fire inline during `step()`. `Container.removeChild`
-  is deferred, so it is safe; `removeChildNow()` and `destroy()` are immediate,
+  is deferred, so it is safe; `removeChildNow()`, and the internal `destroy()`
+  it calls, are immediate,
   and the detector only survives them because it re-checks `body === undefined`
   after every user callback.
 - **planck** — `onCollisionStart` / `onCollisionEnd` are dispatched from
@@ -496,50 +544,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 +772,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 |