melonjs 20.4.0 → 20.6.0

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

@@ -49,6 +49,43 @@ always drives the switch from its own completion callback.
 registered for that id, and `state.set` throws if the second argument is not a
 `Stage` instance. Neither fails quietly.
 
+### Always leave `state.LOADING` — it is transitional
+
+`loader.preload()` switches to `state.LOADING` for you. Building your scene in
+the preload callback and then *staying there* looks like it works, and is one
+of the easiest mistakes to make:
+
+```js
+// WRONG — the game now runs inside the loading stage, forever
+loader.preload(assets, () => {
+    app.world.addChild(new Player(...));
+});
+```
+
+Nothing ever destroys that stage, so the built-in loading screen's logo and
+progress bar are never removed and sit on top of your game. (Eight of this
+repository's own examples did this before it was noticed, so it is not an
+obscure trap.)
+
+Give the scene a stage of its own and switch to it:
+
+```js
+class PlayScreen extends Stage {
+    onResetEvent(app) {
+        app.world.addChild(new Player(...));
+    }
+}
+
+await loader.preload(assets);
+state.set(state.PLAY, new PlayScreen());
+state.change(state.PLAY);
+```
+
+The awaited form reads better here than the callback, because "load, then
+switch" is exactly what the code then says. If you genuinely want to keep using
+the loading stage as your scene, `state.change(state.DEFAULT)` at least gets
+you out of it — but a stage of your own is what you want.
+
 ## Persistent objects across levels
 
 ```js
@@ -74,6 +111,45 @@ app.freeze(150);                             // brief hit-stop (proxies state.fr
 `state.change`. The `"mask"` form needs its fourth argument, an `Ellipse` or
 `Polygon`; without one it warns and falls back to a direct switch.
 
+### A Stage's own `update()` is NOT paused
+
+This one is easy to get wrong and hard to see. `Application.update` calls both
+of these **unconditionally**:
+
+```js
+this.isDirty = this.world.update(this.updateDelta);
+this.isDirty = state.current().update(this.updateDelta) || this.isDirty;
+```
+
+Only `Container.update` consults the pause — it reads `state.isPaused()` and
+skips every child that is not `updateWhenPaused`. So world children (entities,
+sprites, meshes, a `GLTFModel`) freeze correctly, while **the Stage subclass's
+own `update()` keeps running**.
+
+A game that keeps its logic in entities pauses for free and never notices. A
+game that drives the simulation from `Stage.update` — common for an endless
+runner, where one object moves and the world scrolls past it — keeps simulating
+through `pauseOnBlur` with its world frozen. The signature is bizarre and very
+misleading: the scenery scrolls on, the player character stands still in world
+space and slides off the screen, and it all snaps back on focus. It reads as a
+culling or animation bug, not a pause bug.
+
+Guard it explicitly:
+
+```js
+update(dt) {
+    super.update(dt);
+    if (state.isPaused()) {
+        return true;        // world children are already frozen for you
+    }
+    // …simulation…
+}
+```
+
+Worth knowing that `pauseOnBlur` (default `true`) fires on a window `blur`, not
+only on tab `visibilitychange` — so clicking another window on the same screen
+triggers it while the canvas is still fully visible.
+
 ## The update loop
 
 There is no loop you own. Logic goes in `update(dt)` overrides, or a
@@ -160,6 +236,21 @@ save.add({ hiscore: 0 });      // once; idempotent, loads any stored value
 save.hiscore = 1200;           // plain assignment writes to localStorage
 ```
 
+**In TypeScript, keep what `add()` returns.** The namespace carries a
+`[key: string]: unknown` index for keys registered anywhere, so reading
+`save.hiscore` off it gives you `unknown`. `add()` hands back the same
+namespace typed with the keys you just registered, which is the handle to
+keep:
+
+```ts
+const store = save.add({ hiscore: 0, lives: 3 });
+store.hiscore = 1200;          // number, no cast
+if (score > store.hiscore) { /* ... */ }
+```
+
+Chained calls accumulate, so `save.add({ a: 0 }).add({ b: "" })` is typed with
+both.
+
 ## Symptom → cause
 
 | symptom | cause |
@@ -169,6 +260,8 @@ save.hiscore = 1200;           // plain assignment writes to localStorage
 | a tween finishes in 1000 ms whatever you pass | `to()` takes `{ duration }`, not a number |
 | object frozen while its state updates | `update()` not returning `true` |
 | timers fire behind a pause menu | `window.setTimeout` instead of `timer.setTimeout` |
+| the world freezes on blur but the game keeps advancing | simulation lives in `Stage.update`, which the pause does not gate — only `Container.update` checks `state.isPaused()` |
+| the player character is left behind and scrolls off after a lost window | same cause: the stage advanced the camera while its world children were paused |
 | a tween does nothing | `.start()` never called |
 | effect stops during a hit-stop | tween needs `updateWhenPaused = true` |
 | crash after a stage switch | callback ran during teardown — guard with `state.isCurrent` |

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

@@ -6,6 +6,96 @@ license: MIT
 
 # UI, HUD and text
 
+## Outlined text: the stroke eats into the glyph
+
+`Text` draws `fillText` and then `strokeText`, so the outline lands **on top of
+the fill** and is centred on the glyph edge — half of it inward. On a small or
+chunky face a `lineWidth` of 3 leaves the letters solid black. Keep it to 1,
+and raise the font size rather than the stroke.
+
+The stroke used to cost you the top row of pixels as well, and a display face
+whose glyphs overshoot the nominal ascent did the same on its own: the render
+box was sized from the line height alone, with no allowance for either. **That
+is fixed** — the bake is padded by the ink's real extent and the blit shifts
+back by the same amount, so nothing is clipped and the reported bounds are
+unchanged. Write the string you mean:
+
+```js
+new Text(x, y, { font: "Display", lineWidth: 1, lineHeight: 1.45, text: "" });
+hud.setText("SCORE 100");
+```
+
+If you have a label carrying a leading `\n` to buy headroom, that workaround is
+now dead weight — drop it, and take the line height back off the position you
+shifted it by.
+
+## Gradient text
+
+`fillStyle` takes a `Gradient` as well as a colour — the same object
+`Renderer#setColor` accepts, built the way the canvas API builds one:
+
+```js
+const ramp = renderer.createLinearGradient(0, 0, 0, 24);  // top to bottom
+ramp.addColorStop(0, "#fffdf0");
+ramp.addColorStop(1, "#f0a020");
+
+new Text(x, y, { font: "Display", size: 24, fillStyle: ramp });
+```
+
+Coordinates are the label's own bake: `(0, 0)` is the top-left of the render
+box, so the ramp above runs down one line. A multi-line label **restarts it on
+every line**, reading like one `Text` per line — you do not have to author the
+gradient over the block height. Pass `gradientPerLine: false` for a single ramp
+spanning the whole block, which is what a plain canvas does and what a
+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`.
+
+## BitmapText: `size` is a RATIO, not pixels
+
+The trap when moving over from `Text`:
+
+```js
+new Text(x, y,       { font: "Arial", size: 24, text: "SCORE" });  // 24 pixels
+new BitmapText(x, y, { font: "arial", size: 24, text: "SCORE" });  // 24 TIMES
+```
+
+`size` scales the font's authored size, so `1` is native and `2` is double —
+`resize(scale)` and `set(textAlign, scale)` take the same ratio. Whole numbers
+keep pixel art crisp; fractional ones resample the page image.
+
+It has **no stroke** — there is no `strokeStyle` or `lineWidth` here, which is
+part of why it stays sharp. Colour comes from the tint instead:
+
+```js
+const score = new BitmapText(8, 8, {
+    font: "arial", text: "1000", fillStyle: "#ffd700",
+});
+score.fillStyle = "#ff4040";                  // recolour at any time
+score.fillStyle = new Color(255, 255, 255);   // UNTINTED, not "white text"
+```
+
+`fillStyle` is `Renderable#tint` under another name: white is the *absence* of a
+tint and every other colour tints away from it, so author the page in white to
+keep every colour available to you.
+
+Load the descriptor as `binary` and its page as `image` under the **same name**.
+Both BMFont flavours — text (`.fnt`) and XML — are auto-detected, so an `.xml`
+descriptor loads as-is:
+
+```js
+loader.preload([
+    { name: "arial", type: "binary", src: "data/font/arial.fnt" },
+    { name: "arial", type: "image",  src: "data/font/arial.png" },
+]);
+```
+
+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.
+
 ## The HUD pattern
 
 A HUD is a `floating` container at a high z, built once and re-added:
@@ -39,6 +129,40 @@ Three things matter here:
   real accessor is `depth` (an alias for `pos.z`); `addChild(child, z)` sets it
   for you.
 
+### Buttons: extend the handlers, do not bind listeners
+
+`UISpriteElement` is a `Sprite` that already registers itself for pointer
+events, so a button is made by overriding methods rather than by wiring
+`registerPointerEvent`:
+
+| handler | fires | returns |
+|---|---|---|
+| `onClick(event)` | pressed | `false` to stop the event propagating |
+| `onRelease(event)` | pressed and released | `false` to stop propagating |
+| `onOver(event)` | pointer enters | — |
+| `onOut(event)` | pointer leaves | — |
+| `onHold()` | pressed and held | — |
+
+```js
+class MuteButton extends UISpriteElement {
+    constructor(x, y) {
+        super(x, y, { image: atlas, region: "speaker.png" });
+        this.setOpacity(0.5);
+    }
+    onOver() { this.setOpacity(1.0); }
+    onOut()  { this.setOpacity(0.5); }
+    onClick() {
+        audio.muteAll();
+        return false;          // consumed — do not fall through to the world
+    }
+}
+```
+
+The pointer still has to reach it: a renderable with `isKinematic = true` — the
+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.
+
 ### In a 3D scene, a HUD needs a SMALL depth
 
 `floating` opts a renderable out of the camera transform. It does **not** opt it