melonjs 20.8.0 → 20.10.0

package/skills/melonjs-display-and-scaling/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: melonjs-display-and-scaling
+description: "Use this skill when a melonJS game looks blurry, soft, shimmering or cropped, or when choosing how the canvas fills its page. Covers the design resolution, scale and scaleMethod, scaleTarget, scaleRounding for pixel-perfect integer scaling, antiAlias, textureFilter, subPixel, devicePixelRatio, and which setting does which job. Triggers on: blurry, soft, fuzzy, shimmering, pixel art, pixel perfect, crisp, nearest, linear, scale, scaleMethod, scaleTarget, scaleRounding, integer scaling, antiAlias, textureFilter, subPixel, devicePixelRatio, retina, hidpi, design resolution, canvas size, canvas cropped, letterbox, image-rendering, upscale, resolution."
+license: MIT
+---
+
+# Display and scaling
+
+Seven settings decide how a game looks on screen, and they are easy to get
+individually right and collectively wrong. This is what each one actually
+does, and which one to reach for.
+
+## The four jobs
+
+A pixel travels from your source art to a physical pixel through four
+separate decisions. Knowing which setting owns which is most of the work.
+
+| job | setting | what it decides |
+|---|---|---|
+| how big the frame is drawn | `width`/`height` on `Application` | the design resolution everything is authored against |
+| how it uses the space | `scale`, `scaleMethod`, `scaleTarget` | fit, fill, stretch, and what it measures to decide |
+| may the factor be fractional | `scaleRounding` | whole device pixels per source pixel, or any factor |
+| how a texture is sampled | `antiAlias`, `textureFilter` | nearest or linear, and the CSS upscale filter |
+
+`subPixel` is a fifth, orthogonal to all of them: it decides whether a
+renderable may sit on a fractional position WITHIN the frame.
+
+## Design resolution
+
+```js
+const app = new Application(480, 270, { scale: "auto" });
+```
+
+The game is drawn at 480x270 whatever the window is, and the canvas is scaled
+to the container. Everything in world coordinates is in those units. This is
+the usual arrangement: author once, scale to whatever you are given.
+
+## `scale` and `scaleMethod`
+
+`scale: "auto"` turns on automatic scaling; a number is a fixed multiplier and
+`scaleMethod` is then ignored.
+
+`scaleMethod` decides how the available space is used:
+
+- **`"fit"`** keeps the design resolution and the aspect ratio, scaling to the
+  largest factor that fits. Leftover space becomes margin. This is the one to
+  use when the game is authored for a fixed frame.
+- **`"fill-min"` / `"fill-max"`** keep the aspect ratio but RESIZE the
+  renderer, so the design resolution changes with the window and the game sees
+  more or less of the world.
+- **`"flex"`, `"flex-width"`, `"flex-height"`** resize the renderer on one or
+  both axes.
+- **`"stretch"`** scales each axis independently, so the aspect ratio is not
+  preserved and circles become ovals.
+- **`"manual"`** does nothing automatic.
+
+The distinction that matters: **`fit` scales a fixed frame; everything else
+changes how much of the world is visible.** A game whose layout assumes a
+known frame wants `fit`.
+
+## `scaleTarget`: what gets measured
+
+Automatic scaling measures **the parent of the element the canvas is mounted
+in**, not the element itself. If that grandparent is not the box you meant,
+the canvas is sized wrongly, and the failure is quiet.
+
+The case that bites: a canvas container that is `position: fixed` or
+`absolute` contributes no height to its parent, so the parent measures only
+whatever else is in it. If that parent is `<body>`, the engine falls back to
+the window size and the canvas ends up larger than the box it lives in,
+cropped by whatever sits above it.
+
+```js
+new Application(1024, 576, {
+	parent: "screen",
+	scale: "auto",
+	// measure THIS, rather than guessing from the DOM shape
+	scaleTarget: document.getElementById("stage"),
+});
+```
+
+Either name the element with `scaleTarget`, or give the canvas container a
+parent whose box is the area you want filled. If the canvas is cropped or
+overflows on resize, this is the first thing to check.
+
+## `scaleRounding`: whole device pixels
+
+```js
+new Application(480, 270, {
+	scale: "auto",
+	scaleMethod: "fit",
+	scaleRounding: "integer",   // default "fractional"
+});
+```
+
+`"fractional"` fills the container exactly, at whatever factor that takes. A
+480 wide design in a 1280 wide container is scaled by 2.667, so some source
+pixels cover three screen pixels and some cover two. Pixel art shows this as
+uneven glyph stems and shimmering edges, and browsers resolve the unevenness
+differently, so the same scene can look crisp in one and soft in another.
+
+`"integer"` rounds the factor DOWN so every source pixel covers the same whole
+number of device pixels, and letterboxes with the space left over. That trade,
+crisp pixels for black bars, is the whole decision.
+
+### What it costs
+
+More than "some letterboxing", and the size of it is decided by
+`devicePixelRatio` as much as by the window. A higher ratio has more device
+pixels to round among, so it lands closer to the factor it wanted. For a
+480x270 design, which is exactly a quarter of 1920x1080:
+
+| container | ratio | fit | integer | presented | area lost |
+|---|---|---|---|---|---|
+| 1920x1080 | 1 or 2 | 4.000 | 4 / 8 | 1920x1080 | none |
+| 1440x810 | 1 | 3.000 | 3 | 1440x810 | none |
+| 960x540 | 1 | 2.000 | 2 | 960x540 | none |
+| 1280x720 | 2 | 2.667 | 5 | 1200x675 | 12% |
+| 2560x1440 | 2 | 5.333 | 10 | 2400x1350 | 12% |
+| 1280x720 | 1 | 2.667 | 2 | 960x540 | **44%** |
+| 1366x768 | 1 | 2.844 | 2 | 960x540 | **51%** |
+
+So the decision is mostly made when the design resolution is chosen, not when
+this setting is. One that divides the sizes you expect costs nothing; one that
+does not can give up half the screen on a 1x display, and 1366x768 laptops are
+not rare. A game that must fill the window on any machine should stay
+fractional and accept the uneven pixels.
+
+Two things to know:
+
+- It applies to **`scaleMethod: "fit"` only.** Every other method resizes the
+  renderer to the container, so the design resolution moves and there is no
+  fixed factor to round.
+- The rounding happens in **device** pixels. `devicePixelRatio` multiplies the
+  CSS size on the way to real pixels, so rounding the CSS factor would let the
+  fraction straight back in: a factor of 2 at a ratio of 1.25 is 2.5 device
+  pixels per source pixel.
+
+## `antiAlias` does three things
+
+This is the setting most likely to surprise, because it is not one switch:
+
+1. the texture filter, but only while `textureFilter` is `"auto"` (the
+   default), which TRACKS it: linear when on, nearest when off. Setting
+   `textureFilter` explicitly decouples the two
+2. `imageSmoothingEnabled` on the 2D context
+3. the canvas CSS `image-rendering`: `pixelated` when off, `auto` when on
+
+So `antiAlias: false` gives hard-edged textures AND a hard-edged upscale of
+the whole frame. That is usually what a pixel-art game wants, and usually NOT
+what a smooth 3D scene wants, because it also disables MSAA.
+
+`textureFilter: "nearest" | "linear"` separates the texture half, so a scene
+can have smooth model edges and nearest-sampled sprites. The presentation half
+is not separable: there is no way to get MSAA silhouettes and a hard-edged
+upscale at the same time.
+
+## `subPixel` is about position, not scale
+
+`subPixel: false` (the default) truncates a renderable's translation to whole
+pixels inside the frame. It is `|0`, so it truncates **toward zero** rather
+than rounding, which is worth knowing when something travels a short distance:
+an offset that should swing between -3 and +3 lands on -2 and +2, and parks at
+the extremes for longer than it should.
+
+It does nothing about how the frame reaches the screen. A game that carefully
+snaps positions and is then scaled by 2.667 has thrown that work away at the
+last step, which is the contradiction `scaleRounding: "integer"` exists to
+resolve.
+
+## Soft text next to crisp sprites
+
+If everything is crisp EXCEPT the text, the scale factor is not the cause: a
+fractional factor softens the whole frame equally. The text is different
+because of how it is made.
+
+`Text` draws through the browser's `fillText`, which anti-aliases glyph edges
+into partial-alpha pixels. Measured on one label at 16px: **171 distinct
+partial alpha levels**. Nothing in the canvas API turns that off. `antiAlias`
+and the `imageSmoothingEnabled` that `CanvasRenderTarget` sets govern IMAGE
+drawing, not glyph rasterisation.
+
+So the label arrives already soft, and the upscale then magnifies each grey
+edge pixel into a grey block, sitting beside sprites that were hard-edged to
+begin with and stay hard-edged under nearest sampling.
+
+It also explains the same scene looking crisp in one browser and soft in
+another at identical size and settings: engines use different font
+rasterisers, with different hinting and anti-aliasing, so they bake DIFFERENT
+textures from the same font at the same size.
+
+**Use `BitmapText` for a game that upscales.** A pixel-font atlas is
+hard-edged source art like every other texture, so it survives magnification
+the way the sprites do. Raising the design resolution only shrinks the
+magnification of anti-aliasing that is still there, so it softens the symptom
+rather than removing it, and `scaleRounding` does nothing for this at all.
+
+Keep `Text` where the frame is not upscaled much, or where the label is meant
+to look smooth.
+
+### Baking an atlas from a face you already use
+
+Swapping in a bitmap face means generating one, and three things decide
+whether it comes out looking like the original:
+
+- **Threshold the coverage.** Hard edges are the whole point, so every pixel
+  has to end up fully on or fully off. Hardening only the ALPHA is not enough:
+  an outlined glyph keeps a soft stroke-to-fill blend INSIDE the silhouette,
+  which still reads as blur once magnified. Pick the colours from a mask.
+- **Bake each size at that size, and draw it at a ratio of 1.** `size` on
+  `BitmapText` is a ratio of the authored size, and a bitmap face has the sizes
+  it was baked at. Doubling a smaller atlas halves the detail; a ratio below 1
+  drops whole stems; a fractional ratio resamples hard pixels unevenly. One
+  atlas per step of the type scale.
+- **Grow the outline outward, but carve it INWARD around a counter.** This is
+  the one that costs the most time. A stroke drawn by the canvas is centred on
+  the contour, so around an enclosed hole it eats into the letter and the hole
+  keeps its size. Dilating a mask outward instead grows black INTO the hole
+  from every side, which closes anything under about 3px: the letter loses its
+  counter and reads as a blob. Take the rim from the fill side and the hole
+  survives at every size. Neither leaving holes unrimmed nor closing the small
+  ones is a substitute — both were tried and both look wrong.
+
+Two traps in the generator itself:
+
+- A face whose glyphs overshoot the `textBaseline` origin is clipped by a tight
+  cell, and the symptom is an outline that goes missing along one edge of some
+  glyphs. Pad the cell by a fraction of the size, and assert that no glyph's
+  ink reaches its border.
+- The threshold decides the TOPOLOGY, not just the weight. A notch or a narrow
+  gap in a letterform closes over at a full threshold and becomes an isolated
+  hole, which then bakes as a black blob sitting on the glyph. Thinner, the
+  same feature stays joined to the background and reads as the face intends.
+  So a small size may want a thinner fill than a large one, and the way to see
+  it is to magnify one glyph, not a whole line.
+
+## A pixel-art setup
+
+```js
+const app = new Application(480, 270, {
+	scale: "auto",
+	scaleMethod: "fit",
+	scaleRounding: "integer",   // whole device pixels, letterbox the rest
+	antiAlias: false,           // nearest textures, hard-edged upscale
+	// subPixel: false is already the default
+});
+```
+
+## A smooth 3D setup
+
+```js
+const app = new Application(1024, 576, {
+	scale: "auto",
+	scaleMethod: "fit",
+	antiAlias: true,            // MSAA and a filtered upscale
+	textureFilter: "nearest",   // but keep blocky textures if the art is blocky
+});
+```
+
+## Symptoms
+
+| symptom | cause |
+|---|---|
+| pixel art is blurry or shimmers | the frame is upscaled by a fractional factor; set `scaleRounding: "integer"` |
+| crisp in one browser, soft in another | the same fractional factor, which engines distribute differently under `pixelated` |
+| the canvas is cropped or overflows its box | automatic scaling measured the wrong element; name it with `scaleTarget` |
+| the canvas grows on every resize | the measured ancestor is auto-sized around the canvas itself |
+| things shimmer as they move | fractional positions; check `subPixel`, and that the scale factor is whole |
+| 3D model edges are jagged | `antiAlias: false` also disables MSAA; turn it on and use `textureFilter` for textures |
+| textures are smoothed when they should be blocky | `antiAlias: true` makes the default texture filter linear; set `textureFilter: "nearest"` |
+| `scaleRounding: "integer"` changes nothing | it applies to `scaleMethod: "fit"` only; the others resize the renderer |
+| text is soft but sprites are crisp | the glyphs were anti-aliased when `Text` baked them; use `BitmapText` (see below) |
+| the game shows more world on a bigger window | that is `fill-*` or `flex-*` doing their job; use `"fit"` to keep a fixed frame |

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

@@ -110,14 +110,15 @@ reused across renderables.
 
 ## Built-in effects
 
-Twenty-one presets, every one constructed as `new XEffect(renderer, options)` and
+Twenty-two 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),
 `BloomEffect`, `GlowEffect`, `BlurEffect`, `PixelateEffect`,
 `ChromaticAberrationEffect`, `DropShadowEffect`, `FlashEffect`,
 `OutlineEffect`, `ColorMatrixEffect`, `DesaturateEffect`, `DissolveEffect`,
 `TintPulseEffect`, `WaveEffect`, `InvertEffect`, `SepiaEffect`,
-`HologramEffect`, `ShineEffect`, `RadialGradientEffect`, `ToneMappingEffect`.
+`HologramEffect`, `ShineEffect`, `RadialGradientEffect`, `SquishEffect`,
+`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
@@ -127,6 +128,40 @@ 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.
 
+`SquishEffect` bulges a sprite's middle out (`setBulge(0.3)`) or pinches it in
+(`setBulge(-0.3)`), its top and bottom rows staying put. Bulging out widens the
+sprite past its own frame, and the effect draws on a wider quad to make room,
+so the art needs no transparent margin. On its own it is a jelly wobble; paired
+with a change of height it is **squash and stretch that keeps the volume**:
+scale the sprite to `scaleY` of its height about its feet and set the bulge to
+`1 - scaleY`, so a stretched sprite pinches in and a squashed one bulges out.
+Ease `scaleY` back to 1 with a short `Tween.Easing.Back.Out`; an elastic ease
+keeps it trembling long after the landing.
+
+```js
+const squish = new SquishEffect(app.renderer);
+player.addPostEffect(squish);
+// every frame, from the player's update()
+const feet = player.height * (1 - player.anchorPoint.y);
+player.currentTransform
+    .identity()
+    .translate(0, feet)
+    .scale(1, scaleY)
+    .translate(0, -feet);
+squish.setBulge(1 - scaleY);
+```
+
+Apply that from the sprite's own `update()`, not from a tween's `onUpdate`. A
+physics adapter that mirrors a body's angle (Matter does) rewrites
+`currentTransform` on every step, before the renderables update, so a scale set
+anywhere else is gone by the time the sprite is drawn. Let the tween animate a
+plain `{ scaleY }` object and read it in `update()`.
+
+It is made for a sprite carrying it as its only effect: chained with another,
+or on the camera, the frame it measures against is the whole capture, so it
+squishes the whole frame. The bulge is outside the sprite's bounds, so culling
+and pointer events ignore it.
+
 **`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
@@ -136,9 +171,9 @@ bright pixels bleed into their neighbours — and it is the one to put on the
 camera:
 
 ```js
-game.viewport.addPostEffect(new BloomEffect(app.renderer));
+app.viewport.addPostEffect(new BloomEffect(app.renderer));
 // only the brightest highlights, with a wider halo
-game.viewport.addPostEffect(
+app.viewport.addPostEffect(
     new BloomEffect(app.renderer, { threshold: 0.85, radius: 4 }),
 );
 ```
@@ -154,8 +189,8 @@ 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(
+app.viewport.addPostEffect(new BloomEffect(app.renderer));
+app.viewport.addPostEffect(
     new ToneMappingEffect(app.renderer, { exposure: 1.6 }),
 );
 ```
@@ -453,8 +488,15 @@ With `prewarm` on (the default since 20.6), `loader.preload()` warms on its way
 through — automatically, on every call — and compiles the GPU-side objects for
 every shader it holds — on WebGPU that is the
 WGSL module, which is otherwise built inside the draw path the first time the
-effect is used. Effects constructed inline are not in the loader, so nothing can
-bring them forward.
+effect is used.
+
+Since 20.10 the rest is warmed when the effect is **attached**, inline effects
+included: `addPostEffect` (or assigning `shader`) compiles the pipelines that
+effect will draw with on that renderable — on WebGPU the costly part, keyed by
+the renderable's blend mode and target as well as the shader — and on WebGL
+links the spliced program when the host is a mesh. It finishes off the frame,
+so attach when you build (a pool, a stage starting), not when you show: an
+effect attached and drawn in the same frame still compiles on that frame.
 
 One caveat if you are moving an inline effect to a file: a template literal can
 interpolate constants into the source (`vec2(${ASPECT}, 1.0)`), and a static
@@ -470,8 +512,8 @@ uniform values — fine when the look is uniform, and the reason to clone (and
 pay a link) when it is not.
 
 Note this covers **your** effects only. The engine's own mesh/quad shader
-variants are compiled lazily per feature combination on first draw and cannot be
-preloaded — see `melonjs-loading-assets` for the warm-up that covers those.
+variants are covered by the loading-screen warm-up and by the per-renderable one
+— see `melonjs-loading-assets`.
 
 ### Screen-reading builtins
 
@@ -609,6 +651,8 @@ same question after construction.
 | 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` |
+| squash and stretch only bulges, the height never changes, under Matter | the adapter rewrites `currentTransform` every step; set the scale from the sprite's `update()` |
+| `SquishEffect` squishes the whole screen instead of the sprite | it is chained with another effect, or on the camera; give the sprite it alone |
 | 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

package/skills/melonjs-events/SKILL.md

@@ -112,9 +112,9 @@ onDeactivateEvent() {
 ```
 
 **Pool-recycled objects never fire `onDestroyEvent` on removal** — `removeChildNow`
-tries `pool.push(child)` first and only calls `destroy()` if that fails, so a
-class registered with `pool.register(name, Class, true)` goes back to the pool
-instead. Anything you clean up there will not run. `destroy()` is also what calls
+first tries to return the child to the pool that built it, and only calls
+`destroy()` when nothing owns it. So anything taken from a `createPool` goes
+back to that pool instead. Anything you clean up there will not run. `destroy()` is also what calls
 `releaseAllPointerEvents(this)`, which is why a pooled object must release its
 own pointer registrations in `onDeactivateEvent`.
 
@@ -134,8 +134,10 @@ Without this, a "children emptied" handler can reset the wrong stage.
 Contact callbacks fire inline inside the physics step, mid-iteration over the
 detector's pair list. `container.removeChild()` is safe there — it defers the
 actual removal to the next tick, which is exactly why it defers. The immediate
-forms are the dangerous ones: `removeChildNow()` and `destroy()` tear the object
-down under the iteration (`destroy()` nulls `pos` and `body`). The builtin
+forms are the dangerous ones: `removeChildNow()` tears the object down under
+the iteration, via the internal `destroy()` it calls, which nulls `pos` and
+`body`. (`destroy()` is engine teardown and is not in the published types, so
+`removeChildNow` is the call a game actually makes.) The builtin
 detector guards the pair it is currently resolving, but nothing guarantees that
 for the rest of the step or for another adapter.
 
@@ -149,7 +151,7 @@ Use `removeChild()`, or flag the work and drain it from `Stage.update`.
 | handlers accumulate on pooled objects | subscribed in the constructor rather than `onActivateEvent` |
 | cleanup never runs on a pooled object | pooled removal does not fire `onDestroyEvent` |
 | crash during a stage switch | callback ran mid-teardown — guard with `state.isCurrent` |
-| crash after a collision | `removeChildNow()` / `destroy()` inside a contact callback — use `removeChild()` |
+| crash after a collision | `removeChildNow()` inside a contact callback — use `removeChild()` |
 | progress callbacks never fire | assigned `loader.onProgress` (removed in 20.3) instead of subscribing to `LOADER_PROGRESS` |
 | `onActivateEvent` never runs | the child was added to a container not yet attached to the world |
 

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, 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."
+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, KEYDOWN, KEYUP, press any key, splash screen, click, touch, drag, hit test, event propagation, stop propagating, overlapping, which object gets the click."
 license: MIT
 ---
 
@@ -29,6 +29,31 @@ wrong for jump or fire. A locked action stays consumed until the key is released
 or you call `input.unlockKey("jump")`. Use `input.keyStatus(action)` when you
 want the raw held/not-held state regardless of locking.
 
+### A poll can miss a press entirely
+
+`isKeyPressed` is sampled once per frame, and `keyup` decrements the key's
+counter the moment it arrives — locked or not. A press that goes down and up
+between two frames therefore leaves the counter back at zero and is never
+seen. At 60fps that is anything under ~16ms: rare from a human finger, routine
+from a synthetic event, and more likely the slower the frame rate.
+
+For a screen where a missed press is a dead end — a splash, a "press any key",
+a notice to acknowledge — listen for the event instead, which cannot be missed:
+
+```js
+import { event } from "melonjs";
+
+// action is the bound action name, or undefined for an unbound key
+const onKey = (action) => { if (action === "menuSelect") continue(); };
+event.on(event.KEYDOWN, onKey);      // in onResetEvent
+event.off(event.KEYDOWN, onKey);     // in onDestroyEvent — it does not self-remove
+```
+
+`KEYDOWN` fires for *every* key, bound or not, so matching on `action` is what
+narrows it; it also repeats while the key is held, so guard anything that must
+happen once. Keep polling for movement and for a menu cursor, where one step
+per press and a key held across a state change are the things that matter.
+
 The full signature is `bindKey(keyCode, action, lock?, preventDefault?)`;
 `preventDefault` defaults to `input.preventDefault` (itself `true`). Pass the
 fourth argument per binding, or change the global default with
@@ -172,11 +197,80 @@ input.bindGamepad(0,
 ```
 
 **Order matters:** `bindGamepad` throws `no action defined for keycode N` if the
-keycode has not already been passed to `bindKey`. Axes use the same call with a
-threshold: `{ type: "axes", code: input.GAMEPAD.AXES.LX, threshold: -0.5 }`.
-`unbindGamepad(index, button)`, `setGamepadDeadzone(value)` and
+keycode has not already been passed to `bindKey`.
+
+Axes use the same call with a threshold, and bind **one half of the axis each**
+— the sign selects which half:
+
+```js
+input.bindGamepad(0, { type: "axes", code: input.GAMEPAD.AXES.LX, threshold: -0.15 }, input.KEY.LEFT);
+input.bindGamepad(0, { type: "axes", code: input.GAMEPAD.AXES.LX, threshold:  0.15 }, input.KEY.RIGHT);
+```
+
+**`threshold` is added to the deadzone, it does not replace it.** The test is
+`abs(value) >= deadzone + abs(threshold)`, so with the default deadzone of 0.1
+a threshold of `0.5` does not fire until 0.6 of full travel, and `0.15` fires at
+0.25. Pick the number you want the stick to break at and subtract the deadzone.
+Raising `setGamepadDeadzone` moves every axis binding with it.
+
+`unbindGamepad(index, button, type?)`, `setGamepadDeadzone(value)` and
 `setGamepadMapping(id, mapping)` complete the surface.
 
+### Which index to bind
+
+Bindings are per pad **index**, and the index is plug order, not identity —
+nothing reports which pad is "the" controller. Slot 0 is a guess: a wheel, a
+spare pad or a keyboard-shaped device left plugged in can hold it for a whole
+session while the player presses buttons on slot 1.
+
+So a one-player game binds **every slot it will accept** to the same actions,
+and lets `activeGamepad()` say which one is in use when something has to go
+back the other way:
+
+```js
+for (let pad = 0; pad < 4; pad++) {
+    input.bindGamepad(pad, { type: "buttons", code: input.GAMEPAD.BUTTONS.FACE_1 }, input.KEY.X);
+}
+input.activeGamepad();   // the last pad to produce a bound input, else the
+                         // first connected one, else -1
+```
+
+Binding spare slots costs nothing: the poll skips a bound index with no pad in
+it. `activeGamepad()` follows **bound inputs only**, which is what makes it an
+answer about the player rather than about electrical noise — a worn stick at
+rest reports movement for ever and would otherwise claim to be the active pad.
+
+### Rumble
+
+```js
+input.vibrateGamepad(input.activeGamepad(), {
+    duration: 120, strongMagnitude: 0.6, weakMagnitude: 0.9,
+});
+input.stopGamepadVibration(index);   // cut a long effect short
+input.hasGamepadVibration(index);    // for an options-screen toggle
+```
+
+Safe to call blind: no pad, no motors, or no Gamepad API at all resolves
+`false` and does nothing, so game code never branches on support. Magnitudes
+default to **full** — the underlying web API defaults every parameter to zero,
+which makes a bare `playEffect` a silent no-op. A second call preempts the
+first on the same pad, so a rapid series of hits reads as a rapid series of
+hits rather than as a queue. For a SUSTAINED rumble issue one effect with a
+long `duration` instead of calling every frame.
+
+Hot-plugging needs no polling of your own — the engine listens for the browser's
+own events and republishes them:
+
+```js
+import { event } from "melonjs";
+
+event.on(event.GAMEPAD_CONNECTED,    (gamepad) => { /* gamepad.id, .index */ });
+event.on(event.GAMEPAD_DISCONNECTED, (gamepad) => { /* pause, show a prompt */ });
+```
+
+Bindings survive a disconnect: they are attached to the index, not to the
+device, so a pad unplugged and plugged back into the same slot keeps working.
+
 ## Virtual controls
 
 On-screen buttons synthesise key events, again reaching the same actions:
@@ -199,6 +293,8 @@ 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 |
+| stick has to be pushed well past its `threshold` before it registers | `threshold` is ADDED to the deadzone, not used instead of it |
+| one half of a stick does nothing | each half is a separate `bindGamepad`, chosen by the sign of `threshold` |
 | 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 |

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

@@ -111,13 +111,31 @@ the assets are in and **before** `LOADER_COMPLETE` fires, so it happens while
 the progress bar is still up. Every `preload()` warms, not just the first, so a
 per-level preload warms whatever that level brought with it.
 
-The one precondition: **a game that never calls `loader.preload()` is never
-warmed**, because that is the only hook. If you load assets another way, call
+The one precondition for this part: **a game that never calls
+`loader.preload()` does not get it**. If you load assets another way, call
 `await app.renderer.prewarm()` yourself. On
 WebGL that links the mesh batchers' variants, for the unlit tier and the lit
 one that inherits from it; on WebGPU it compiles the
-WGSL module of every shader the loader holds — which is the reason to declare
-effects as assets rather than build them inline (see above).
+WGSL module of every shader the loader holds, and the mip-chain blitter when
+textures are filtered.
+
+**4. Everything that depends on the renderable — warmed as you build, since
+20.10.** The rest cannot be done at preload, because it depends on what draws:
+on WebGPU a *pipeline* is keyed by blend mode, culling, transparency and the
+format of the target as well as by shader, and that compile is the expensive
+part (tens of milliseconds, up to 140ms measured, per effect). So, behind the
+same `prewarm` setting, the engine warms a renderable when it gains an effect
+(`addPostEffect`, or assigning `shader`) and when it is added to the world:
+its effect pipelines, its own draw, the render targets its chain composites
+through, the advanced-blend shader if it uses one. Inline effects are covered
+too; on WebGL that means linking a mesh-hosted effect's spliced program.
+
+That work starts after your code has run and finishes off the frame, so it
+needs **at least a frame between setting a renderable up and drawing it**. The
+pattern that gets it for free is the one you want anyway: build pools (and
+attach their effects) when the stage starts, then show and hide them during
+play. Something created and drawn in the same frame still compiles on that
+frame.
 
 Cost to a game that uses none of it is about 60ms of preload on a desktop GPU.
 Set it to `false` only for a target where linking is slow enough that the