melonjs 20.6.0 → 20.8.0

package/skills/melonjs-scenes-and-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-scenes-and-state
-description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Stage, state, state.set, state.change, state.transition, state.pause, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze."
+description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Tween, easing, fade out, flash, pulse, punch, shrink back, ease in, ease out, animate over time, countdown in update, Stage, state, state.set, state.change, state.transition, state.pause, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze."
 license: MIT
 ---
 
@@ -165,6 +165,18 @@ Returning nothing is falsy and the object can appear frozen while its state move
 `dt` is milliseconds since the last frame and is the right basis for motion —
 the engine already paces it. Do not reach for `performance.now()`.
 
+**Smooth a value toward a target with `math.damp`, not with `lerp` per
+frame.** `lerp(current, target, 0.1)` once per frame moves further on a slow
+frame than on a fast one, so the feel drifts with the frame rate:
+
+```js
+this.speed = math.damp(this.speed, targetSpeed, 5, dt / 1000);
+```
+
+`damp(current, target, lambda, dt)` takes SECONDS, so divide `dt`. Higher
+`lambda` converges faster. See `melonjs-camera-and-drawing` for the camera's
+own `follow()` damping, which is already frame-rate independent for you.
+
 A common idiom for a per-frame game controller with nothing to draw is a
 `Renderable(0, 0, 1, 1)` with `alwaysUpdate = true` and an empty `draw()`.
 
@@ -191,6 +203,59 @@ countdown that should not freeze needs. (That argument was ignored by
 
 ## Tweens
 
+### You are hand-rolling a tween if you write this
+
+The shape, in any of its spellings. If you are adding a field that counts
+milliseconds and dividing it by a constant to get a `0..1`, stop:
+
+```js
+// ✗ a tween, written out longhand
+private flashMs = 0;
+// ... in update(dt)
+if (this.flashMs > 0) {
+    this.flashMs -= dt;
+    const k = this.flashMs / FLASH_MS;      // ← the 0..1
+    effect.setUniform("uIntensity", k * k); // ← and a curve, by hand
+}
+```
+
+```js
+// ✓ the same thing
+const driver = { k: 1 };
+new Tween(driver)
+    .to({ k: 0 }, { duration: FLASH_MS })
+    .easing(Tween.Easing.Quadratic.In)      // the curve, named
+    .onUpdate(() => effect.setUniform("uIntensity", driver.k))
+    .start();
+```
+
+The tells, any one of which is enough: a `*Ms` or `*Age` field that only
+`update()` touches; a division by a `*_MS` constant; `k * k`, `(1 - k) ** 2` or
+`** 1.4` written inline, which is an easing curve spelled by hand; an
+`if (x <= 0)` arm that exists only to clean up at the end, which is
+`onComplete`; a second timer counting the same duration to chain what happens
+next, which is `delay`.
+
+It matters beyond tidiness: a hand-rolled fade needs something to tick it, and
+an effect that is NOT a renderable (one living on the camera, say) has nothing
+that will. That forces an `update(dt)` method and a call site in the game loop
+whose only job is to drive the fade. A tween updates itself, so both disappear.
+
+### When NOT to reach for one
+
+Four shapes that look similar and are not tweens:
+
+| shape | what it is | use |
+| --- | --- | --- |
+| approaching a value that keeps MOVING | a follow, not an animation | `math.damp` |
+| a loop that never ends | oscillation | a sine of your own clock |
+| a gate: cooldown, spawn interval, invulnerability window | a timer, nothing is interpolated | a plain countdown |
+| the same effect on dozens of live objects | per-instance churn | a hand-rolled countdown really is cheaper |
+
+The rule in one line: **fixed duration, known endpoint, one-shot, few
+instances.** All four, or it is not a tween.
+
+
 ```js
 import { Tween, pool } from "melonjs";
 
@@ -216,6 +281,61 @@ Four traps:
 - **Stop a tween before destroying its target**, or `onUpdate` fires against a
   dead renderable.
 
+**To animate something that is not a property, tween a holder and push the
+value in `onUpdate`.** A shader uniform and a light's intensity are both set
+through a method, so there is nothing for `to()` to interpolate directly. The
+callback is invoked with the tweened object as `this` and the eased progress
+`0..1` as its argument:
+
+```js
+const fade = { level: 1 };
+pool.pull("Tween", fade)
+    .to({ level: 0 }, { duration: 400 })
+    .easing(Tween.Easing.Quadratic.Out)
+    .onUpdate(function () {
+        effect.setUniform("uIntensity", this.level);
+        muzzleLight.intensity = this.level * 3;
+    })
+    .start();
+```
+
+Use a `function`, not an arrow, if you want `this` to be the tweened object;
+an arrow keeps the enclosing `this` and you read the holder by name instead.
+For a handful of pooled objects a hand-rolled countdown in `update()` is
+cheaper than a `Tween` each — this is the right tool for one-off effects, not
+for every particle.
+
+### Pick the easing, not just the duration
+
+Eleven families, each with `In`, `Out` and `InOut`. `Out` is what most UI
+wants: the value arrives decisively instead of creeping in. The two worth
+knowing by name beyond the power curves:
+
+| family | what it does |
+| --- | --- |
+| `Back` | **overshoots past the target and settles back**, which is impact: a stamp, a button press, anything that should LAND rather than arrive |
+| `Bounce` | lands and bounces, for something dropping onto a surface |
+
+```js
+// a stamp: scale falls to 1 and springs through it
+const driver = { scale: 5 };
+new Tween(driver)
+    .to({ scale: 1 }, { duration: 420 })
+    .easing(Tween.Easing.Back.Out)
+    .onUpdate(() => { label.currentTransform.identity(); label.scale(driver.scale); })
+    .onComplete(() => camera.shake(12, 400))     // the thump, when it truly lands
+    .start();
+```
+
+`Back` and `Elastic` **leave the range** between your start and end, so clamp
+anything that cannot take it, an opacity or a colour channel above all. The
+overshoot follows the direction of travel: a value tweened DOWN overshoots
+below its target.
+
+Reach for `onComplete` for anything that must happen on arrival, rather than a
+second timer counting the same duration. `delay` in the `to()` options chains
+the next one without a timer either.
+
 ## Guard teardown-adjacent callbacks
 
 Callbacks can fire while a stage is being torn down, when the current state is

package/skills/melonjs-tilemaps/SKILL.md

@@ -100,6 +100,15 @@ melonJS pre-registers `Renderable`, `Sprite`, `NineSliceSprite`, `Text`,
 `BitmapText`, `ImageLayer`, `ColorLayer`, `Light2d`, `Collectable` and `Trigger`
 as Tiled classes, so `Collectable` and `Trigger` work out of the box.
 
+A `Trigger` forwards a **fixed list** of settings to `level.load()` — not
+whatever you pass it. Today that list is `container`, `onLoaded`, `flatten`,
+`setViewportBounds` and the glTF scene options (`scale`, `rightHanded`,
+`lights`, `lightIntensityScale`, `castGroundShadow`, `shadowGroundY`); see the
+3D assets skill. Anything outside it is **dropped silently**, which is worth
+knowing before you spend an afternoon on a map that loads at the wrong scale.
+`async` is excluded deliberately — the trigger needs to sequence its own
+transition.
+
 ## Camera bounds
 
 `level.load` sets the viewport bounds to the map size for you —

package/skills/melonjs-ui-and-text/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-ui-and-text
-description: "Use this skill for HUDs, buttons, menus, dialogue panels and on-screen text in melonJS. Covers UIBaseElement/UISpriteElement/UITextButton, Draggable and DropTarget, the floating screen-space container pattern, Text and BitmapText, web font loading, and NineSliceSprite panels. Triggers on: UI, HUD, button, UIBaseElement, UISpriteElement, UITextButton, Draggable, DropTarget, menu, dialogue, Text, BitmapText, font, fontface, wordWrapWidth, NineSliceSprite, score display, floating."
+description: "Use this skill for HUDs, buttons, menus, dialogue panels, progress bars and on-screen text in melonJS. Covers UIBaseElement/UISpriteElement/UITextButton, ProgressBar, Draggable and DropTarget, the floating screen-space container pattern, which of two overlapping panels gets the pointer, Text and BitmapText, web font loading, and NineSliceSprite panels. Triggers on: UI, HUD, button, UIBaseElement, UISpriteElement, UITextButton, ProgressBar, progress bar, health bar, gauge, Draggable, DropTarget, menu, dialogue, overlapping panels, moveToTop, onOver, onClick, Tween, easing, animate a label, Text, BitmapText, fillStyle, fillGradient, gradient text, tint, font, fontface, wordWrapWidth, NineSliceSprite, score display, floating."
 license: MIT
 ---
 
@@ -51,8 +51,24 @@ deliberate fade across a two-line title wants.
 
 The ramp colours the **fill only** — `Text` strokes in a separate pass, so
 an outline keeps its own colour without any luminance trickery — and it works on
-Canvas2D, which a post effect does not. `fillStyle.alpha` still gates the fill,
-and the property still reads back as a `Color`.
+Canvas2D, which a post effect does not.
+
+### The gradient does not live in `fillStyle`
+
+`fillStyle` ACCEPTS a `Gradient`; it never HOLDS one. The constructor routes it
+to `fillGradient` and leaves `fillStyle` as the pooled `Color` it always is,
+which is what keeps `fillStyle.alpha` gating the fill and keeps the colour
+owned by the pool.
+
+So changing the ramp later means assigning the field it actually landed in:
+
+```js
+label.fillGradient = ramp;   // ✓
+label.fillStyle = ramp;      // ✗ TS2740: Gradient is not a Color
+```
+
+The ramp is authored for ONE line height, so a label that changes size needs a
+new one built at the new size; there is nothing that rescales it for you.
 
 ## BitmapText: `size` is a RATIO, not pixels
 
@@ -96,6 +112,19 @@ loader.preload([
 Reach for it over `Text` when the text is mostly static, has to stay crisp at
 integer scales, or wants recolouring without a re-bake.
 
+### `fillStyle` means two different things
+
+The name is shared and the behaviour is not, which is the trap when moving a
+label from one class to the other:
+
+| | `Text` | `BitmapText` |
+|---|---|---|
+| what `fillStyle` holds | a real `Color`, the fill | `Renderable#tint`, under another name |
+| white | white glyphs | the ABSENCE of a tint |
+| gradient | yes, via `fillGradient` | no: a tint is one colour over a page image |
+| stroke | `strokeStyle` + `lineWidth` | none |
+| `size` | pixels | a RATIO of the authored size |
+
 ## The HUD pattern
 
 A HUD is a `floating` container at a high z, built once and re-added:
@@ -129,6 +158,79 @@ Three things matter here:
   real accessor is `depth` (an alias for `pos.z`); `addChild(child, z)` sets it
   for you.
 
+### Bars and gauges: `ProgressBar`
+
+A health bar, a shield gauge, a cooldown and a loading bar are one object. Set
+`value`; it redraws.
+
+```js
+const hp = new ProgressBar(20, 20, {
+    width: 200, height: 24,
+    min: 0, max: 100, value: 100,      // min/max default to 0 and 1
+    trackColor: "#0000001a",
+    fillColor: "#c0392b",
+    borderColor: "black", borderWidth: 2,
+    padding: 2,                        // inset of the fill inside the track
+    radius: 6,                         // 0 is square
+});
+hud.addChild(hp);
+
+hp.value -= 15;                        // clamps; `ratio` reads back 0..1
+```
+
+`direction` takes `"left-to-right"` (the default), `"right-to-left"`,
+`"top-to-bottom"` or `"bottom-to-top"`, each growing from its own edge.
+
+**The colour follows the value by mutating the `Color` you passed.** This is
+the one non-obvious part, and it is deliberate: every game wants a different
+rule, and most want the colour somewhere else too, next to a shader uniform or
+a glow. The bar re-reads `fillColor` every frame, so it never has to know:
+
+```js
+const full = new Color().parseCSS("#7fe0ff");
+const empty = new Color().parseCSS("#ff2a1e");
+const mixed = new Color();
+
+const shield = new ProgressBar(x, y, {
+    width: 190, height: 13,
+    trackColor: null,                  // hollow: the scene shows through
+    borderColor: "rgba(122, 190, 235, 0.8)",
+    padding: 2,
+    fillColor: mixed,                  // KEPT, not copied
+});
+
+// each frame
+mixed.copy(empty).lerp(full, hp);      // the bar follows, and so can a shader
+shield.value = hp;
+```
+
+Blinking is the same story: `setOpacity()` already does it, on whatever clock
+the game is already keeping. Neither is built in.
+
+**`bindEvent` takes the value from an event instead**, and the subscription
+then lives exactly as long as the bar:
+
+```js
+const bar = new ProgressBar(0, y, {
+    width: renderer.width, height: 4,
+    trackColor: "black", fillColor: "#55aa00",
+    bindEvent: event.LOADER_PROGRESS,
+});
+```
+
+Hold that subscription anywhere else and it outlives the bar, firing into a
+renderable whose `pos` has already been released. The engine's own loading
+screen is built on exactly this.
+
+Two more worth knowing:
+
+- **The border is four filled rects, not a stroke** (unless the bar is
+  rounded). A stroke is centred on the path, so half of it falls outside and a
+  bordered bar paints over its neighbour; and `strokeRect` adds corner joins
+  only above a line width of 1, so at exactly 1 a corner pixel goes missing.
+- **`trackColor: null` leaves the bar hollow**, which is what a HUD over a busy
+  scene usually wants: the border is then the only chrome.
+
 ### Buttons: extend the handlers, do not bind listeners
 
 `UISpriteElement` is a `Sprite` that already registers itself for pointer
@@ -139,7 +241,7 @@ events, so a button is made by overriding methods rather than by wiring
 |---|---|---|
 | `onClick(event)` | pressed | `false` to stop the event propagating |
 | `onRelease(event)` | pressed and released | `false` to stop propagating |
-| `onOver(event)` | pointer enters | — |
+| `onOver(event)` | pointer enters | `false` to stop propagating |
 | `onOut(event)` | pointer leaves | — |
 | `onHold()` | pressed and held | — |
 
@@ -163,6 +265,59 @@ default on a plain `Renderable` — is skipped by the broadphase and receives
 nothing. `UISpriteElement` and `UIBaseElement` clear it for you; anything else
 you make clickable has to clear it itself.
 
+### `z` is container-local
+
+`addChild(child, z)` writes a depth that means something **only among that
+container's own children**. `autoDepth` numbers them from 1, so a button at
+`z = 8` inside one panel and a whole second panel at `z = 2` are not comparable
+numbers, and the second panel is still the one on top. Drawing and hit-testing
+both resolve a cross-container pair the same way: walk up to the common parent
+and compare the two siblings there.
+
+So a panel is raised by raising **the panel**, not its contents:
+
+```js
+this.ancestor.moveToTop(panel);   // reorders, and sets z past its neighbour
+```
+
+Giving a child a huge `z` to "put it in front" lifts it only within its own
+panel. This is also why a widget's `z` never has to be coordinated with
+anything outside its own container.
+
+### An opaque panel has to say so
+
+The hit test asks the topmost renderable first and then keeps walking down, so
+consuming is what stops a widget underneath answering too. A panel that can
+overlap another one therefore wants both:
+
+```js
+class Panel extends UIBaseElement {
+    onClick() {
+        this.ancestor.moveToTop(this);  // and bring it to the front
+        return false;                   // consumed
+    }
+    onOver() {
+        return false;                   // the frame the pointer crosses in
+    }
+    onActivateEvent() {
+        super.onActivateEvent();
+        // and every frame after that, when the pointer is ALREADY inside and
+        // `onOver` no longer fires
+        input.registerPointerEvent("pointermove", this, () => false);
+    }
+    onDeactivateEvent() {
+        input.releasePointerEvent("pointermove", this);
+        super.onDeactivateEvent();
+    }
+}
+```
+
+Leave `onOut` alone: an element that suppresses its own leave stays lit after
+the pointer has gone. It fires for the covered element too, not only when the
+pointer leaves its bounds, so a button half under the panel goes dark as soon as
+the pointer slides onto the panel, which never takes it out of the button's
+bounds.
+
 ### In a 3D scene, a HUD needs a SMALL depth
 
 `floating` opts a renderable out of the camera transform. It does **not** opt it
@@ -187,3 +342,9 @@ Give a HUD the huge z that would put it on top in 2D and it lands at the far end
 of the level instead, with the scenery drawing over it. Both shipped idioms are
 the same rule: afterBurner's HUD sits at `-150`, and the glTF, Billboard, Night
 City and Instanced Forest examples park a floating sky at `-10000` or `100000`.
+
+## Related skills
+
+- `melonjs-scenes-and-state` — `Tween` and the easing families, for animating any of this
+- `melonjs-input` — which object gets a pointer event, and how to consume it
+- `melonjs-loading-assets` — web fonts have to be loaded before a `Text` bakes

package/build/level/gltf/srgb.d.ts

@@ -1,20 +0,0 @@
-/**
- * Color-space bridge for glTF material factors.
- *
- * glTF 2.0 defines `pbrMetallicRoughness.baseColorFactor` in **linear** space
- * (spec §3.9.2), while a melonJS `tint` is an 8-bit **sRGB** value — the same
- * space as a CSS color or a texel out of a PNG. Handing the linear number
- * straight to `tint.setColor(f * 255)` therefore displays every untextured
- * glTF material far too light and desaturated: a linear `0.29` shows up as
- * sRGB `0.58`, so an authored mid-green renders as pale mint.
- *
- * The encode below is the standard sRGB transfer function.
- * @module level/gltf/srgb
- */
-/**
- * Encode one linear channel (0..1) to an 8-bit sRGB value (0..255).
- * @param {number} c - linear channel value
- * @returns {number} the sRGB-encoded channel, rounded to 0..255
- */
-export function linearToSrgb8(c: number): number;
-//# sourceMappingURL=srgb.d.ts.map

package/build/level/gltf/srgb.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"srgb.d.ts","sourceRoot":"","sources":["../../../src/level/gltf/srgb.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,iCAHW,MAAM,GACJ,MAAM,CAQlB"}