melonjs 20.10.1 → 20.12.0

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

@@ -110,23 +110,100 @@ reused across renderables.
 
 ## Built-in effects
 
-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),
+Twenty-three 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`,
+`TintPulseEffect`, `WaveEffect`, `SwayEffect`, `InvertEffect`, `SepiaEffect`,
 `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
-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.
+**Colors take an alpha.** Every color option and `setColor` takes `[r, g, b]`
+or `[r, g, b, a]`, each 0.0 to 1.0, and the alpha is the color's own opacity: a
+half-transparent outline, a glow at half strength, a flash that only half
+covers. `[r, g, b]` is opaque, as it always was. Any other length throws.
+`RadialGradientEffect` takes a `Color` instead, and its alpha scales the spot.
+
+```js
+sprite.addPostEffect(new OutlineEffect(app.renderer, { color: [1, 1, 1, 0.5] }));
+```
+
+**On a sprite cut from an atlas or a tileset, the effects that read around a
+pixel keep to the sprite's own frame.** `GlowEffect`, `OutlineEffect`,
+`BlurEffect`, `DropShadowEffect`, `ChromaticAberrationEffect`, `WaveEffect`,
+`SwayEffect`, `PixelateEffect` and `BloomEffect` read the neighbouring frames
+as transparent, as if the sprite were drawn on its own, so they never show
+along its edges and the atlas needs no padding for them. Past the texture's own
+edge (a standalone image, or the outside of an atlas) nothing changes.
+
+**The effects that place a pattern place it on the renderable they draw.**
+`SwayEffect`'s planted row, `WaveEffect`'s `anchor`, the centre of
+`VignetteEffect`, `RadialGradientEffect` and `ScanlineEffect`'s curvature all
+land on the sprite itself: cut from an atlas, flipped, rotated, or with other
+effects after it, the pattern sits where it sits on a sprite with a texture of
+its own and that one effect. What is measured in the texture stays measured in
+it: `ShineEffect`'s sweep, bands and width, `WaveEffect`'s amplitude and
+frequency, `DissolveEffect`'s grain, the lines of `HologramEffect` and
+`ScanlineEffect` (on an atlas sprite, fractions of the atlas, so a single shine
+crosses an atlas sprite only part of the time). With other effects after them
+they all stay on the sprite. `SwayEffect` measures everything across the
+sprite.
+
+**Their widths, offsets and sizes are in pixels of the texture they draw, with
+nothing to pass.** Each of those effects takes the size of what it draws: the
+sprite's whole texture (the atlas image, not the frame), the screen for a
+camera's effect, a mesh's texture. With other effects after it, it still
+measures in the sprite's own pixels, at any scale and under a camera's zoom
+(on a container, in the container's own), so adding a second effect never
+changes how wide the first comes out. Do not pass `textureSize` to get this: a
+`textureSize` (or `setTextureSize()`) fixes the size instead, for a width
+meant in some other texture's pixels.
+
+```js
+// 2 pixels of the sprite's art, whatever the size of its atlas, its scale,
+// the camera's zoom, or the effects after it
+sprite.addPostEffect(new OutlineEffect(app.renderer, { width: 2 }));
+sprite.addPostEffect(new GlowEffect(app.renderer, { width: 6 }));
+```
+
+With two or more effects, the sprite is drawn into a capture and each effect
+reads that, at the game's texture filter, as a sprite reads its own texture:
+under `"nearest"` (or `antiAlias` off) a width that lands between two screen
+pixels, such as 2 pixels of a sprite drawn at 0.3, stays crisp, and under
+`"linear"` it blends, on WebGL and WebGPU alike. The result lands inside the
+clip the sprite is drawn under, a minimap camera's view or a clipping
+container, as with one effect.
+
+`SwayEffect` leans a sprite or a layer from side to side, as if in a breeze: the
+top sways most and everything from its `anchor` row down stays put, so a tree's
+trunk or a reed's root stays planted. It suits anything planted at its bottom;
+something hanging from its top, like a banner, needs its own shader. It is a
+`WaveEffect`, which takes the same `anchor`, so it adds no shader. Drive it with
+`setTime(seconds)` every frame, like any time-based effect; it wraps the phase
+itself, so a raw clock never costs precision on a phone's medium-precision
+floats.
+
+```js
+const sway = new SwayEffect(app.renderer, { strength: 0.02, anchor: 0.9 });
+tree.addPostEffect(sway);
+// each frame
+sway.setTime(timer.getTime() / 1000);
+```
+
+Its strength (a fraction of the sprite's width), its `anchor` and how it bends
+are all measured across the sprite, so a sprite cut from an atlas sways exactly
+like the same art with a texture of its own. `WaveEffect`'s `anchor` is a row of
+the sprite too, but its amplitude and frequency are measured across the texture,
+so on an atlas sprite they are fractions of the atlas.
+
+`RadialGradientEffect` is a procedural soft spot: solid at the centre of the
+renderable it draws, fading linearly to transparent at the edge, and elliptical
+for free on a non-square one. 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,
+on a standalone image, `Renderer.getWhitePixel()` or a sprite cut from an atlas
+alike.
 
 `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
@@ -178,9 +255,8 @@ app.viewport.addPostEffect(
 );
 ```
 
-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.
+Its `radius` is in texels of what it filters, the screen on a camera, and it
+follows a resize by itself.
 
 **`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,
@@ -460,6 +536,42 @@ loader.preload([{ name: "ramp", type: "shader", data: myFragmentBody }]);
 label.addPostEffect(loader.getShader("ramp"));
 ```
 
+### Sprites sharing one effect share one draw
+
+Sprites drawn one after the other through the **same** effect instance are one
+draw call, as plain sprites are, even when they come from different frames of
+an atlas: a hundred enemies outlined by one shared `OutlineEffect` draw once.
+Each still draws with the values it was given: a uniform set to a **new**
+value draws the sprites queued before it first (setting the value it already
+has changes nothing). What splits the batch:
+
+- a uniform taking a new value between two sprites: give a few sprites the
+  same value one after the other, rather than a different one each;
+- a different texture (the effect path samples one texture per draw);
+- a different effect instance, or a sprite without the effect in between;
+- a `noise_uv` effect on sprites of different frames or sizes (its rect is
+  per sprite);
+- one of the effects that place a pattern on the sprite (`SwayEffect`,
+  `WaveEffect`, `ShineEffect`, `VignetteEffect`, `RadialGradientEffect`,
+  `ScanlineEffect`, `DissolveEffect`, `HologramEffect`): each sprite is told
+  where it is, so each draws on its own;
+- a `screen_texture` effect, which draws each sprite on its own, as each one
+  samples a capture of everything drawn before it.
+
+So share one instance (the loader's `"shader"` type hands one back, see
+above) rather than constructing an effect per sprite: *n* instances are *n*
+draws as well as *n* programs. One you construct yourself and share needs
+`effect.shared = true`, or the first renderable destroyed destroys it for the
+others (the loader's are marked shared already):
+
+```js
+const outline = new OutlineEffect(renderer, { color: [1, 1, 1] });
+outline.shared = true; // you destroy it, when no enemy is left
+for (const enemy of enemies) {
+    enemy.addPostEffect(outline);
+}
+```
+
 ### Declare a level's effects with that level's assets
 
 An effect the loader knows about can be prepared before anything draws it; an
@@ -522,7 +634,9 @@ For refraction, distortion and anything that samples what is already drawn:
 - **`screen_texture`** — a sampler kept filled with everything drawn so far
   (GLSL: annotate the sampler `uniform sampler2D tex : screen_texture;`)
 - **`screen_uv`** — this fragment's 0..1 position in that capture
-- **`noise_uv`** — 0..1 across the sprite regardless of its atlas frame
+- **`noise_uv`** — 0..1 across the sprite regardless of its atlas frame, and
+  across the renderable when it has several effects (it does not slide with
+  the camera)
 
 In WGSL the capture is sampled through `screen_sampler` (clamped) or
 `screen_sampler_repeat` (wrapping) instead of GLSL's `: screen_texture`
@@ -617,11 +731,13 @@ that against your request detects the fallback.
 
 ## The Canvas fallback
 
-`ShaderEffect` on a Canvas renderer logs a warning, leaves `enabled = false`, and
-turns every method into a no-op. Nothing throws. The same happens on a GPU
-backend when no body matches its language — a GLSL-only effect under WebGPU.
+`ShaderEffect` on a Canvas renderer leaves `enabled = false` and turns every
+method into a no-op. Nothing throws, and the console gets one warning, from the
+first such effect; the rest stay quiet. The same happens on a GPU backend when
+no body matches its language — a GLSL-only effect under WebGPU.
 
-That is fine for decoration. It is **not** fine when the shader draws your
+That is fine for decoration, which needs no guard: create and add the effect as
+on any renderer. It is **not** fine when the shader draws your
 content — the carrier renderable then shows through raw. A 1×1 white texture
 stretched to 280×156 renders as a white box where the effect should be.
 
@@ -650,6 +766,7 @@ same question after construction.
 | 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 |
+| many sprites with the same effect still cost a draw each | an effect instance per sprite, or a uniform set to a different value per sprite — share one instance and group sprites by value |
 | 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 |

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, KEYDOWN, KEYUP, press any key, splash screen, 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, virtual gamepad, touch controls, joystick, gamepad-plugin, KEYDOWN, KEYUP, press any key, splash screen, click, touch, drag, hit test, event propagation, stop propagating, overlapping, which object gets the click."
 license: MIT
 ---
 
@@ -273,7 +273,27 @@ 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:
+For on-screen touch controls, use `@melonjs/gamepad-plugin` rather than
+writing them: sticks and buttons drawn over the game and reported as a pad in
+a gamepad slot, so the `bindGamepad` bindings above answer to them unchanged.
+
+```js
+import { GamepadPlugin } from "@melonjs/gamepad-plugin";
+
+// once the application is created: a stick and two buttons, on touch screens
+plugin.register(GamepadPlugin, "gamepad", {
+    buttons: [{ label: "A" }, { label: "B" }],
+});
+```
+
+The left stick presses the D-pad buttons (`GAMEPAD.BUTTONS.UP` ...) in 8
+directions and reports `AXES.LX`/`LY`; the buttons press `FACE_1`, `FACE_2`...
+in turn, or a key with `{ key: input.KEY.SPACE }`. Each finger is followed on
+its own, a touch starting on the controls does not reach the game, and they
+hide while a real pad is in use. `plugin.cache.gamepad.visible` says whether
+they show, to word a prompt ("tap" or a key name).
+
+A single key can also be pressed directly, reaching the same actions:
 
 ```js
 input.triggerKeyEvent(input.KEY.LEFT, true);    // press
@@ -299,6 +319,8 @@ input.triggerKeyEvent(input.KEY.LEFT, false);   // release
 | 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 |
+| touch controls do nothing | nothing bound to their slot — `bindGamepad` on the plugin's `index` (0 by default), or give the buttons a `key` |
+| touch controls never show on a desktop | the gamepad plugin's `enabled` defaults to `device.touch` — pass `enabled: true` to try them there |
 
 ## Related skills
 

package/skills/melonjs-lighting/SKILL.md

@@ -41,6 +41,34 @@ normal-mapped sprites.
 returns immediately while its alpha is 0 — so with no ambient colour set there
 is nothing to cut through and the lights just look like soft additive blobs.
 
+## Soft edges: `softness`
+
+A light's hole in the darkness is hard-edged by default: full light inside its
+radius, full darkness outside. `light.softness` (0 to 1) fades it instead:
+
+```js
+const torch = new Light2d(x, y, 220, 220, "#ffb46a", 0.4);
+torch.softness = 0.8;      // lit core of 20% of the radius, then fading out
+```
+
+- `1` thins the darkness straight from the centre to the edge, the same falloff
+  as the glow; in between, a fully lit core of `1 - softness` of the radius.
+- Hard and soft lights mix in one scene. Where lights overlap, what is left of the
+  darkness is what each leaves, multiplied, so two half-lights make three
+  quarters light.
+- The hole is the light's size. For an opening wider than the glow (a torch whose
+  light reaches further than its flame's halo), add a second, bigger light with
+  `illuminationOnly = true`: it cuts the darkness and draws nothing.
+- Up to 32 lights in view are cut by one soft pass; lights outside the view do not
+  count. A scene with no soft light draws exactly as before.
+- To keep a camera out of the darkness (a minimap showing the level lit),
+  override `drawLighting` on the stage and skip that camera.
+- To keep one light out of a camera, put it, or a container it is in, on a
+  `visibilityLayer` the camera's `cullMask` leaves out: there it neither glows,
+  nor cuts the darkness, nor lights normal-mapped sprites (see
+  `melonjs-camera-and-drawing`). This is for a `Light2d`: a `Light3d` lights
+  the meshes of every camera.
+
 ## Multiple lights
 
 Add as many as you need — the glow quads and the ambient cutouts accumulate with
@@ -131,8 +159,9 @@ 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`.
 
-Without a normal map a sprite is still lit, but flatly: brightness varies with
-distance from the light, not with surface direction.
+Without a normal map a sprite is not shaded at all: it takes the unlit path on
+every backend, and a light changes how it looks only through its additive glow
+and its cutout in the ambient darkness.
 
 ## What needs a GPU backend, and what does not
 
@@ -140,13 +169,15 @@ Less than you would expect. `Light2d` is renderer-agnostic: it just calls
 `renderer.drawLight(this)`, and every backend implements it — the GPU backends
 through a shared procedural radial-falloff shader, the Canvas renderer by
 rasterising a cached `Gradient` into one shared render target and compositing it
-with `drawImage`. The ambient cutout pass is plain `setMask` + `fillRect`. So the
-lit-spot look works everywhere, Canvas included.
+with `drawImage`. The hard ambient cutout pass is plain `setMask` + `fillRect`;
+the soft one is one shader pass on the GPU backends and an offscreen canvas on
+Canvas. So the lit-spot look, soft or hard, works everywhere, Canvas included.
 
 What Canvas cannot do is **per-pixel normal-map lighting**:
-`renderer.setLightUniforms()` is a no-op there, and the first frame that passes a
-non-empty light list logs a one-shot warning. Normal-mapped sprites simply render
-unlit — no error.
+`renderer.setLightUniforms()` is a no-op there, and the first normal-mapped
+sprite drawn while lights are on logs a one-shot warning (a scene with lights
+and no normal maps stays quiet). Normal-mapped sprites simply render unlit — no
+error.
 
 ```js
 if (app.renderer.shaderLanguage === null) {
@@ -171,7 +202,11 @@ See the `melonjs-3d` skill.
 | symptom | cause |
 |---|---|
 | lights added but the scene never darkens | no ambient colour set — `ambientLight` alpha is 0, so the pass returns early |
-| sprite lit flatly, ignoring light direction | no `normalMap` on the sprite, or the Canvas backend is active |
+| the lit area has a hard rim | `softness` is 0 (the default): set it on the light |
+| the darkness opens no wider than the glow | the hole is the light's size: add a bigger `illuminationOnly` light for the opening |
+| a minimap or second camera is dark too | every camera draws the stage's darkness: override `drawLighting` and skip that camera |
+| a light should show in one camera only | put it on a `visibilityLayer` the other camera's `cullMask` leaves out |
+| sprite not shaded by a light, only glowed over | no `normalMap` on the sprite, or the Canvas backend is active |
 | normal-mapped sprite is pure black where unlit | `Stage.ambientLightingColor` left at black |
 | the 33rd light shades nothing | `MAX_LIGHTS = 32` for the normal-map pipeline |
 | `TypeError` assigning `normalMap` | not an image-like value (a video element is rejected outright) |

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

@@ -183,7 +183,8 @@ the hard way:
 ### `DefaultLoadingScreen` lives in the WORLD, not on the screen
 
 The built-in loading screen is written for a `Camera2d`. Its progress bar and
-logo are added with `app.world.addChild(bar, 1)` / `addChild(logo, 2)` and are
+logo are added together, once the logo is decoded (a frame or so after the
+screen comes up), with `app.world.addChild(bar, 1)` / `addChild(logo, 2)`, and are
 **`floating === false`** — ordinary world-space renderables. They read as an
 overlay only because that stage's world is otherwise empty.
 
@@ -195,7 +196,7 @@ in front of a bar sitting at z = 1. What does NOT rescue it, all tried:
   depth, so the scene's own z values are geometry, not layering, and the bar
   still loses to the depth test.
 - **`moveToTop()`** — it early-returns for a child already at index 0, which the
-  loading screen's children always are, having been added before anything else.
+  loading screen's children usually are, having been added before anything else.
   It silently does nothing.
 - **Flipping them to `floating = true`** for the duration — the scene still
   covers them.
@@ -397,7 +398,7 @@ throws, the same trap as the removed `loader.onload` / `onProgress`.
 
 | | |
 | --- | --- |
-| one streamed clip (`stream: true` / `html5: true`) ignores `withCredentials` | it plays through an `<audio>` element, which needs a `crossorigin` attribute rather than fetch credentials. Preload it buffered if it is behind auth |
+| one streamed clip (`stream: true` / `html5: true` / `preload: false`) ignores `withCredentials` | it plays through an `<audio>` element, which needs a `crossorigin` attribute rather than fetch credentials. Preload it buffered if it is behind auth |
 | credentials silently dropped for audio before 20.4 | the loader forwarded them under a pre-20.3 name the backend never read — a hung preload rather than an error |
 
 ## Symptom → cause

package/skills/melonjs-math/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-math
-description: "Use this skill for vector and matrix maths in melonJS — Vector2d, Vector3d, their observable variants, Matrix2d, Matrix3d, and the math utility functions. Covers which methods mutate and which allocate, the vector pool and when clone() is the wrong tool, interpolation with lerp, slerp, damp and moveTowards, and the argument defaults that silently drop a component. Triggers on: Vector2d, Vector3d, ObservableVector2d, ObservableVector3d, Matrix2d, Matrix3d, vector, vector maths, dot, cross, normalize, length, distance, angle, lerp, slerp, damp, moveTowards, project, clamp, degToRad, radToDeg, clone, vector pool, vector3dPool, setMuted, setCallback, my vector is wrong, z is zero, scale ignores z., moveTowards ignores z, projectN, currentTransform, setTransform, matrix, transform matrix, column-major, val, Float32Array, basis matrix, orientation matrix."
+description: "Use this skill for vector and matrix maths in melonJS — Vector2d, Vector3d, their observable variants, Matrix2d, Matrix3d, and the math utility functions. Covers which methods mutate and which allocate, the vector pool and when clone() is the wrong tool, interpolation with lerp, slerp, damp and moveTowards, and the argument defaults that silently drop a component. Triggers on: Vector2d, Vector3d, ObservableVector2d, ObservableVector3d, Matrix2d, Matrix3d, vector, vector maths, dot, cross, normalize, length, distance, angle, lerp, slerp, damp, moveTowards, project, clamp, degToRad, radToDeg, clone, vector pool, vector3dPool, setMuted, setCallback, my vector is wrong, z is zero, scale ignores z., moveTowards ignores z, projectN, currentTransform, setTransform, matrix, transform matrix, column-major, val, Float32Array, basis matrix, orientation matrix, Noise, getNoise1d, flicker, wobble."
 license: MIT
 ---
 
@@ -291,6 +291,25 @@ math.pow(n);                     // n squared
 math.DEG_TO_RAD  math.RAD_TO_DEG  math.TAU  math.ETA  math.EPSILON
 ```
 
+### Values that wobble over time
+
+`Noise`, the generator behind `NoiseTexture2d`, also samples directly. For a
+value that should drift without repeating (a torch's flicker, a sway, a camera
+wander), sample it with time:
+
+```js
+import { Noise } from "melonjs";
+
+const noise = new Noise({ seed: 7, frequency: 1.5, octaves: 3 });
+// around 1; give each object its own offset so they do not move together
+const flicker = 1 + 0.2 * noise.getNoise1d(seconds + offset);
+```
+
+`getNoise1d` returns `[-1, 1]` (with fractal octaves most values fall within
+about ±0.6), `frequency` is in changes per unit of the input, and the same seed
+gives the same field every run. A sum of sines repeats where people notice it,
+and `Math.random()` every frame jitters instead of drifting.
+
 ## Symptoms
 
 | symptom | cause |
@@ -305,6 +324,7 @@ math.DEG_TO_RAD  math.RAD_TO_DEG  math.TAU  math.ETA  math.EPSILON
 | you built your own 16-number array | `Renderable.currentTransform` is already a `Matrix3d`; write its `val` |
 | a value read back from a matrix differs | `val` is `Float32Array`; it holds float32 |
 | easing differs at 120fps | per-frame `lerp`; use `damp` |
+| a flicker or sway looks mechanical, or visibly repeats | a sum of sines or a per-frame `Math.random()`: sample `Noise#getNoise1d(time)` |
 
 ## 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, 3D particle motion through elevation and minSpread/maxSpread in 20.8, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: Trail3d, ribbon, exhaust trail, speed streak, ski track, tyre mark, ribbonNormal, ParticleEmitter, particles, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter."
+description: "Use this skill for particle effects and motion trails in melonJS — ParticleEmitter configuration, burst versus stream emission, the referenceSpace frame of reference introduced in 20.2, 3D particle motion through elevation and minSpread/maxSpread in 20.8, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: Trail3d, ribbon, exhaust trail, speed streak, ski track, tyre mark, ribbonNormal, ParticleEmitter, particles, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter, tintOverLife, colour over life, color over life, flame, fire."
 license: MIT
 ---
 
@@ -60,7 +60,8 @@ pair it with `framewidth`/`frameheight` or it does nothing.
 
 Note the variety is in SHAPE, not colour. `tint` belongs to the emitter, so
 every particle from one emitter is tinted alike however many frames it picks
-between.
+between. For a colour that changes over each particle's life, use
+`tintOverLife` (below) rather than drawing one frame per colour.
 
 Frame dimensions must be positive integers that fit inside the image, and an
 explicit `frames` sequence must be nonempty and contain valid integer indices.
@@ -69,6 +70,35 @@ Invalid configurations throw `RangeError` before changing an emitter during
 only future particles, so ones already alive finish with their original image,
 frame size and sequence.
 
+## Colour over life: `tintOverLife`
+
+`tintOverLife` is the list of tints a particle takes over its life: the first at
+birth, the last at the end, evenly spaced and blended in between. Give as many
+CSS colours as you like (repeat one to hold it longer); it replaces `tint`.
+
+```js
+// a flame: white hot, then orange, then deep red as it rises and dies
+const flame = new ParticleEmitter(x, y, {
+    image: softDot,                     // a white texture takes the tints as they are
+    tintOverLife: ["#fff3b0", "#ffc455", "#ff8a26", "#e45414", "#a0280c"],
+    textureAdditive: true,
+});
+```
+
+- **Colour only.** Opacity is still the built-in fade over the particle's life;
+  the alpha of a colour in the list is ignored. On an additive emitter, a darker
+  colour is a dimmer particle, so fold a "fainter" step into the colour itself.
+- **32 steps.** However many colours, the blend is taken in 32 steps, the same on
+  every renderer: a particle changes colour at most 32 times. That matters on
+  Canvas, which keeps a tinted copy of the texture for every colour it is asked
+  to draw: 32 at most per texture.
+- **Author the texture white.** `tint` multiplies, so a coloured texture muddies
+  every step.
+- It works alongside sprite-sheet `frames` (one picks the image, the other the
+  colour), and a list that is empty, not an array, or holds a non-string throws a
+  `TypeError` from the constructor or `reset()`, which then leaves the emitter as
+  it was. The list is copied: change it through `reset()`.
+
 ## Where particles are born
 
 `width` and `height` are the spawn AREA, and both default to `1` — so by
@@ -290,6 +320,7 @@ answer when you want discrete puffs rather than a continuous ribbon.
 | symptom | cause |
 |---|---|
 | trail looks flat under a `Camera3d` | `Trail` is 2D; use `Trail3d` |
+| particles clutter a minimap or a second camera | every camera draws them: set the emitter's `visibilityLayer` to a layer that camera's `cullMask` leaves out (see `melonjs-camera-and-drawing`) |
 | `Trail3d` draws nothing, with a console warning | it needs a `Camera3d`; the app's `cameraClass` is still the 2D default |
 | `trail.tint` does nothing | `Trail` cannot be tinted at all; `Trail3d` can |
 | assigning `maxPoints` throws | `Trail3d` sizes its geometry once; pass `length` to the constructor |
@@ -298,6 +329,9 @@ answer when you want discrete puffs rather than a continuous ribbon.
 | the cloud follows a moving emitter | default `referenceSpace: "local"` — use `"world"` for trails |
 | particles do not travel far enough | settings tuned pre-20.2, when drawn travel was doubled |
 | one-shot emitters accumulate | missing `autoDestroyOnComplete: true` |
+| every particle of an emitter is the same colour all its life | `tint` is one value for the emitter: use `tintOverLife` for a colour that changes as it ages |
+| a `tintOverLife` colour's transparency has no effect | the list sets the colour only; opacity is the particle's fade |
+| `tintOverLife` colours look muddy | the texture is coloured; author it white so the tints come through as given |
 | 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` |

package/skills/melonjs-performance/SKILL.md

@@ -222,6 +222,9 @@ queries one at a time, usually not. See `melonjs-3d` for the decision table.
 
 - `stream: true` on long music tracks plays through a streaming element instead
   of decoding the whole file into memory.
+- `preload: false` on music a player may never reach (a boss theme, the
+  ending) keeps it out of the initial download: it is fetched and streamed
+  when first played.
 - `pool` on an audio clip sizes the reuse pool for finished instances — it is
   **not** a concurrency cap.
 - `loader.unloadAll()` between large levels drops every loaded asset and
@@ -373,6 +376,7 @@ In rough order for a typical 2D game:
 | a freeze the first time a level shows, never again | shader variants linking on first draw — warm them behind the loading screen |
 | a freeze the first time an effect appears mid-play (a shield, a hit flash) | the effect attached in the same frame it is drawn — attach it when the pool is built, so the warm-up has a frame to finish |
 | the same scene stutters once per entry | a derived texture rebuilt per stage: the texture cache keys on the image object, so each rebuild is a new upload |
+| steady movement stutters while the frame rate reads 60 | not a cost: frame-time jitter gives a frame no update and the next two; set `syncToDisplay: true` (see `melonjs-display-and-scaling`) |
 
 ## Related skills
 

package/skills/melonjs-plugins/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-plugins
-description: "Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, Capacitor packaging — or when writing your own plugin. Covers plugin.register and its version gate, plugin.cache, plugin.patch, and why physics adapters are not plugins. Triggers on: plugin, plugin.register, plugin.cache, plugin.get, plugin.patch, BasePlugin, debug-plugin, DebugPanelPlugin, SpinePlugin, TiledInflatePlugin, CapacitorPlugin, adapter, custom plugin, plugin version mismatch, already registered."
+description: "Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, on-screen touch controls, Capacitor packaging — or when writing your own plugin. Covers plugin.register and its version gate, plugin.cache, plugin.patch, and why physics adapters are not plugins. Triggers on: plugin, plugin.register, plugin.cache, plugin.get, plugin.patch, BasePlugin, debug-plugin, DebugPanelPlugin, SpinePlugin, TiledInflatePlugin, GamepadPlugin, gamepad-plugin, touch controls, virtual joystick, CapacitorPlugin, adapter, custom plugin, plugin version mismatch, already registered."
 license: MIT
 ---
 
@@ -88,6 +88,25 @@ This is the answer for deforming animated characters — glTF import does not re
 vertex skinning. It also registers a Tiled object class, so Spine skeletons can
 be placed from a map.
 
+### `@melonjs/gamepad-plugin`
+
+On-screen touch controls, reported as a gamepad: one or two sticks and any
+number of buttons, drawn over the game and read by the engine as a pad in a
+gamepad slot. The game's `bindGamepad` bindings drive it unchanged, so one set
+of bindings covers a real pad and a touch screen.
+
+```js
+import { GamepadPlugin } from "@melonjs/gamepad-plugin";
+plugin.register(GamepadPlugin, "gamepad", {
+    buttons: [{ label: "A" }, { label: "B" }],
+});
+// plugin.cache.gamepad.visible — showing, to word prompts ("tap" or a key)
+```
+
+Shown on touch screens by default (`enabled`), hidden while a real pad is in
+use. The left stick also presses the D-pad; a button can press a key instead
+of a pad button. See `melonjs-input` for the bindings.
+
 ### `@melonjs/capacitor-plugin`
 
 Bridges Capacitor's native lifecycle and hardware-back events into the engine:

package/skills/melonjs-renderables/SKILL.md

@@ -96,9 +96,44 @@ world.addChild(sprite, 10);   // ✓ the only reliable form
 2. **Setting `depth` *before* `addChild` is overwritten.** With `autoDepth` on
    (the default), `addChild` without an explicit `z` assigns
    `child.pos.z = children.length` after the push, discarding whatever you set.
-3. **Setting `depth` *after* `addChild` does not reorder.** Containers sort when
-   a child is added (`autoSort`, deferred to the next tick), not when `pos.z`
-   changes. If you must change it later, call `container.sort()` yourself.
+3. **Setting `depth` *after* `addChild` does not reorder.** A `"z"` sort runs
+   when a child is added (`autoSort`, deferred to the next tick), not when
+   `pos.z` changes. If you must change it later, call `container.sort()`
+   yourself, or use `moveToTop` / `moveUp` / `moveDown` / `moveToBottom`, which
+   reorder the children themselves. (An `"x"` / `"y"` sort is different: see
+   below.)
+
+### Sorting on `"y"` (or `"x"`), and `sortOffset`
+
+A container with `sortOn = "y"` draws its children from the smallest `pos.y` to
+the largest, so whatever is lower on screen covers what is above it (top-down and
+isometric games). `"x"` does the same along x. A different `pos.z` still decides
+first, so keep the children that should interleave at one z.
+
+- **Moving a child re-sorts by itself.** With `autoSort` on (the default), the
+  container checks its order at the end of every update, after physics and the
+  children's own updates, and re-sorts when anything is out of place: a walking
+  character needs no `sort()` call. A frame where nothing moved costs one pass
+  over the children and does not cause a redraw. Turn `autoSort` off to keep
+  the children in the order you put them.
+- **Ties keep insertion order, and the child added LAST is drawn BEHIND.** A
+  torch placed at its wall's exact position disappears behind the wall.
+
+`sortOffset` changes the ORDER only, never where anything is: the child is lined
+up as if it stood that many pixels lower (positive) or higher (negative), and is
+drawn exactly where it was. Use it when `pos` is not the point to sort by:
+
+```js
+torch.sortOffset = 1;                        // win the tie with the wall it hangs on
+dust.sortOffset = door.pos.y - dust.pos.y;   // an emitter's pos is the top of its
+                                             // spawn area: line it up with the door
+prop.sortOffset = prop.height;               // sort by the bottom of the image
+```
+
+A container that keeps itself sorted picks a change up at its next update (with
+`autoSort` off, call its `sort()`). `"z"` and `"depth"` sorting ignore it. It must be a finite number (a string
+or `NaN` throws, rather than scrambling every sibling), and a pooled renderable
+starts again at `0`.
 
 The exception: under `Camera3d` the world's `sortOn` is `"depth"`, and the
 camera calls `container.sortNow(true)` every frame. Note that mode does **not**
@@ -139,9 +174,10 @@ Use `addPostEffect()` / `getPostEffect()` / `removePostEffect()`. Assigning
 `renderable.shader = …` is deprecated since 19.2.0.
 
 Post effects need a programmable pipeline. A `ShaderEffect` constructed against
-the Canvas renderer (`renderer.shaderLanguage === null`) logs a warning, stays
-at `enabled === false` and no-ops every method rather than throwing — and
-`beginPostEffect` filters disabled effects out. Since `video.AUTO` picks the
+the Canvas renderer (`renderer.shaderLanguage === null`) stays at
+`enabled === false` and no-ops every method rather than throwing — and
+`beginPostEffect` filters disabled effects out. The first one logs a warning,
+the rest stay quiet, so a decorative effect needs no renderer check. Since `video.AUTO` picks the
 backend at runtime, an effect that works on your machine may do nothing on
 another.
 
@@ -262,6 +298,10 @@ other correct ending.
 - `floating = true` pins a renderable to the screen rather than the world, which
   is what you want for HUD elements. It opts the object out of camera transforms
   and out of ancestor position accumulation.
+- `visibilityLayer` decides which cameras draw a renderable: a camera draws it
+  only if it shares a bit with the camera's `cullMask` (every camera, by
+  default). See `melonjs-camera-and-drawing` for keeping something off a
+  minimap.
 
 ## Prefer built-in features
 

package/skills/melonjs-renderer-backends/SKILL.md

@@ -47,8 +47,8 @@ once and then degrades or no-ops, so the game runs and looks wrong.
 Two Canvas rows are worth spelling out because they are easy to misread as total
 failures. A `Light2d` still *draws* — the Canvas renderer bakes a radial gradient
 per light and blits it — what disappears is per-pixel normal-map shading, which
-warns once (`Light2d normal-map lighting requires the WebGL renderer`) and then
-renders sprites unlit. A `Mesh` still draws too, sorted with the painter's
+warns once (`Light2d normal-map lighting requires a GPU backend`), the first time
+a normal-mapped sprite is drawn under a light, and then renders sprites unlit. A `Mesh` still draws too, sorted with the painter's
 algorithm and no depth buffer, so convex models look right and anything
 self-overlapping does not. `"none"` (replace, alpha included) is the one blend
 mode Canvas cannot express — there is no `globalCompositeOperation` that