melonjs 20.3.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,137 +129,61 @@ Three things matter here:
   real accessor is `depth` (an alias for `pos.z`); `addChild(child, z)` sets it
   for you.
 
-Relayout on resize by listening for `event.CANVAS_ONRESIZE`.
+### Buttons: extend the handlers, do not bind listeners
 
-## Buttons and interactive elements
+`UISpriteElement` is a `Sprite` that already registers itself for pointer
+events, so a button is made by overriding methods rather than by wiring
+`registerPointerEvent`:
 
-Use the built-ins rather than hand-rolling — they set `isKinematic = false` for
-you, which is the trap that stops hand-rolled buttons receiving clicks at all.
+| 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 PlayButton extends UISpriteElement {
+class MuteButton extends UISpriteElement {
     constructor(x, y) {
-        super(x, y, { image: atlas, region: "play.png" });
+        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
     }
-    onClick()   { state.change(state.PLAY); return false; }
-    onOver()    { this.setOpacity(1.0); }
-    onOut()     { this.setOpacity(0.8); }
-    onRelease() { return false; }
 }
 ```
 
-| class | for |
-|---|---|
-| `UIBaseElement` | a `Container` base — clickable, optionally draggable and holdable |
-| `UISpriteElement` | a `Sprite`-backed button with hover/press callbacks |
-| `UITextButton` | a `BitmapText` label on a `RoundRect` background — it needs a **bitmap** font, not a `fontface` |
-| `Draggable` / `DropTarget` | drag-and-drop; `dropTarget.setCheckMethod(dropTarget.CHECKMETHOD_CONTAINS)` to require containment instead of overlap |
-
-The callbacks to override are `onClick`, `onOver`, `onOut`, `onRelease` and
-`onHold`; `UIBaseElement` adds `onMove` while dragging. Returning `false` from
-`onClick` / `onRelease` stops the event propagating further.
-
-## Text
-
-```js
-new Text(x, y, {
-    font: "Arial",
-    size: 32,
-    fillStyle: "#FFFFFF",
-    textAlign: "center",
-    textBaseline: "middle",
-    text: "Score: 0",
-    wordWrapWidth: 400,        // enables wrapping
-});
-```
-
-`text` accepts a string or an array of lines. Update with `setText()`.
-
-**Custom web fonts must be preloaded** with the `"fontface"` asset type:
-
-```js
-{ name: "PressStart2P", type: "fontface", src: "data/font/PressStart2P.ttf" }
-```
-
-Drawing before the font has loaded silently renders in a fallback font — the
-layout looks subtly wrong rather than failing.
-
-## `BitmapText`
-
-For pixel-perfect text that scales without antialiasing, and for text drawn in
-volume: every `BitmapText` sharing a font draws glyph quads from that one page
-image, so they batch together. Each `Text` instead owns a private canvas
-texture (re-rasterised whenever it changes), so a screenful of them is a
-screenful of distinct textures.
-
-```js
-await loader.preload([
-    { name: "PressStart2P", type: "image",  src: "data/font/font.png" },
-    { name: "PressStart2P", type: "binary", src: "data/font/font.fnt" },
-]);
-
-new BitmapText(x, y, {
-    font: "PressStart2P",
-    size: 2,                  // a scale ratio, not a pixel size
-    text: "GAME OVER",
-});
-```
-
-It needs **both** assets, and by default they must share the **same asset
-name** — `settings.font` resolves the image *and*, unless you pass
-`settings.fontData`, the descriptor. Registering the descriptor under a
-different name (`"…-fnt"`) is the usual mistake; either use one name for both,
-or pass `fontData: "PressStart2P-fnt"` explicitly.
-
-The descriptor is AngelCode BMFont in either flavour — the text `.fnt` form or
-the XML form — auto-detected, so an `.xml` export loads as-is.
-
-## Never draw text through the raw context
+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.
 
-```js
-// ✗ works on Canvas only — getContext() returns the GL/GPU context on the
-//   GPU backends, and neither has fillText
-app.renderer.getContext().fillText("hi", 10, 10);
-
-// ✓
-world.addChild(new Text(10, 10, { text: "hi", /* … */ }));
-```
+### In a 3D scene, a HUD needs a SMALL depth
 
-`getContext()` hands back the *backend's* context — a
-`CanvasRenderingContext2D` only under the Canvas renderer. On WebGL or WebGPU
-the call throws `TypeError: … .fillText is not a function`, so this fails loudly
-— but only on the machines that picked a GPU backend, which under `video.AUTO`
-is most of them and probably not yours.
+`floating` opts a renderable out of the camera transform. It does **not** opt it
+out of the depth sort, and the two sorts read z differently:
 
-## Panels
+| container `sortOn` | ordered by | on top |
+| --- | --- | --- |
+| `"z"` (default, 2D) | `pos.z` | **highest** z |
+| `"depth"` (what `Camera3d` sets) | distance from the camera | **nearest** the camera |
 
-`NineSliceSprite` stretches a panel without distorting its corners — the right
-tool for dialogue boxes and windows:
+Under `"depth"` a floating child is ordered by `|pos.z|` alone — its `pos.x/y`
+are screen pixels, not a place in the world, and the camera does not move
+relative to it. So the *magnitude* is the distance, and the sign is ignored:
 
 ```js
-new NineSliceSprite(x, y, {
-    image: "panel", width: 300, height: 120, insetx: 12, insety: 12,
-});
+world.addChild(hud, -150);        // small -> in front of the whole scene
+world.addChild(backdrop, -10000); // large -> behind the whole scene
+world.addChild(backdrop, 100000); // equally far: sign does not matter
 ```
 
-The inset keys are lowercase `insetx` / `insety`; `insetX` is silently ignored
-and the corners fall back to a quarter of the frame. `width` and `height` are
-mandatory — the constructor throws without them.
-
-## Symptom → cause
-
-| symptom | cause |
-|---|---|
-| HUD scrolls away with the camera | missing `floating = true` on the container |
-| HUD drawn under the game | `this.z = …` instead of `addChild(hud, z)` |
-| hand-rolled button never responds | `isKinematic` left `true` — use `UISpriteElement` |
-| text renders in the wrong font | web font not preloaded as `"fontface"` |
-| `BitmapText` renders nothing | the `.fnt` / image pair was loaded under two different asset names |
-| `TypeError: … .fillText is not a function` | drawn via `getContext()` under a GPU backend |
-| `UIContainer is not defined` | no such class — use `Container` or `UIBaseElement` |
-| UI misplaced after a window resize | no `CANVAS_ONRESIZE` relayout |
-
-## Related skills
-
-- `melonjs-input` — the `isKinematic` requirement in full
-- `melonjs-renderables` — `floating`, draw order, containers
+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`.