melonjs 20.8.0 → 20.9.0

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

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

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

@@ -136,9 +136,9 @@ bright pixels bleed into their neighbours — and it is the one to put on the
 camera:
 
 ```js
-game.viewport.addPostEffect(new BloomEffect(app.renderer));
+app.viewport.addPostEffect(new BloomEffect(app.renderer));
 // only the brightest highlights, with a wider halo
-game.viewport.addPostEffect(
+app.viewport.addPostEffect(
     new BloomEffect(app.renderer, { threshold: 0.85, radius: 4 }),
 );
 ```
@@ -154,8 +154,8 @@ reads as a white sticker. `exposure` lifts the image into the curve, and the
 curve (`aces`, `reinhard` or `exponential`) is baked at construction:
 
 ```js
-game.viewport.addPostEffect(new BloomEffect(app.renderer));
-game.viewport.addPostEffect(
+app.viewport.addPostEffect(new BloomEffect(app.renderer));
+app.viewport.addPostEffect(
     new ToneMappingEffect(app.renderer, { exposure: 1.6 }),
 );
 ```

package/skills/melonjs-events/SKILL.md

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

package/skills/melonjs-input/SKILL.md

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