melonjs 20.7.0 → 20.8.0

package/skills/melonjs-effects-and-shaders/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-effects-and-shaders
-description: "Use this skill for post-processing effects, custom shaders, blend modes and colour grading in melonJS. Covers the built-in ShaderEffect presets, addPostEffect on renderables and cameras, writing a custom dual-language GLSL/WGSL effect, the screen_texture builtins, and why effects silently do nothing on the Canvas fallback. Triggers on: ShaderEffect, addPostEffect, removePostEffect, getPostEffect, VignetteEffect, GlowEffect, BlurEffect, PixelateEffect, ScanlineEffect, shader, GLSL, WGSL, uniform, setUniform, setTexture, setTime, blendMode, colorMatrix, screen_texture, toFrameTexture, post effect, filter."
+description: "Use this skill for post-processing effects, custom shaders, blend modes and colour grading in melonJS. Covers the built-in ShaderEffect presets, addPostEffect on renderables and cameras, writing a custom dual-language GLSL/WGSL effect, the screen_texture builtins, and why effects silently do nothing on the Canvas fallback. Triggers on: Tween, easing, animate an effect, ShaderEffect, addPostEffect, removePostEffect, getPostEffect, postEffectNeedsCapture, VignetteEffect, GlowEffect, BlurEffect, PixelateEffect, ScanlineEffect, shader, GLSL, WGSL, uniform, setUniform, setTexture, setTime, blendMode, colorMatrix, screen_texture, toFrameTexture, post effect, filter."
 license: MIT
 ---
 
@@ -41,7 +41,7 @@ quad.scale(viewW / anyImage.width, viewH / anyImage.height);
 quad.floating = true;                 // its own uv is now screen space
 quad.blendMode = "additive";
 quad.addPostEffect(myEffect);
-world.addChild(quad, HUD_Z - 10);     // BELOW the labels, not above
+world.addChild(quad, HUD_Z - 10);     // 2D: below the labels. See the note.
 ```
 
 Two things follow from the quad filling the frame: its own `uv` is screen space
@@ -49,9 +49,47 @@ Two things follow from the quad filling the frame: its own `uv` is screen space
 and the incoming `color` is the quad's own texture, which a body that paints
 from scratch can ignore entirely.
 
-Depth here is easy to get backwards — a higher z draws **later**, i.e. on top.
-Verify it by returning a flat colour from the body for one frame: whatever it
-tints is what the pass covers.
+**Depth here is easy to get backwards, and the rule FLIPS between the two sort
+modes.** Under the default `sortOn = "z"` a higher z draws later, i.e. on top,
+so `HUD_Z - 10` puts the pass under the labels as written above. Under
+`sortOn = "depth"`, which every `Camera3d` scene sets, a floating child's sort
+key is `pos.z * pos.z` and the walk paints far to near, so the SMALLER
+magnitude is nearer and draws on top — `HUD_Z - 10` there puts the pass OVER
+the labels, the opposite of the comment.
+
+So in a 3D scene give the overlay a larger magnitude than the HUD, and give
+the HUD a small one (`melonjs-3d` and `melonjs-ui-and-text` both say a HUD
+wants a small depth, not the huge z that would put it on top in 2D).
+
+Either way, verify it rather than reasoning about it: return a flat colour from
+the body for one frame and see what it tints.
+
+## A renderable that draws with PRIMITIVES has to ask to be captured
+
+One effect is applied the cheap way: the renderable is drawn with the effect's
+own program instead of being captured offscreen and post-processed, which costs
+no render target. That is equivalent only when everything the renderable draws
+is a textured quad. `fillRect`, `strokeRect` and `renderer.fill(shape)` go
+through a batcher that never reads that shader, so **one** effect on such a
+renderable would silently do nothing, while **two** would work, because a chain
+always captures.
+
+So a renderable of your own that draws with primitives says so:
+
+```js
+class Bar extends Renderable {
+    constructor(x, y, w, h) {
+        super(x, y, w, h);
+        this.postEffectNeedsCapture = true;   // ← or one effect is a no-op
+    }
+    draw(renderer) {
+        renderer.fillRect(this.pos.x, this.pos.y, this.width, this.height);
+    }
+}
+```
+
+`ProgressBar` and `Trail` set it for you, and a sprite needs nothing: the flag
+defaults to `false` and only ever changes the single-effect case.
 
 ## Toggle with `enabled`, do not remove
 
@@ -72,13 +110,257 @@ reused across renderables.
 
 ## Built-in effects
 
-Eighteen presets, every one constructed as `new XEffect(renderer, options)` and
+Twenty-one presets, every one constructed as `new XEffect(renderer, options)` and
 every one shipping both a GLSL and a WGSL body, so they all run on either GPU
 backend: `VignetteEffect`, `ScanlineEffect` (optional CRT curvature),
-`GlowEffect`, `BlurEffect`, `PixelateEffect`, `ChromaticAberrationEffect`,
-`DropShadowEffect`, `FlashEffect`, `OutlineEffect`, `ColorMatrixEffect`,
-`DesaturateEffect`, `DissolveEffect`, `TintPulseEffect`, `WaveEffect`,
-`InvertEffect`, `SepiaEffect`, `HologramEffect`, `ShineEffect`.
+`BloomEffect`, `GlowEffect`, `BlurEffect`, `PixelateEffect`,
+`ChromaticAberrationEffect`, `DropShadowEffect`, `FlashEffect`,
+`OutlineEffect`, `ColorMatrixEffect`, `DesaturateEffect`, `DissolveEffect`,
+`TintPulseEffect`, `WaveEffect`, `InvertEffect`, `SepiaEffect`,
+`HologramEffect`, `ShineEffect`, `RadialGradientEffect`, `ToneMappingEffect`.
+
+`RadialGradientEffect` is a procedural soft spot: solid at the centre of its
+host quad, fading linearly to transparent at the edge, and elliptical for free
+on a non-square quad. It is the one to reach for instead of baking a disc into
+a canvas, for a pickup highlight, a trigger marker or a damage flash. Its
+falloff assumes the quad samples a FULL texture rect, so pair it with a
+standalone image or `Renderer.getWhitePixel()` rather than a sprite that draws
+a sub-region of an atlas, where the centre would land off-quad.
+
+**`BloomEffect` and `GlowEffect` are not the same thing**, and reaching for the
+wrong one is the usual disappointment here. `GlowEffect` draws a halo OUTSIDE a
+sprite's silhouette: its body returns the colour untouched wherever alpha is
+already non-zero, so on an opaque frame it returns early on every fragment and
+a camera-wide glow does nothing at all. `BloomEffect` is the screen bloom —
+bright pixels bleed into their neighbours — and it is the one to put on the
+camera:
+
+```js
+game.viewport.addPostEffect(new BloomEffect(app.renderer));
+// only the brightest highlights, with a wider halo
+game.viewport.addPostEffect(
+    new BloomEffect(app.renderer, { threshold: 0.85, radius: 4 }),
+);
+```
+
+Its tap offsets are in texels, so it takes its size from the renderer at
+construction; call `setTextureSize(w, h)` from an `event.ONRESIZE` handler, or
+when applying it to something smaller than the frame.
+
+**`ToneMappingEffect` goes after it, and goes last.** Bloom spreads the bright
+parts; the tone map is what stops the sum of the two clipping flat at white,
+which is the difference between an effect that reads as light and one that
+reads as a white sticker. `exposure` lifts the image into the curve, and the
+curve (`aces`, `reinhard` or `exponential`) is baked at construction:
+
+```js
+game.viewport.addPostEffect(new BloomEffect(app.renderer));
+game.viewport.addPostEffect(
+    new ToneMappingEffect(app.renderer, { exposure: 1.6 }),
+);
+```
+
+It is a grade, not a colour pipeline. By default melonJS renders into `RGBA8`
+everywhere, so the frame reaching it is already clamped and `exposure` past 1
+is what gives the curve range to compress.
+
+**`hdr: true` in the application settings changes that**: render targets
+become half-float, so the chain carries values above 1 instead of clamping at
+every write, and the bloom threshold starts discriminating genuinely
+over-bright pixels rather than merely bright ones. Off by default: it costs
+GPU memory on the camera's two render targets and depends on the driver.
+
+On its own it is **not HDR output**: the frame is still presented in SDR, so
+anything above 1 clamps on the final blit. What it buys is that nothing clamped
+BEFORE then. Removing that last clamp is a second, separate opt-in —
+`hdrOutput`, below — and it is WebGPU-only.
+
+```js
+const app = new Application(1024, 576, { hdr: true, … });
+// …and check what you actually got, since a driver can refuse it
+if (app.renderer.supportsHDR) { /* the chain now carries values above 1 */ }
+```
+
+Branch the GRADE on that flag, not just the feature. An exposure under 1 and a
+bloom threshold at 1 make sense only where values above 1 exist; applied to a
+chain that clamps, the same numbers tone map an already display-referred frame
+and switch the bloom off, which reads as a dark, flat picture rather than as a
+missing feature. Where there is no headroom, squeeze each emitter into range in
+its own shader instead and put the bloom threshold back under 1.
+
+**Nothing is added to your chain.** `hdr` is additive: the same frame, plus
+additive content that no longer saturates per write and a threshold that means
+something. Anything still above 1 at the end clamps on the blit, as it always
+did.
+
+A tone map is therefore a decision, not a consequence, and it is a bigger one
+than it looks. Every curve maps 1 to less than 1, so a 2D look built ON the
+clamp — clipped white specular, saturated neon — goes matte the moment you add
+one, at any exposure. Add one when your art is authored in linear light and you
+want the highlights rolled off; skip it when the clipping IS the look.
+
+It applies to the CAMERA chain only. A sprite's chain keeps 8-bit targets on
+purpose: its final blit composites with `ONE_MINUS_SRC_ALPHA`, and additive
+blending accumulates alpha past 1 in a float target, so that factor would go
+negative and subtract the backdrop.
+
+### Once it is on: putting values above 1 into the frame
+
+`hdr: true` on its own changes nothing visible. It removes a ceiling; something
+still has to reach for it. No single draw exceeds 1 on its own, so a game that
+turns the setting on and changes nothing else renders very nearly the frame it
+did before and looks like the feature is broken. The exception is worth knowing
+because it is free: additive content that already overlapped was being clipped
+at every write, and stops being.
+
+What produces over-bright pixels:
+
+```js
+// a built-in colour matrix, scaled past 1 — no custom shader needed
+sprite.addPostEffect(new ColorMatrixEffect(app.renderer).brightness(4));
+
+// in 3D, both of these were always unbounded; the 8-bit target was the only
+// thing destroying the range. `emissive` is a 3-component Float32Array, set
+// from the mesh settings or replaced wholesale — it is not a Color
+const mesh = new Mesh(x, y, { emissive: [2.5, 1.8, 0.4], /* … */ });
+light.intensity = 3;
+
+// and additive blending, which accumulates past 1 once the target can hold it
+sprite.blendMode = "additive";
+```
+
+**One effect, not two.** A renderable carrying exactly ONE post effect takes
+the renderer's `customShader` fast path: no offscreen target, and it draws
+straight into the camera's half-float target with its range intact. A chain of
+two or more is routed through a pooled intermediate that stays 8 bits per
+channel on purpose, so the energy is clamped there, before the camera ever sees
+it. Adding a second effect to an emitter is enough to silently undo its
+headroom.
+
+### Everything inside the camera is graded, including your UI
+
+The tone curve runs on the camera's whole frame. A `floating` HUD is still
+inside it, so a label authored at display white arrives at the curve as 1 and
+leaves at `1 - exp(-exposure)` — at exposure 0.45 that is 0.36, and the HUD
+comes out at roughly a third of its brightness for no reason the author can
+see.
+
+UI in an HDR chain has to be authored for that chain, exactly as the scene is:
+
+```js
+// drive the readout so the curve lands it back at display white. `shared`
+// keeps one instance across every element: it opts the effect out of the
+// per-renderable auto-destroy, so the first element torn down does not take
+// the program the others are still using
+const energy = new ColorMatrixEffect(app.renderer).brightness(2);
+energy.shared = true;
+for (const element of hudElements) element.addPostEffect(energy);
+```
+
+Put it on each ELEMENT, not on their container: `beginPostEffect` clears
+`customShader` for any renderable with no effects of its own, so a container's
+shader is thrown away by its first child. The alternative is to keep the UI out
+of the camera pass entirely, by overriding `Stage.draw` and drawing it after
+`super.draw(...)` — at the cost of the bloom that makes additive UI glow.
+
+The quad trick under *A camera effect covers the HUD too* does not help here.
+It works by hosting a pass BELOW the HUD's z, and a tone map cannot live there:
+it has to be the last thing before the blit to the 8-bit canvas, which is the
+camera. Anything the camera draws goes through it.
+
+Pick the multiplier by measuring against the no-headroom build, not by
+inverting the curve. Inverting it over-estimates, because additive UI is inside
+the BLOOM too and driving it harder also makes it spill wider into the same
+pixels.
+
+### `hdrOutput`: actually presenting in HDR, and what it costs you
+
+`hdr` gives the chain headroom and then throws it away at the very last step,
+because the surface the browser presents into is 8 bits per channel. Values
+above 1 clamp there, exactly as they did before the setting existed.
+`hdrOutput` changes that surface, so they reach the compositor instead:
+
+```js
+const app = new Application(1024, 576, { hdr: true, hdrOutput: true, … });
+if (app.renderer.supportsHDROutput) { /* the display is getting values above 1 */ }
+
+app.renderer.setHDROutput(false);   // and at runtime, for a settings screen
+```
+
+**It is WebGPU-only, and that is not a melonJS limitation.** The WebGPU
+specification defines a tone mapping mode on the canvas configuration, and two
+engines ship it. The WebGL2 equivalent needs a drawing-buffer tone mapping mode
+that is still an unapproved specification change with no implementation in any
+browser; the colour-space half of it exists in Chrome behind
+`--enable-experimental-web-platform-features`, which is not something you can
+ask a player to enable. So the WebGL2 backend reports `false`, warns once if
+you asked, and presents in SDR as it always has.
+
+That makes this the first setting where **the same machine answers differently
+depending on which backend `video.AUTO` picked**. Branch on
+`renderer.supportsHDROutput`, never on the setting.
+
+**It requires `hdr`** — the last pass blits from the camera's target, so if
+that target is 8 bits there is nothing above 1 left to present and the extra
+cost would buy an identical picture. Turning `hdr` off turns this off with it.
+
+**It changes how your game looks, on an HDR display.** Everything else here is
+careful not to: `hdr` is additive, the tone curve defaults to none. This one
+removes the final clamp, so anything you drove above 1 — an additive stack, an
+emitter, a `brightness()` above 1 — gets genuinely brighter rather than
+saturating at white. That is the point of it, and it is why it is a separate
+opt-in rather than part of `hdr`. Two consequences worth planning for:
+
+- a look built on clipped whites will not survive it unchanged, because the
+  clipping is what you were art-directing against
+- a tone curve and `hdrOutput` pull in opposite directions. A curve exists to
+  fit values into `[0, 1]`; if you have removed the clamp, either drop the
+  curve or give it a white point high enough to leave the top of the range
+  alone
+- **`"aces"` cannot produce HDR output.** Its expression clamps to `[0, 1]`
+  internally, so everything past the shoulder collapses to one value before
+  the white point scales it — different bright things come out equally bright.
+  Under `hdrOutput` use `"reinhard"` or `"exponential"`, which approach 1
+  asymptotically without clamping and so keep their ordering when the white
+  point lifts them past it, or use no curve at all
+
+**What it is not.** It does not make an SDR display brighter, and there is no
+way to ask melonJS how bright the panel is — `matchMedia("(dynamic-range:
+high)")` is the closest the platform gets. Calibrating in nits, the way a
+console settings screen does, is not reachable from the web platform today.
+
+### Exposure, and the runtime toggle
+
+Under `hdr` the useful exposure is often **below** 1, which surprises people who
+have only used the effect as an LDR grade. The curve has to work where it
+separates: at exposure 1 the ACES shoulder maps 2, 4 and 8 to 0.86, 0.96 and
+0.99, so genuinely different energies all arrive at white and the headroom buys
+nothing you can see. Lower exposure spreads them out. The right value is a
+property of how bright your scene is authored, so measure it; there is no
+default that is right for two different games.
+
+A tone curve is a setting rather than an effect you wire up:
+
+```js
+renderer.setToneMapping("aces", { exposure: 0.4, white: 6 });
+renderer.setToneMapping("none");                       // and off again
+```
+
+`"none"` by default. The renderer keeps the curve LAST on the camera, so
+whatever you put in front of it is mapped along with everything else. Changing
+the mode rebuilds one shader (the curve is baked); `exposure` and `white` are
+uniform writes, so a settings screen can drive them live. `white` is the value
+that comes out as display white — the knob a "brightness" or "peak" slider
+wants, since exposure alone drags the midtones up with the highlights.
+
+`renderer.setHDR(enable)` moves the whole pipeline at runtime, the way
+`setAntiAlias` does, for a settings toggle. It empties the render-target pool
+when the format actually changes, so it is not something to drive per frame.
+The boot header reports what happened either way:
+
+```
+resolution: requested 1024x576 (HDR), got 1024x576 (SDR)   ← the driver refused
+```
 
 For grading without writing a shader yourself, the camera has a colour matrix:
 
@@ -108,6 +390,23 @@ one `@group(3) @binding(0) var<uniform>` struct — so a single `setUniform` cal
 feeds whichever backend is live. `setTime` is a convenience for a `uTime`
 uniform and silently does nothing if the shader does not declare one.
 
+**Never put a backtick in a shader body, including in its comments.** An inline
+body is a JavaScript template literal, so a backtick ENDS it — and what follows
+is parsed as code, which fails somewhere further down the file with an error
+that says nothing about shaders:
+
+```js
+const glsl = `
+// x * x, not `pow(x, 2.0)`: the base goes negative here   <-- ends the literal
+vec4 apply(vec4 color, vec2 uv) { ... }
+`;
+```
+
+Markdown-quoting an identifier is a reflex when writing a comment, and this is
+the one place it breaks the file. Write `pow(x, 2.0)` bare. A body loaded from
+a `.glsl` / `.wgsl` file has no such problem, which is one more reason to move
+a shader out once it stops being a sketch.
+
 ### One effect is one program — prefer preloading, and share
 
 A `ShaderEffect` compiles and links in its **constructor**, and the link is
@@ -201,28 +500,38 @@ Two places where a straight port really does differ:
   uniform (initialise it to `1.0`) and multiply vertical offsets by it; the
   renderer feeds `-1` on that path and `+1` everywhere else.
 
-## A ShaderEffect cannot shade a mesh on WebGPU
+## A ShaderEffect on a mesh is a colour hook, and drops some builtins
 
-The single-effect fast path swaps the renderable's program outright instead of
-rendering through an offscreen target. On WebGL that works for a `Mesh` too, so
-a custom mesh shader is a `ShaderEffect` away. **On WebGPU it does not** — the
-renderer says so in its own source, warns once, and then keeps the built-in
-mesh shading.
+`mesh.addPostEffect(fx)` shades a `Mesh` on **both** backends since 20.5. The
+body is spliced into the engine's own mesh shader as a colour hook, so the mesh
+keeps its placement, alpha cutout, lighting and fog, and `setUniform` /
+`setTime` drive it exactly as they do over a sprite. Uniform-only bodies are
+the supported case and they are most of them.
 
-Nothing throws. The mesh simply draws with its plain texture, which looks like
-a broken shader, a bad binding, or a texture that failed to load — and since
-`video.AUTO` prefers WebGPU where it is available, this is the default outcome
-on most desktops. It cost several hours here: the symptom was a water surface
-rendering flat white, and alpha, bindings, transparency and lighting were all
-eliminated before the backend was.
+Five things the quad tier gives an effect that the mesh tier does not, each
+refused rather than half-working:
 
-2D renderables are unaffected: `Sprite`, `Text` and the rest go through the
-quad path, which hosts effects on both backends. So a gradient fill for text,
-or a refraction over a sprite, is fine — it is specifically the mesh path.
-
-If you need a genuinely custom mesh shader that runs everywhere, supply a full
-dual-language `GLShader` rather than a fragment body, and declare the fog
-uniforms yourself (see `melonjs-3d`).
+| refused | why |
+|---|---|
+| its own `setTexture` samplers | resolved by the quad tier's per-effect device state; refused on both backends |
+| `screen_texture`, `screen_uv` | need the screen capture only the quad tier takes |
+| `noise_uv` | derived from a quad's image and object size |
+| `vColor`, on WGSL only | the WGSL mesh module has no module-scope equivalent; the GLSL one declares it, so GLSL is fine |
+| `InstancedMesh` | the instanced WGSL builder drops everything between the two stages |
+
+Hitting one warns **once** and falls back to the built-in shading. Nothing
+throws, so the symptom is a mesh drawing with its plain texture, which reads as
+a broken shader, a bad binding or a texture that failed to load. Check the
+console for the warning before you start eliminating alpha, bindings and
+transparency: it names which of the five it was.
+
+2D renderables never hit this. `Sprite`, `Text` and the rest go through the
+quad path, which has the full feature set, so a gradient fill for text or a
+refraction over a sprite is fine.
+
+If you need one of the five on a mesh, supply a full dual-language `GLShader`
+rather than a fragment body, and declare the fog uniforms yourself (see
+`melonjs-3d`).
 
 ## Extra textures bind in setTexture order
 
@@ -294,13 +603,16 @@ same question after construction.
 | effect does nothing, warning in console | Canvas fallback — no programmable pipeline |
 | effect does nothing on some machines only | GLSL-only shader, `video.AUTO` chose WebGPU |
 | a white or solid box where the effect should be | carrier renderable drawn while the effect is disabled |
+| ONE effect does nothing but two of them work | the renderable draws with primitives — set `postEffectNeedsCapture` |
 | effect cannot be re-enabled | `removePostEffect()` destroyed it — use `enabled` |
 | ported shader renders upside down | a hand-bound `toFrameTexture()` capture — GL is bottom-up, WebGPU top-down |
 | shadow/smear offset flips on some draws | vertical UV offset not multiplied by `uUVYDir` |
 | frame rate collapses with many blended sprites | an *advanced* mode (overlay, darken, …) — each draw is a capture plus a composite |
 | animated shader never moves | `setTime` fed milliseconds, or the shader declares no `uTime` |
+| syntax error in a file whose shader you just edited, pointing at a line of GLSL | a backtick in the shader body ended the template literal — most often one wrapped around an identifier in a comment |
 
 ## Related skills
+- `melonjs-scenes-and-state` — `Tween` and the easing families, for animating any of this
 
 - `melonjs-renderables` — where post effects attach, and the destroy trap
 - `melonjs-3d` — the GPU-backend requirement, and why a custom mesh shader is

package/skills/melonjs-input/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-input
-description: "Use this skill for keyboard, pointer, mouse, touch and gamepad input in melonJS. Covers the bindKey action indirection, registerPointerEvent on regions, the isKinematic requirement that silently blocks pointer events, world vs screen pointer coordinates, and gamepad mapping onto the same actions. Triggers on: input, bindKey, isKeyPressed, KEY, registerPointerEvent, releasePointerEvent, pointerdown, pointerup, POINTERMOVE, gamepad, bindGamepad, triggerKeyEvent, click, touch, drag."
+description: "Use this skill for keyboard, pointer, mouse, touch and gamepad input in melonJS. Covers the bindKey action indirection, registerPointerEvent on regions, the isKinematic requirement that silently blocks pointer events, which of several overlapping objects receives an event and how to consume it, world vs screen pointer coordinates, and gamepad mapping onto the same actions. Triggers on: input, bindKey, isKeyPressed, KEY, registerPointerEvent, releasePointerEvent, pointerdown, pointerup, pointermove, POINTERMOVE, gamepad, bindGamepad, triggerKeyEvent, click, touch, drag, hit test, event propagation, stop propagating, overlapping, which object gets the click."
 license: MIT
 ---
 
@@ -64,9 +64,11 @@ subclasses with no body are the ones that catch people.
 Register in `onActivateEvent` and release in `onDeactivateEvent`, not in the
 constructor — pooled objects are reused and would otherwise accumulate handlers.
 
-`app.viewport` works as a whole-screen region when you want global clicks: the
-dispatcher appends it to the candidate list on every event, so it is reachable
-even when nothing else is under the pointer.
+`app.viewport` works as a whole-screen region when you want global clicks. Note
+it is asked **before** everything else, not as a fallback after nothing matched:
+the dispatcher appends it to the candidate list and walks that list from the
+end. So a viewport handler must not return `false` unless it really means to
+swallow every pointer event in the game.
 
 The accepted event names are exactly `"pointerdown"`, `"pointerup"`,
 `"pointermove"`, `"pointercancel"`, `"pointerenter"`, `"pointerover"`,
@@ -76,6 +78,44 @@ throw `invalid event type`. melonJS maps the canonical name onto whichever
 mouse/touch events the device actually supports, so you always register the
 pointer name.
 
+## Which object gets the event
+
+The dispatcher collects the regions near the pointer from the broadphase,
+bounds-checks each one, orders them **the way they are drawn** and asks the
+topmost first, walking down until something consumes.
+
+A handler consumes by returning `false`. This is the DOM sense and it reads
+backwards: `false` means handled, and anything else, `undefined` included, lets
+the walk carry on to whatever is underneath.
+
+```js
+input.registerPointerEvent("pointerdown", this, () => {
+    this.fire();
+    return false;        // nothing under this gets the click
+});
+```
+
+Three things decide the order, and only the first is obvious:
+
+- **`pos.z`, among siblings of one container.** Higher is on top.
+- **Across containers, the common ancestor decides.** `pos.z` is
+  container-local, since `autoDepth` numbers each container's children from 1,
+  so a button at `z = 8` inside one panel does not outrank a second panel at
+  `z = 2`. The pair is resolved by walking both up to their shared parent and
+  comparing the two siblings there, which is exactly how drawing resolves it.
+  Raise a whole panel with `ancestor.moveToTop(panel)`, not by inflating a
+  child's `z`.
+- **A child is asked before the container holding it**, since it draws over it.
+
+Equal `z` between siblings falls back to child order, lower index on top. Two
+callbacks registered on the **same** region for the same event run
+last-registered-first.
+
+Consuming a **move** also takes the pointer away from the regions below: each
+one still holding it gets its `pointerleave`, because it is covered now and
+being inside its own bounds no longer decides. Consuming a press, a release or a
+wheel does not, since none of those says where the pointer is.
+
 ## World coordinates versus screen coordinates
 
 The pointer carries several, and picking the wrong one produces a feedback loop:
@@ -159,6 +199,10 @@ input.triggerKeyEvent(input.KEY.LEFT, false);   // release
 | jump fires every frame while held | `bindKey` without its third `lock` argument |
 | `invalid event type` thrown at registration | non-pointer name (`"click"`, `"mousedown"`, …) passed to `registerPointerEvent` |
 | `no action defined for keycode N` | `bindGamepad` called before `bindKey` for that keycode |
+| a widget under an overlapping panel still reacts | the panel consumes nothing — return `false` from its `onClick` and `onOver` |
+| a widget stays highlighted after the pointer moves onto a panel over it | the panel consumes no `pointermove`, so nothing takes the pointer off the widget |
+| a child's big `z` does not put it in front of another container | `pos.z` is container-local — use `ancestor.moveToTop()` on the container |
+| every click in the game stops working | a handler on `app.viewport` returning `false`, which is asked first |
 
 ## Related skills
 

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: ParticleEmitter, particles, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter."
 license: MIT
 ---
 
@@ -28,6 +28,101 @@ emitter.burstParticles();      // one shot
 `duration` setting, which defaults to `Infinity` — a stream runs until
 `stopStream()`. `burstParticles(n)` launches `n`, or `totalParticles`.
 
+## 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.
@@ -95,9 +190,10 @@ 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:
 
 - **`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.
+  they were dropped while the emitter moves on, and each one sits at the
+  emitter's depth slice so `Camera3d` projects it correctly. Add an `elevation`
+  and they recede as well. 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.
@@ -129,6 +225,12 @@ tool for a trail behind an object moving *into* the scene. For that:
 | 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