melonjs 20.6.0 → 20.8.0

package/skills/melonjs-camera-and-drawing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-camera-and-drawing
-description: "Use this skill for camera control and immediate-mode drawing in melonJS — following a target, viewport bounds, shake and fade, secondary cameras, and drawing shapes, lines and gradients inside a custom draw(). Covers world versus screen coordinate conversion, clipping and masking, and baking with CanvasRenderTarget. Triggers on: Camera2d, viewport, follow, setBounds, shake, fadeIn, fadeOut, worldToLocal, localToWorld, colorMatrix, renderer.fill, renderer.stroke, Rect, Ellipse, Polygon, Line, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d."
+description: "Use this skill for camera control and immediate-mode drawing in melonJS — following a target, viewport bounds, shake and fade, secondary cameras, and drawing shapes, lines and gradients inside a custom draw(). Covers world versus screen coordinate conversion, clipping and masking, and baking with CanvasRenderTarget. Triggers on: Camera2d, viewport, follow, setBounds, shake, fadeIn, fadeOut, worldToLocal, localToWorld, colorMatrix, renderer.fill, renderer.stroke, Rect, Ellipse, Polygon, Line, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d, lookAt, setBasis."
 license: MIT
 ---
 
@@ -24,6 +24,25 @@ frame-rate independent since 19.7. `AXIS.HORIZONTAL` / `AXIS.VERTICAL` /
 
 Call it from the followed entity's `onActivateEvent`, using `this.parentApp`.
 
+**For anything that is NOT the camera, the same smoothing is `math.damp`.**
+`follow()` is frame-rate independent for you; a value you smooth yourself is
+not, and `lerp(current, target, alpha)` once per frame moves further on a slow
+frame than on a fast one, so the feel changes with the frame rate:
+
+```js
+import { math } from "melonjs";
+
+// dt is milliseconds, damp wants seconds
+this.speed = math.damp(this.speed, targetSpeed, 5, dt / 1000);
+this.turret.angle = math.damp(this.turret.angle, wanted, 8, dt / 1000);
+```
+
+`damp(current, target, lambda, dt)`. Higher `lambda` converges faster; it is
+the rate, not a per-frame fraction. Use it for camera pans you drive yourself,
+turret tracking, zoom, input smoothing and any value that should chase another
+one — it is the tool that is easy to miss and easy to hand-write slightly
+wrong.
+
 ## Bounds are the thing people forget
 
 The camera's bounds default to the **renderer size**, so it cannot scroll until
@@ -102,6 +121,24 @@ coordinate that puts your label on the wrong side of the screen. Skip it.
 Do not hand-roll this with `Matrix3d` — the perspective divide and the behind-
 camera case are exactly what gets it wrong.
 
+## Pointing a 3D camera
+
+A 2D camera's only rotation is `roll`. A 3D one can be pointed at a target, and
+optionally banked at the same time:
+
+```js
+camera.lookAt(target);                  // pitch and yaw; roll untouched
+camera.lookAt(target, up);              // and bank, where `up` is what should
+                                        // appear UP ON SCREEN
+camera.setBasis(right, up, forward);    // or pose it from a basis outright
+```
+
+`up` has no default, so the one-argument form behaves exactly as it always
+did. Because this engine renders Y-down, a level horizon is `(0, -1, 0)`.
+`setBasis` is the writable counterpart of `getBasis` and takes the camera's
+own columns, whose `up` points down the screen: the opposite sense, one
+negation apart. See `melonjs-3d` for the full account.
+
 ## Secondary cameras
 
 Cameras are first-class — a minimap is a second camera with `autoResize = false`
@@ -195,6 +232,24 @@ hand `.canvas` on for exactly that reason.
 
 This is the sanctioned performance idiom before reaching for a custom shader.
 
+**For a solid fill you do not need a canvas at all.** `Renderer.getWhitePixel()`
+is a shared, lazily-created 1x1 white canvas, and stretching it is how you get
+a coloured rectangle, a bar, a flat screen overlay, or a blank carrier for an
+effect that paints from scratch:
+
+```js
+const bar = new Sprite(0, 0, { image: Renderer.getWhitePixel() });
+bar.anchorPoint.set(0, 0);
+bar.tint.parseCSS("#39d0ff");
+bar.scale(width, height);     // a 1x1 texture, so scale IS the size in pixels
+```
+
+It is also the right texture under a `ShaderEffect` whose body ignores the
+incoming colour, and it keeps the quad batched with everything else using it.
+When you DO need a real canvas, `Renderer.createCanvas(width, height)` is the
+engine's allocator: it hands back an `OffscreenCanvas` where that is safe and
+throws on a zero dimension, instead of `document.createElement("canvas")`.
+
 `renderer.toFrameTexture()` is the related tool for capturing the *current frame*
 into a texture for a shader to sample.
 
@@ -213,6 +268,7 @@ into a texture for a shader to sample.
 | `container.clipping = true` does nothing | container has no explicit size, so `width`/`height` are `Infinity` |
 | baked target draws nothing / throws | passed the `CanvasRenderTarget`, not its `.canvas` |
 | frame rate drops with many static draws | bake into a `CanvasRenderTarget` instead |
+| a 3D camera cannot be given an arbitrary up | `Camera3d#lookAt(target, up)` or `setBasis(right, up, forward)`; see `melonjs-3d` |
 
 ## Related skills
 

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-lighting/SKILL.md

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