melonjs 20.11.0 → 20.13.0

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

@@ -1,6 +1,6 @@
 ---
 name: melonjs-camera-and-drawing
-description: "Use this skill for camera control and immediate-mode drawing in melonJS — following a target, viewport bounds, shake and fade, secondary cameras and 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."
+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, setGlobalAlpha, fillArc, Rect, Ellipse, Polygon, Line, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d, lookAt, setBasis, toImageData, getImageData, toBlob, toDataURL, screenshot, read pixels."
 license: MIT
 ---
 
@@ -143,6 +143,12 @@ app.viewport.worldToLocal(x, y);   // world → screen
 app.viewport.localToWorld(x, y);   // screen → world
 ```
 
+They agree with where the camera draws: a level smaller than the view is
+centred by offsetting the world container (`world.pos`), which the default
+camera draws and a minimap, corner or zoomed camera leaves out, and each
+camera's conversions follow suit (20.13 and later; before, a minimap's were off
+by `world.pos`).
+
 Both return a `Vector2d`; with no third argument that vector comes from the
 shared pool, so in a per-frame path pass your own `v` as the third argument, or
 release it with `getPool("vector2d").release(v)`.
@@ -205,6 +211,14 @@ and an overridden `postDraw`:
 this.cameras.set("minimap", new MinimapCamera());
 ```
 
+A stage's cameras draw in the order they were added, each over the ones before
+it, so a full-screen second camera is a layer: a `Camera3d` drawing a 3D
+background first, the game's own camera over it, each kept to its part of the
+world with `visibilityLayer` / `cullMask` (below). A camera's post effects
+apply to what that camera draws: the first camera's pass starts the frame, and
+a later camera's is blended over what is already there (20.13 and later;
+before, it wiped out the cameras before it).
+
 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`.
@@ -228,6 +242,9 @@ minimap.cullMask = ~PARTICLES;         // the minimap draws every layer but 2
   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.
+- Particles are on their emitter's layers, and follow a change to them on the
+  emitter's next update, so a camera that draws only the emitter's layer draws
+  its particles too.
 - 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
@@ -256,6 +273,23 @@ draw(renderer) {
 }
 ```
 
+**The colour's alpha and the global alpha are two things**, as on a 2D
+context. A fill or a stroke is drawn at the alpha of `setColor` times
+`setGlobalAlpha` (which is where the renderable's opacity comes in), an image at
+the global alpha (times the tint) alone, and `getGlobalAlpha()` never moves with
+`setColor`. So to fade a translucent shape, lower the global alpha and keep the
+colour; folding the colour's alpha into `setGlobalAlpha` as well counts it twice.
+
+`lineWidth`, `lineJoin`, the colour and the global alpha are all part of what
+`save()` / `restore()` keep, and every renderable's `draw()` runs between the
+two, so set them freely there: the next renderable gets them back.
+
+`fillArc` / `strokeArc` read their angles like `CanvasRenderingContext2D.arc`:
+an end before the start wraps round (`end + 2π`), and a span of 2π or more in
+the arc's own direction is the whole circle. A filled part-circle differs by
+backend, though: Canvas closes it with a straight chord, the GPU renderers fill
+a pie slice from the centre.
+
 Geometry available: `Rect`, `RoundRect`, `Ellipse`, `Polygon`, `Line`, `Point`
 (and a `Bounds`). `renderer.fill(shape)` and `renderer.stroke(shape)` take any
 of them and throw `Invalid geometry for fill/stroke` for anything else.
@@ -383,6 +417,7 @@ const data = await rt.toImageData(0, 0, w, h);
 
 | symptom | cause |
 |---|---|
+| a second camera's post effect wipes out what the first camera drew | before 20.13 a later camera's post-effect pass replaced the whole frame; update, or put the effects on a container instead of the camera |
 | `follow()` set but the view never moves | viewport bounds still at renderer size |
 | `invalid target for me.Camera2d.follow` | passed `player.pos` — pass the renderable, a `Vector2d` or a `Vector3d` |
 | camera drag jumps around | using world (`gameWorldX`) instead of screen (`gameScreenX`) coordinates |
@@ -390,6 +425,11 @@ const data = await rt.toImageData(0, 0, w, h);
 | custom drawing appears at the origin | `draw()` not reading `this.pos` |
 | custom drawing offset by half its size | centred `anchorPoint` not zeroed |
 | `setLineWidth` is not a function | it is the `lineWidth` property |
+| after a translucent `setColor`, images, later colours and the next renderables come out faded (WebGL / WebGPU) | before 20.13 the colour's alpha leaked into the global alpha; update |
+| a translucent colour comes out fainter than asked | its alpha folded into `setGlobalAlpha` as well, so it counts twice |
+| a `lineWidth` set in one `draw()` thickens everything drawn after it (WebGL / WebGPU) | before 20.13 `restore()` did not put `lineWidth` back; update, or put it back yourself |
+| `fillArc` with the end angle before the start fills the wrong part of the circle (WebGL / WebGPU) | before 20.13 the GPU renderers did not wrap the angles like Canvas; update |
+| a minimap's `worldToLocal` / `localToWorld` are off by the level's centring offset | before 20.13 they applied `world.pos`, which a non-default camera does not draw; update |
 | clipping in the wrong place inside a container | container clips in local coordinates, after its own translate |
 | `container.clipping = true` does nothing | container has no explicit size, so `width`/`height` are `Infinity` |
 | baked target draws nothing / throws | passed the `CanvasRenderTarget`, not its `.canvas` |

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

@@ -195,11 +195,25 @@ A repeating pattern is left to wrap.
 
 ## `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.
+`subPixel: false` (the default) draws everything on whole pixels. The snap
+happens **once, where a draw lands**, the same on every renderer: each edge of
+a sprite, a shape or a clip is rounded to the nearest pixel after every
+translation and scale it is drawn under. So:
+
+- nested containers add their positions up exactly first (10.6 then -6.5
+  lands on 4, the pixel 4.1 is in);
+- a flipped sprite covers the pixels it covers unflipped;
+- a sprite and a `fillRect` at the same position cover the same pixels, and a
+  shape has no half-grey edge on the Canvas renderer;
+- a position floating point error leaves a hair short of a pixel, such as a
+  body resting on the floor at `223.99999999999997` after a collision
+  push-out, draws on that pixel (224), so it does not shake every other frame.
+
+The camera's view starts on a whole pixel too, in world units (zoomed 2x, it
+moves in 2 px steps), and culling and the pointer use that same position:
+things standing still stay still against each other while the view scrolls,
+and a click lands on what is drawn under it. A rotated draw, and anything a
+`Camera3d` draws, is left where it is.
 
 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

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

@@ -138,18 +138,44 @@ 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. Do not pass `textureSize` to get this: 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
+// 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;
@@ -166,17 +192,18 @@ tree.addPostEffect(sway);
 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.
+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 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.
+`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
@@ -524,6 +551,10 @@ has changes nothing). What splits the batch:
 - 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.
 
@@ -603,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`
@@ -698,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.
 
@@ -723,6 +758,7 @@ same question after construction.
 
 | symptom | cause |
 |---|---|
+| a camera's post effect hides another camera drawn before it | before 20.13 a later camera's pass replaced the whole frame; update. Since then each camera's effects apply to what it draws, over the cameras before it |
 | effect does nothing, warning in console | Canvas fallback — no programmable pipeline |
 | effect does nothing on some machines only | GLSL-only shader, `video.AUTO` chose WebGPU |
 | a white or solid box where the effect should be | carrier renderable drawn while the effect is disabled |

package/skills/melonjs-events/SKILL.md

@@ -87,7 +87,7 @@ right times and there is nothing to unsubscribe:
 | callback | when |
 |---|---|
 | `onActivateEvent()` | `addChild`-ed into a container that is already attached to the world root (a `Container` forwards it to its children) |
-| `onDeactivateEvent()` | removed from its container — including the automatic world clear on a state change |
+| `onDeactivateEvent()` | removed from its container — including the automatic world clear on a state change. Once per `onActivateEvent`: the children of a removed container, at any depth, are told once |
 | `onDestroyEvent()` | `destroy()` ran; called with no arguments from the container-removal path |
 | `onCollisionStart` / `onCollisionActive` / `onCollisionEnd` | contacts |
 
@@ -154,6 +154,8 @@ Use `removeChild()`, or flag the work and drain it from `Stage.update`.
 | 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 |
+| `onDeactivateEvent` runs twice when a group is removed (a count goes negative, a light or listener is released twice) | the group's `onDeactivateEvent` and its `destroy()` both reached the children, before 20.13.0 — now once per `onActivateEvent` |
+| `onDeactivateEvent` never runs on a child of a group built off-world and destroyed | it never had `onActivateEvent` either: the pair is only sent to children that entered the world |
 
 ## Related skills
 

package/skills/melonjs-getting-started/SKILL.md

@@ -137,7 +137,6 @@ with the formats you ship before any audio asset is preloaded.
 ```js
 import { audio, loader } from "melonjs";
 
-loader.setOptions({ crossOrigin: "anonymous" });   // needed for remote assets
 audio.init("mp3,ogg");                             // BEFORE preloading audio
 await loader.preload([
     { name: "tileset", type: "image", src: "data/img/tileset.png" },
@@ -173,7 +172,7 @@ placement.
 | scene content appears once and never resets | scene built in the constructor instead of `onResetEvent` |
 | everything offset by half a sprite | top-left math against the centred `anchorPoint` default |
 | a `Tween` or `ParticleEmitter` does nothing | `.start()` / `streamParticles()` never called |
-| cross-origin textures fail to load | missing `loader.setOptions({ crossOrigin: "anonymous" })` |
+| an asset on another origin fails to load, the error naming it | that server sends no `Access-Control-Allow-Origin` header (see melonjs-loading-assets) |
 
 ## Related skills
 

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, floating stick, floating button, floating joystick, two thumbs, tap to fire, hideAtRest, mobile controls, 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,60 @@ 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).
+
+Sticks and buttons are fixed in a corner by default. **`floating: true`**
+puts one under the finger wherever it lands inside its `area` (`"half"`, its
+own half of the screen, by default; `"screen"`; or `{ x, y, width, height }`),
+and **`hideAtRest: true`** draws it only while held. The usual mobile
+two-thumb layout, nothing on screen until touched (1.1):
+
+```js
+plugin.register(GamepadPlugin, "gamepad", {
+    sticks: [{ floating: true, hideAtRest: true }],                 // left half
+    buttons: [{ floating: true, hideAtRest: true, label: "A" }],    // right half
+});
+```
+
+Or one thumb for both: a stick over the whole screen whose quick tap (lifted
+within `tap.time`, 250 ms, without leaning to `dpadThreshold`) presses a key
+or button for one frame, and no button at all:
+
+```js
+plugin.register(GamepadPlugin, "gamepad", {
+    sticks: [{ floating: true, area: "screen", hideAtRest: true,
+               tap: { key: input.KEY.SPACE } }],
+    buttons: 0,
+});
+```
+
+Where areas overlap, a finger takes the first free control there: fixed
+buttons, fixed sticks, floating buttons, floating sticks. So a floating button
+on its `"half"` carves the right half out of a `"screen"` stick, and several
+floating buttons sharing an area split it by distance to where each rests.
+Every press lasts at least one frame, so a 15 ms thumb tap still reaches
+`isKeyPressed`, and Safari's pinch gesture is cancelled while the controls
+show, so a second thumb works on iOS.
+
+A single key can also be pressed directly, reaching the same actions:
 
 ```js
 input.triggerKeyEvent(input.KEY.LEFT, true);    // press
@@ -293,12 +346,17 @@ 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 |
+| floating stick ignores the right half of the screen | its `area` defaults to `"half"`, its own side — use `area: "screen"` |
+| `area: "screen"` stick still ignores part of the screen | a floating button's area comes first there — the overlap order is fixed buttons, fixed sticks, floating buttons, floating sticks |
+| a quick tap on a stick moves instead of acting | it leaned past `dpadThreshold` or outlasted `tap.time` before lifting |
 | 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 under an overlapping panel still lights up | the panel consumes no hover: return `false` from its `onOver` (presses already stop at UI elements; `UIPanel` with `blocking` does both) |
 | 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

@@ -174,9 +174,10 @@ 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) {

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

@@ -13,8 +13,6 @@ Every asset is `{ name, type, src }` plus type-specific extras:
 ```js
 import { loader } from "melonjs";
 
-loader.setOptions({ crossOrigin: "anonymous" });   // needed for remote assets
-
 await loader.preload([
     { name: "tiles",   type: "image",    src: "data/img/tiles.png" },
     { name: "map1",    type: "tmx",      src: "data/map/map1.tmx" },
@@ -183,7 +181,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 +194,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.
@@ -348,6 +347,20 @@ event.on(event.LOADER_COMPLETE, () => { /* … */ });
 event.on(event.LOADER_ERROR, (res) => { /* … */ });
 ```
 
+**Each `preload()` has only its own callback.** One given none calls nothing
+on completion, so a later `await loader.preload(levelAssets)` does not re-run
+the boot callback. Before 20.13 the loader kept the last callback it was given
+and called it again for a preload that had none — usually a `state.change`
+straight back to the first screen. `loader.reload(src)` after a failure
+completes the preload that asset failed in, with that preload's callback, once
+all of its assets are in.
+
+**Progress is per preload:** `LOADER_PROGRESS` goes from that call's first
+asset to `1` with its last, every time. A preload started while another is
+still loading joins it, and the value covers both until everything in flight
+has settled; the next preload starts from zero again. A failed asset keeps
+its preload short of `1`, and only that preload.
+
 ## Unloading
 
 ```js
@@ -376,20 +389,45 @@ state.change(state.PLAY, true);
 
 ## Cross-origin and authenticated assets
 
-Two settings, both global and both applying to **every** asset type — there is
-no per-asset or per-type spelling to remember:
+**Nothing to set for the usual cases.** Every fetched asset (image, json,
+binary, tmx, tsx, shader, gltf/glb, obj, mtl, aseprite, buffered audio) is
+requested the same way:
+
+- **On the game's own origin**, it carries the browser's cookies and HTTP
+  auth, as the page and its scripts do. A game behind a login or a session
+  cookie loads its own assets with no option.
+- **On another origin** (a CDN), it is a CORS request: it loads when that
+  server sends `Access-Control-Allow-Origin`, and fails at load when not, with
+  an error naming the asset and the header it needs. No `crossOrigin` needed.
+
+| asset on… | default | `withCredentials: true` |
+|---|---|---|
+| the game's own origin | loads, with its cookies | loads, with its cookies |
+| another origin sending `Access-Control-Allow-Origin` | loads, no cookies | **blocked** if it answers `*`; needs the page's exact origin plus `Access-Control-Allow-Credentials: true` |
+| another origin allowing credentials for the page | loads, no cookies | loads, with that origin's cookies |
+| another origin with no CORS headers | fails at load, naming the asset | fails at load, naming the asset |
+
+Two global settings cover the rest, for every asset type — there is no
+per-asset or per-type spelling to remember:
 
 ```js
 loader.setOptions({
-    crossOrigin: "anonymous",   // CORS mode for remote assets
-    withCredentials: true,      // send cookies / auth with the request
+    withCredentials: true,      // send cookies / auth to OTHER origins too
+    crossOrigin: "anonymous",   // attribute of the <video>, <script> and glTF
+                                // image elements the loader creates
 });
 ```
 
-`withCredentials` is what an asset behind a session cookie or an
-`Authorization`-style login needs. Every fetched asset — image, json, binary,
-tmx, tsx, shader, gltf/glb, obj, mtl, aseprite, video — carries it, and so does
-buffered audio.
+`withCredentials` is for assets on **another** origin behind a session cookie
+or a login; that server must then allow credentials for the page's origin, or
+the browser blocks the request. `crossOrigin: "use-credentials"` does the same
+for fetched assets, and sets the attribute on the elements.
+
+Before 20.13 both were needed far more often: assets on the game's own origin
+went out with no cookies unless `withCredentials` was set (a 401 or 403 behind
+a login), and an asset on another origin without `crossOrigin: "anonymous"`
+was read as an empty response, failing later with "Unexpected end of input" or
+"The source image could not be decoded" even when its server allowed it.
 
 **Set them through `setOptions`.** `loader.crossOrigin` and
 `loader.withCredentials` are read-only module bindings; assigning to them
@@ -397,7 +435,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
@@ -407,13 +445,17 @@ throws, the same trap as the removed `loader.onload` / `onProgress`.
 | audio 404s | `src` given as a file instead of a directory |
 | audio fails, `preload()` rejects with "Failed loading resource" | `audio.init()` not called before preloading — the real message is replaced by the loader's |
 | blank level, missing tiles | `.tsx` or tileset image not listed in the resources |
-| cross-origin textures fail | missing `loader.setOptions({ crossOrigin: "anonymous" })` |
-| assets behind a login 401 / audio preload hangs | missing `loader.setOptions({ withCredentials: true })` — one switch, all asset types |
+| `Failed to load "…" (Failed to fetch). An asset on another origin loads only if its server allows it…` | that origin sends no `Access-Control-Allow-Origin` header — or, with `withCredentials`, sends `*` or no `Access-Control-Allow-Credentials: true`. Fix the server's headers, or serve the asset from the game's own origin |
+| an asset on another origin behind a login 401s / audio preload hangs | missing `loader.setOptions({ withCredentials: true })` — one switch, all asset types. Assets on the game's own origin need nothing (before 20.13 they needed it too) |
+| a remote JSON fails with "Unexpected end of input", or an image with "The source image could not be decoded" | melonJS before 20.13, which read assets on another origin without CORS unless `crossOrigin: "anonymous"` was set |
 | `TypeError` assigning `loader.withCredentials` / `crossOrigin` | read-only module bindings; use `loader.setOptions({ … })` |
 | preload never finishes, blank screen, no error | a failing sound with `audio.setStopOnAudioError(false)` before 20.4 — it disabled audio *and* failed the preload |
 | text renders in a fallback font | web font not preloaded as `"fontface"` |
 | `BitmapText` renders nothing | the `.fnt` (as `"binary"`) or its image is missing |
 | `TypeError` assigning `loader.onProgress` / `onload` | removed in 20.3; they were never writable — use the `LOADER_*` events |
+| `await loader.preload(level)` sends the game back to its title screen, or runs the boot setup twice (before 20.13) | a preload with no callback re-ran the previous preload's callback; update, each preload now calls only its own |
+| the loading bar starts part-full on a second preload, or never reaches the end after one asset failed (before 20.13) | the progress counters ran for the whole session; update, progress is per preload |
+| `loader.reload(src)` of a custom asset type throws `unload : unknown or invalid resource type` (before 20.13) | update: a type registered with `setParser` can now be retried |
 | `load : unknown or invalid resource type` | a custom type in the manifest before its `loader.setParser` call |
 | black or frozen screen when a stage is first entered, the profile shows your own code (noise, a canvas bake) | a costly derived asset built on stage entry — bake it inside the preload as a [custom asset type](#custom-asset-types) |
 | a custom asset preloads but the result is nowhere to be found | `onload` takes no value and the loader stores nothing for custom types — keep the result in your own module |

package/skills/melonjs-math/SKILL.md

@@ -187,13 +187,22 @@ which is how a renderable knows its bounds went stale.
 
 ```js
 v.setCallback(() => { ... });
-v.setMuted(true);     // write without firing it
+v.setMuted(x, y, z);  // write without firing it
+v.setCallback(undefined); // stop observing
 ```
 
 **`setMuted` is what you want when writing several components**, so a
 half-updated vector does not fire a callback that reads the other half.
 `set()` already does this internally: it disables the callback, writes all
-three, fires once, and re-enables.
+three, fires once, and re-enables. Every mutating method (`add`, `scale`,
+`negateSelf`, `floorSelf`, `clampSelf`, `normalize`, `lerp`, …) goes through
+`set()`, so it fires once and returns the observable vector itself. Before
+20.13 `negateSelf`, `floorSelf`, `ceilSelf` and `clampSelf` (and the 3D
+`normalize` and `perp`) fired once per component and returned the wrapped
+plain vector instead.
+
+`clone()` takes from a pool, and gets the callback you pass it or none: before
+20.13 a recycled clone kept the callback of the vector released before it.
 
 Note the observable `set(x = 0, y = 0, z = 0)` defaults EVERY argument, so
 `set(10, 20)` zeroes z exactly as the plain vector does.
@@ -286,7 +295,7 @@ math.degToRad(deg);  math.radToDeg(rad);
 math.random(lo, hi);             // integer
 math.randomFloat(lo, hi);
 math.weightedRandom(lo, hi);     // integer, biased toward LO
-math.round(n, decimals);
+math.round(n, decimals);        // nearest; a tie goes up, as Math.round: -2.5 → -2
 math.pow(n);                     // n squared
 math.DEG_TO_RAD  math.RAD_TO_DEG  math.TAU  math.ETA  math.EPSILON
 ```
@@ -317,6 +326,8 @@ and `Math.random()` every frame jitters instead of drifting.
 | z unchanged after scaling | `scale(s)` leaves z alone; pass `scale(s, s, s)` |
 | z became 0 for no reason | `set(x, y)` defaults z to 0 |
 | the original vector changed | the method mutates; `copy()` into something first |
+| a position callback fires twice and sees a half-updated vector, or `pos.floorSelf()` returns something that is not `pos` | before 20.13 the observable `negateSelf` / `floorSelf` / `ceilSelf` / `clampSelf` wrote component by component; upgrade |
+| `math.round(-2.7)` is -2, or a large value comes back negative | before 20.13 `round` truncated toward zero through 32-bit integers; upgrade |
 | memory climbs in a loop | `clone()` or `negate()`/`floor()`/`ceil()` per frame |
 | two helper results are the same object | a shared scratch vector was returned |
 | `.z` is a type error | `Renderable.pos` is declared `Vector2d` (#1510) |