melonjs 20.4.0 → 20.5.0

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