melonjs 20.10.1 → 20.11.0

package/skills/melonjs-audio/SKILL.md

@@ -100,7 +100,27 @@ await loader.preload([{
 audio.play("sfx", { sprite: "jump" });
 ```
 
-The optional third element marks a region as looping. `play()`'s second argument
+### A loop with no gap
+
+An MP3 encoder pads the end of its file. Chrome and Firefox trim the padding when
+they decode it, Safari keeps it, so a looping MP3 has a short silence at every
+loop there (27 ms on a 12 s clip at 22 kHz, measured). Declare a region of the
+loop's exact length and loop on that: the voice never reaches the padding.
+
+```js
+await loader.preload([{
+    name: "ambience", type: "audio", src: "data/sfx/",
+    sprite: { loop: [0, 12000] },
+}]);
+audio.playTrack("ambience", { sprite: "loop", volume: 0.6 });
+// or, as a plain clip: audio.play("ambience", { sprite: "loop", loop: true })
+```
+
+Ogg Vorbis carries no such padding.
+
+The optional third element marks a region as looping: it loops unless `play()` is
+told `loop: false` (before 20.11 it only looped when `loop: true` was passed as
+well). `play()`'s second argument
 takes either the original `loop` boolean or a `PlayOptions` object
 (`sprite`, `loop`, `onend`, `volume`, plus the spatial `follow`, `at` and
 `stopWithTarget`) — both forms work. Object fields win over the positional
@@ -467,6 +487,7 @@ either way — blank screen, empty console.
 | a looping sound outlives the entity that owns it | `follow` without `stopWithTarget: true` |
 | a voice panned with `stereo()` loses its 3D placement, or the reverse | one panner node per voice and last writer wins — pick one per voice and stay with it |
 | a reverb / compressor on the master gain does not affect the music | the music is `stream: true`, which bypasses the master gain — preload it buffered |
+| a looping MP3 drops out for a moment at every loop, in Safari only | Safari keeps the encoder's padding at the end of the file: loop a sprite region of the clip's exact length (see "A loop with no gap") |
 | sound effects keep playing after the window loses focus | `pauseOnBlur` and `stopOnBlur` are both off, so the engine is deliberately leaving the game running in the background |
 
 ## Related skills

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, baking with CanvasRenderTarget, and reading pixels back. 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, toImageData, getImageData, toBlob, toDataURL, screenshot, read pixels."
+description: "Use this skill for camera control and immediate-mode drawing in melonJS — following a target, viewport bounds, shake and fade, secondary cameras and what each one draws, and drawing shapes, lines and gradients inside a custom draw(). Covers world versus screen coordinate conversion, clipping and masking, baking with CanvasRenderTarget, and reading pixels back. Triggers on: Camera2d, viewport, follow, offset, look ahead, setBounds, minimap, second camera, split screen, cullMask, visibilityLayer, hide from a camera, shake, fadeIn, fadeOut, worldToLocal, localToWorld, colorMatrix, renderer.fill, renderer.stroke, Rect, Ellipse, Polygon, Line, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d, lookAt, setBasis, toImageData, getImageData, toBlob, toDataURL, screenshot, read pixels."
 license: MIT
 ---
 
@@ -24,6 +24,24 @@ frame-rate independent since 19.7. `AXIS.HORIZONTAL` / `AXIS.VERTICAL` /
 
 Call it from the followed entity's `onActivateEvent`, using `this.parentApp`.
 
+**To frame the target off centre, set `offset`; do not follow a helper
+object.** It shifts the view without moving the camera, in world units, and is
+applied after following and the bounds, so the view can show past them:
+
+```js
+app.viewport.follow(player, app.viewport.AXIS.BOTH, 0.1);
+app.viewport.offset.set(0, -70);   // look a little above the feet
+
+// or ahead of where the player faces, eased (see math.damp below)
+const ahead = facingLeft ? -80 : 80;
+app.viewport.offset.x = math.damp(app.viewport.offset.x, ahead, 4, dt / 1000);
+```
+
+Culling, tile layers, parallax `ImageLayer`s, lights and the pointer
+(`localToWorld`, `worldToLocal`) all count it. `shake()` adds its jitter on top
+and gives the value back when it ends, so setting it before or during a shake
+is fine. `reset()` clears it.
+
 **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
@@ -191,6 +209,37 @@ View state is per camera, not per scene: a `Camera3d` carries its own distance
 fog (`setFog`), so a minimap or split-screen view fogs independently of the main
 one — and a `Camera2d` never fogs. See `melonjs-3d`.
 
+### What each camera draws: `visibilityLayer` and `cullMask`
+
+Every camera draws the whole world. To keep something off one camera only, put
+it on a layer that camera leaves out. A renderable's `visibilityLayer` is the
+layers it is on, as bits (1, 2, 4...); a camera's `cullMask` is the layers it
+draws. A camera draws a renderable only if the two share a bit:
+
+```js
+const PARTICLES = 2;
+emitter.visibilityLayer = PARTICLES;   // the particles go on layer 2
+minimap.cullMask = ~PARTICLES;         // the minimap draws every layer but 2
+```
+
+- By default every renderable is on layer 1 and every camera draws every layer
+  (`cullMask` is `-1`), so nothing changes until a game sets one.
+- A container left out is left out with everything inside it, however deep:
+  set it on an emitter and none of its particles are drawn. The world itself
+  obeys it too, and so does what it contains: a child is drawn only if it and
+  every container above it share a bit with the camera.
+- A renderable on layer `0` is drawn by no camera; a `cullMask` of `0` draws
+  nothing.
+- It decides drawing only: what a camera leaves out still updates, collides and
+  receives pointer events.
+- A `Light2d` a camera leaves out, itself or a container it is in, neither
+  glows, nor cuts its hole in the darkness, nor lights normal-mapped sprites in
+  that camera. A `Light3d` lights the meshes of every camera.
+- It adds to the floating rule: a floating renderable is drawn by a secondary
+  camera only with `visibleInAllCameras`, and only if the layers match as well.
+- On a Tiled object, set it as an `int` custom property named
+  `visibilityLayer`.
+
 ## Immediate-mode drawing
 
 Inside a custom `draw(renderer)` you can draw shapes directly. Remember the two
@@ -269,6 +318,14 @@ Pass `rt.canvas`, never `rt` — a `CanvasRenderTarget` is a wrapper, not a
 drawable, and the engine's own bakes (the particle emitter's default texture)
 hand `.canvas` on for exactly that reason.
 
+**Create it once and keep it.** On a GPU backend, once drawn, its texture stays
+on the GPU for as long as the renderer lives: a stage change does not release
+it, and no public call does. A target made for every level, every restart or
+every spawned object leaks one texture each time, so make it once (at module
+level, say) and clear it for reuse. If you paint into it again after it has
+been drawn, call `rt.invalidate(renderer)` before the next draw so the GPU copy
+is refreshed.
+
 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()`
@@ -338,7 +395,12 @@ const data = await rt.toImageData(0, 0, w, h);
 | baked target draws nothing / throws | passed the `CanvasRenderTarget`, not its `.canvas` |
 | `getImageData()` throws on one machine but not another | that one is on the WebGPU renderer, which cannot read back synchronously — `await toImageData()` instead |
 | frame rate drops with many static draws | bake into a `CanvasRenderTarget` instead |
+| GPU memory grows with every level or restart | a `CanvasRenderTarget` created each time: make one and reuse it |
+| a repainted `CanvasRenderTarget` still shows the old pixels | call `rt.invalidate(renderer)` after painting |
 | a 3D camera cannot be given an arbitrary up | `Camera3d#lookAt(target, up)` or `setBasis(right, up, forward)`; see `melonjs-3d` |
+| particles or effects clutter a minimap | every camera draws everything: put them on their own `visibilityLayer` and leave it out of the minimap's `cullMask` |
+| something is missing from one camera only | its `visibilityLayer`, or a container's above it, shares no bit with that camera's `cullMask` |
+| a renderable shows in no camera at all | its `visibilityLayer` is `0`, or the world's own layer is left out |
 
 ## Related skills
 

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

@@ -1,6 +1,6 @@
 ---
 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."
+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 and linear-mipmap for what is drawn small, subPixel, syncToDisplay for steady motion, 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, linear-mipmap, mipmaps, minimap shimmer, zoomed out, subPixel, syncToDisplay, stutter, judder, uneven scrolling, devicePixelRatio, retina, hidpi, design resolution, canvas size, canvas cropped, letterbox, image-rendering, upscale, resolution."
 license: MIT
 ---
 
@@ -23,7 +23,9 @@ separate decisions. Knowing which setting owns which is most of the work.
 | 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.
+renderable may sit on a fractional position WITHIN the frame. `syncToDisplay`
+is about the frames in a row rather than one frame: whether motion advances
+by the same amount on each.
 
 ## Design resolution
 
@@ -155,6 +157,42 @@ 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.
 
+## Drawn small: `textureFilter: "linear-mipmap"`
+
+A sprite drawn much smaller than its texture (a zoomed-out camera, a minimap,
+a scaled-down sprite) shimmers as it moves, even with linear sampling: each
+screen pixel covers many texels and linear sampling blends only four of them.
+`"linear-mipmap"` samples the texture's mipmaps, smaller copies averaged in
+advance, wherever something is drawn below its size:
+
+```js
+const app = new Application(1280, 720, { textureFilter: "linear-mipmap" });
+```
+
+At its size or larger a texture draws as it does under `"linear"`, so a game
+whose main view is at its size and whose minimap is zoomed out gets a smooth
+minimap and an unchanged view. It covers sprites, text and tile layers, not a
+video nor a texture the engine renders into, and a `nearest` texture keeps to
+its full size. GPU backends only; on WebGPU each texture it applies to takes
+about a third more memory.
+
+A small mipmap level's texels span many of the art's pixels, so a sample near
+the edge of a frame would reach into the next frame of the atlas. Under
+`"linear-mipmap"` every sprite and tile keeps its samples half a texel of the
+level it reads inside its own frame, so the next frame no longer streaks along
+its edges. Two limits:
+
+- a level's texel is an average of a square of the art, 2, 4, 8 pixels a side
+  and so on. Where a frame's edge falls inside such a square, its outermost
+  texel already holds some of the neighbour: drawn very small, a frame of an
+  atlas packed edge to edge can show a faint line of it. Frames on a grid of
+  a power of two (a 32 or 64 px sheet) are free of it, and a padding of a few
+  pixels between frames removes it elsewhere;
+- a sprite drawn through a `ShaderEffect` samples the texture in the effect's
+  own program, which is not kept to the frame.
+
+A repeating pattern is left to wrap.
+
 ## `subPixel` is about position, not scale
 
 `subPixel: false` (the default) truncates a renderable's translation to whole
@@ -168,6 +206,58 @@ 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.
 
+`subPixel: true` alone does not make motion smooth: with nearest sampling a
+sprite between two pixels is still drawn on one of them, so a scene moving
+4.5 pixels a frame jumps by 4 and 5 in turn. Rendered art (not pixel art)
+moves smoothly with `textureFilter: "linear"` as well, which blends it across
+the two, while the upscale stays crisp (`antiAlias: true` would also smooth the
+whole canvas as it is scaled up, which is what makes it look blurry). A still
+scene is only sharp when the camera rests on a whole pixel, so give it a
+target on whole pixels:
+
+```js
+const app = new Application(1280, 720, {
+	scale: "auto",
+	subPixel: true,
+	textureFilter: "linear",
+	syncToDisplay: true,
+});
+// the camera follows a point on whole pixels, kept on the hero: it glides
+// between pixels while following, and comes to rest on one
+const focus = new Vector2d();
+app.viewport.follow(focus, app.viewport.AXIS.BOTH, 0.12);
+
+// in the hero's update(dt)
+focus.set(Math.round(this.pos.x), Math.round(this.pos.y));
+```
+
+## `syncToDisplay` is about steady motion
+
+The game updates in fixed steps, 60 a second by default, as many as the time
+since the last frame holds. Browsers report that time with up to a millisecond
+of jitter, so on a 60 Hz display a frame now and then gets no update and the
+next one gets two: the world holds still for a frame, then moves twice as far.
+Scrolling, and anything else moving steadily, stutters while the frame rate
+reads a solid 60.
+
+```js
+const app = new Application(1280, 720, { scale: "auto", syncToDisplay: true });
+```
+
+With it on, frame times are counted in whole display frames and what is
+rounded off is carried to the next frame: one update every frame at 60 Hz, one
+every other frame at 120 Hz, and the game keeps its speed. A display within 2%
+of `timer.maxfps` (60 by default), or of 2, 3 or 4 times it, or a half, a third
+or a quarter of it, is counted at exactly that rate, so a 59.94 Hz screen runs
+the game 0.1% slower than the wall clock; leave it off when the updates must
+keep to the wall clock exactly. The display's rate is learned as the game runs,
+and again when it changes (the window moved to another screen). At a refresh
+that is no multiple of the update rate (144 Hz, 165 Hz) the steps cannot fall
+evenly however the time is counted.
+
+It is off by default. It sets `timer.syncToDisplay` when the application is
+initialized, which a game can also switch at any time.
+
 ## Soft text next to crisp sprites
 
 If everything is crisp EXCEPT the text, the scale factor is not the cause: a
@@ -266,6 +356,12 @@ const app = new Application(1024, 576, {
 | 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 |
+| scrolling stutters while the frame rate reads 60 | a frame now and then runs no update and the next two; set `syncToDisplay: true` |
+| moving rendered art jumps by whole pixels with `subPixel: true` | nearest sampling still draws it on one pixel; add `textureFilter: "linear"` |
+| the whole game looks blurry with `antiAlias: true` | it also smooths the canvas as it is scaled up; use `textureFilter: "linear"` instead |
+| a minimap or a zoomed-out view shimmers as it moves | linear sampling blends 4 texels where a pixel covers many; use `textureFilter: "linear-mipmap"` |
+| faint lines along sprites drawn small, from the next frame of the atlas | under `"linear-mipmap"` the built-in sprite shaders keep to the frame, but not a `ShaderEffect`'s own sample, and the smallest levels still mix a frame not on a power-of-two grid with its neighbour: pad the atlas |
+| a still scene looks a little soft with linear sampling | the camera rests between two pixels; follow a target rounded to whole pixels |
 | 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 |

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

@@ -110,16 +110,66 @@ 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`.
 
+**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.
+
+**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. 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
+sprite.addPostEffect(new OutlineEffect(app.renderer, { width: 2 }));
+```
+
+`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);
+```
+
+Rows are measured across the texture the effect samples, so on a sprite cut from
+an atlas the anchor is a row of the atlas: it suits a standalone image or a
+layer best.
+
 `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
@@ -178,9 +228,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 +509,38 @@ 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);
+- 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
@@ -650,6 +731,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-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,8 +169,9 @@ 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
@@ -171,7 +201,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-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

@@ -373,6 +373,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