melonjs 20.7.0 → 20.9.0

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, world vs screen pointer coordinates, and gamepad mapping onto the same actions. Triggers on: input, bindKey, isKeyPressed, KEY, registerPointerEvent, releasePointerEvent, pointerdown, pointerup, POINTERMOVE, gamepad, bindGamepad, triggerKeyEvent, click, touch, drag."
+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
@@ -64,9 +89,11 @@ subclasses with no body are the ones that catch people.
 Register in `onActivateEvent` and release in `onDeactivateEvent`, not in the
 constructor — pooled objects are reused and would otherwise accumulate handlers.
 
-`app.viewport` works as a whole-screen region when you want global clicks: the
-dispatcher appends it to the candidate list on every event, so it is reachable
-even when nothing else is under the pointer.
+`app.viewport` works as a whole-screen region when you want global clicks. Note
+it is asked **before** everything else, not as a fallback after nothing matched:
+the dispatcher appends it to the candidate list and walks that list from the
+end. So a viewport handler must not return `false` unless it really means to
+swallow every pointer event in the game.
 
 The accepted event names are exactly `"pointerdown"`, `"pointerup"`,
 `"pointermove"`, `"pointercancel"`, `"pointerenter"`, `"pointerover"`,
@@ -76,6 +103,44 @@ throw `invalid event type`. melonJS maps the canonical name onto whichever
 mouse/touch events the device actually supports, so you always register the
 pointer name.
 
+## Which object gets the event
+
+The dispatcher collects the regions near the pointer from the broadphase,
+bounds-checks each one, orders them **the way they are drawn** and asks the
+topmost first, walking down until something consumes.
+
+A handler consumes by returning `false`. This is the DOM sense and it reads
+backwards: `false` means handled, and anything else, `undefined` included, lets
+the walk carry on to whatever is underneath.
+
+```js
+input.registerPointerEvent("pointerdown", this, () => {
+    this.fire();
+    return false;        // nothing under this gets the click
+});
+```
+
+Three things decide the order, and only the first is obvious:
+
+- **`pos.z`, among siblings of one container.** Higher is on top.
+- **Across containers, the common ancestor decides.** `pos.z` is
+  container-local, since `autoDepth` numbers each container's children from 1,
+  so a button at `z = 8` inside one panel does not outrank a second panel at
+  `z = 2`. The pair is resolved by walking both up to their shared parent and
+  comparing the two siblings there, which is exactly how drawing resolves it.
+  Raise a whole panel with `ancestor.moveToTop(panel)`, not by inflating a
+  child's `z`.
+- **A child is asked before the container holding it**, since it draws over it.
+
+Equal `z` between siblings falls back to child order, lower index on top. Two
+callbacks registered on the **same** region for the same event run
+last-registered-first.
+
+Consuming a **move** also takes the pointer away from the regions below: each
+one still holding it gets its `pointerleave`, because it is covered now and
+being inside its own bounds no longer decides. Consuming a press, a release or a
+wheel does not, since none of those says where the pointer is.
+
 ## World coordinates versus screen coordinates
 
 The pointer carries several, and picking the wrong one produces a feedback loop:
@@ -132,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:
@@ -159,6 +293,12 @@ 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 |
+| every click in the game stops working | a handler on `app.viewport` returning `false`, which is asked first |
 
 ## Related skills
 

package/skills/melonjs-math/SKILL.md

@@ -0,0 +1,313 @@
+---
+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."
+license: MIT
+---
+
+# Vectors, matrices and maths
+
+## The one rule that explains most surprises
+
+**Methods mutate `this` and return it. They do not return a new vector.**
+
+```js
+const a = new Vector3d(1, 0, 0);
+const b = new Vector3d(0, 1, 0);
+
+a.cross(b);        // a IS NOW the cross product; the original a is gone
+a.add(b).normalize().scale(3, 3, 3);   // chains, all in place
+```
+
+That is what makes the API allocation-free, and it is the opposite of what a
+functional style expects. If you need to keep the original, copy into
+something you own first:
+
+```js
+out.copy(a).cross(b);    // a untouched, nothing allocated
+```
+
+**The exceptions are named.** A handful of methods return a NEW vector, and
+each has a `*Self` sibling that does not:
+
+| allocates a new vector | mutates in place |
+|---|---|
+| `negate()` | `negateSelf()` |
+| `floor()` | `floorSelf()` |
+| `ceil()` | `ceilSelf()` |
+| `clamp(low, high)` | `clampSelf(low, high)` |
+| `clone()` | `copy(v)` |
+
+So `v.negate()` in a per-frame loop allocates every frame and `v.negateSelf()`
+does not. The names are the only clue; nothing in the call site shows it.
+
+## `clone()` comes from a pool, and only pays off if you give it back
+
+`clone()` is `vector3dPool.get(...)`. A pool is fast when instances come back:
+`get()` takes a free one and resets it. Nothing comes back on its own, so a
+clone that is simply dropped makes `get()` miss, construct, and write two
+registry entries.
+
+Measured, 3M operations:
+
+| | |
+|---|---|
+| `out.copy(a).cross(b)` | 39ms |
+| `new Vector3d(ax, ay, az).cross(b)` | 37ms |
+| `a.clone().cross(b)` | **2919ms** |
+
+So:
+
+- **Transient value inside a function?** Use a module-level scratch vector, or
+  `new Vector3d()`. Not `clone()`.
+- **Keeping it, then done with it?** `clone()` and `vector3dPool.release(v)`
+  when finished. Releasing is what makes the pool a pool.
+- **Writing a helper that returns a vector?** Take an optional `out`:
+
+```js
+const cross = (a, b, out = new Vector3d()) => out.copy(a).cross(b);
+```
+
+That is the engine's own convention, and it lets a hot caller supply scratch
+while a casual one ignores it.
+
+**A returned value can never be shared scratch.** The next call overwrites
+something the caller is still holding, and nothing fails loudly:
+
+```js
+const _t = new Vector3d();
+const bad = (v) => _t.copy(v).normalize();   // WRONG: two calls alias
+```
+
+## Argument defaults that drop a component
+
+Three signatures quietly discard what you did not pass. All three are
+reachable by writing the obvious thing.
+
+**`scale(x, y = x, z = 1)`** — `z` defaults to **1**, not to `x`. A uniform
+scale has to say so three times:
+
+```js
+v.scale(2);          // (1,2,3) -> (2,4,3)   z UNTOUCHED
+v.scale(2, 2, 2);    // (1,2,3) -> (2,4,6)   what you meant
+```
+
+**`set(x, y, z = 0)`** — setting two components **zeroes the third**:
+
+```js
+v.set(10, 20);       // z is now 0, whatever it was
+```
+
+**`Vector3d.pos` on a renderable is typed `Vector2d`.** `Renderable.pos` is an
+`ObservableVector3d` at run time but is declared through `Polygon` as a
+`Vector2d`, so `.z`, `.setMuted` and `.setCallback` need a cast from
+TypeScript. See issue #1510.
+
+## `cross` is two different functions
+
+```js
+v3.cross(other);   // Vector3d: MUTATES v3, returns this
+v2.cross(other);   // Vector2d: returns a NUMBER, mutates nothing
+```
+
+The 2D one is the z component of the 3D cross, which is the useful scalar for
+"which side is this on". Same name, different shape, different return.
+
+## Interpolation: four of them, and they are not interchangeable
+
+```js
+a.lerp(b, t);            // straight line, t in 0..1
+a.slerp(b, t);           // along the ARC, constant angular rate
+a.damp(b, lambda, dt);   // frame-rate independent ease toward b
+a.moveTowards(b, step);  // fixed distance per call, never overshoots
+```
+
+**`moveTowards` is X/Y ONLY, on `Vector3d` as well as `Vector2d`.** It is the
+one of the four that is not 3D: it measures the distance from `dx` and `dy`,
+steps along `atan2(dy, dx)`, and leaves `z` exactly where it was. The source
+says so in a comment and the JSDoc says "on the x and y axis", but the name
+gives no hint, and in a list like the one above it reads as the sibling of the
+other three. Anything moving in three dimensions wants `damp` or an explicit
+step; reach for `moveTowards` only when the motion really is planar.
+
+**`lerp` between two directions is uneven**: it slows at the ends, runs fast
+through the middle, and shortens the vector as it passes halfway. Anything
+whose direction matters more than its components wants `slerp` — a camera
+swinging to look somewhere, a turret tracking, a body moving over a sphere.
+`slerp` carries length linearly, so two unit vectors give a unit vector and
+nothing needs normalising afterwards.
+
+**`damp` is the one to use for "ease toward a target every frame"**, because
+`lerp(current, target, 0.1)` per frame is frame-rate dependent: it converges
+twice as fast at 120fps as at 60.
+
+## `project` scales THIS, and `projectN` is the one without the divide
+
+`a.project(b)` does not return the component of `a` along `b`. It scales **a**
+by `a.b / |b|^2` and returns `a`, so the result points along `a`, not along
+`b`. Worth knowing before you reach for it expecting the textbook projection.
+
+`projectN(v)` is the same thing for a `v` that is already unit, so it skips
+the `/ v.length2()`:
+
+```js
+a.project(b);   // a scaled by (a.b / |b|^2)
+a.projectN(b);  // a scaled by (a.b)      -- only correct when |b| = 1
+```
+
+Handing `projectN` a target that is NOT unit does not normalise anything, it
+just scales by the raw dot product. That is the price of it being cheaper, and
+it is the caller's job to meet the contract.
+
+Until 20.9 both 3D classes got this wrong: `Vector3d.projectN` and
+`ObservableVector3d.projectN` were copies of `project`, division and all,
+under `projectN`'s name and its "slightly more efficient" doc comment. Nothing
+in the engine called either one and nothing tested them, which is how it
+survived. Both are fixed and all four classes are now pinned by tests.
+
+## `length()` is `sqrt(x*x + y*y + z*z)`
+
+Fast and correct to 1 ULP for anything a game holds. It is NOT robust at
+extremes: components above ~1e154 overflow to `Infinity` and below ~1e-162
+underflow to `0`, because the squares are formed before the root. `Math.hypot`
+avoids that and costs 35 to 65% more. The engine takes the speed, which is the
+right trade for coordinates between 1e-3 and 1e6; nothing in a game is 148
+orders of magnitude from unit scale.
+
+`length2()` skips the square root. Use it for comparisons:
+
+```js
+if (a.distance(b) < r) { }            // a square root you did not need
+if (a.sub(b).length2() < r * r) { }   // same answer, cheaper
+```
+
+## Observable vectors
+
+`ObservableVector2d` / `ObservableVector3d` call a callback on every write,
+which is how a renderable knows its bounds went stale.
+
+```js
+v.setCallback(() => { ... });
+v.setMuted(true);     // write without firing it
+```
+
+**`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.
+
+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.
+
+## Matrices
+
+`Matrix2d` is 3x3 for 2D affine transforms; `Matrix3d` is 4x4. Both mutate and
+chain, same as vectors, and both come from pools.
+
+```js
+m.identity().translate(x, y).rotate(angle).scale(sx, sy);
+```
+
+**Order is the reverse of how it reads.** These post-multiply, so the call
+made LAST reaches the vertex FIRST. To rotate a thing about its own centre,
+translate to the centre last.
+
+### Every renderable already HAS one
+
+`Renderable.currentTransform` is a `Matrix3d`. If you are orienting something
+on screen, the matrix exists: write into it rather than building a parallel
+structure and copying.
+
+```js
+// the whole transform of a renderable, written in place
+mesh.currentTransform.identity().translate(x, y, z).rotate(angle, axis);
+```
+
+### The sixteen numbers are `val`, column-major
+
+Composing with `translate`/`rotate`/`scale` is one way to fill a matrix. The
+other is to write the numbers, which is what you want when the orientation
+comes from a basis you have already computed — three orthonormal vectors, a
+surface frame, a camera basis.
+
+`val` is a `Float32Array(16)` in **column-major** order, the OpenGL
+convention: each basis vector occupies a stride-4 run, and the translation is
+the last column.
+
+| | X column | Y column | Z column | translation |
+|---|---|---|---|---|
+| indices | `0,1,2` | `4,5,6` | `8,9,10` | `12,13,14` |
+
+```js
+// an orientation from three axes, straight into the renderable's own matrix
+const m = mesh.currentTransform.val;
+m[0] = right.x;   m[1] = right.y;   m[2] = right.z;   m[3] = 0;
+m[4] = up.x;      m[5] = up.y;      m[6] = up.z;      m[7] = 0;
+m[8] = fwd.x;     m[9] = fwd.y;     m[10] = fwd.z;    m[11] = 0;
+m[12] = 0;        m[13] = 0;        m[14] = 0;        m[15] = 1;
+```
+
+A helper that builds one should take the destination, the same way the engine
+takes an `out`, so it writes once into the matrix that will be used:
+
+```js
+const orient = (frame, out) => { /* writes out.val */ return out; };
+orient(frame, mesh.currentTransform);
+```
+
+### Getting numbers IN from somewhere else
+
+`setTransform(...)` takes the sixteen as arguments, and `copy(m)` takes
+another matrix:
+
+```js
+m.setTransform(a, b, c, d, e, f, g, h, i, j, k, l, p, q, r, s);
+m.copy(other);                 // Float32Array.set under the hood
+```
+
+Both are fine occasionally. In a per-frame loop, prefer writing `val` or
+`copy()` over spreading sixteen arguments, and note that **one matrix built
+once and applied to many renderables** is a `copy()` per renderable, not a
+rebuild per renderable.
+
+**`val` is `Float32Array`, so it holds float32.** Numbers you put in are
+rounded to single precision. That is where they were always heading, since
+this is what reaches the GPU, but it means a value read back out is not
+bit-identical to the double you wrote.
+
+## Utilities
+
+```js
+import { math } from "melonjs";
+
+math.clamp(v, lo, hi);
+math.lerp(a, b, t);              // scalars
+math.damp(a, b, lambda, dt);     // frame-rate independent
+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.pow(n);                     // n squared
+math.DEG_TO_RAD  math.RAD_TO_DEG  math.TAU  math.ETA  math.EPSILON
+```
+
+## Symptoms
+
+| symptom | cause |
+|---|---|
+| 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 |
+| 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) |
+| rotation eases oddly between directions | `lerp` on directions; use `slerp` |
+| 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` |
+
+## Related skills
+
+- `melonjs-3d` — `Camera3d`, meshes, and where these vectors are used in 3D
+- `melonjs-physics` — bodies, velocities and collision response
+- `melonjs-performance` — pooling in general, and what release() is for