melonjs 20.12.0 → 20.13.0

package/build/renderable/text/text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../../src/renderable/text/text.js"],"names":[],"mappings":"AAiDA;;;;;;;;;;;;;;GAcG;AACH;IACC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6DG;IACH,eA7DW,MAAM,KACN,MAAM,YAEd;QAAyB,IAAI,EAArB,MAAM;QACkB,IAAI,EAA5B,MAAM,GAAC,MAAM;QACoB,SAAS;QACvB,eAAe;QACV,WAAW;QACjB,SAAS;QACT,SAAS;QACT,YAAY;QACZ,UAAU;QACmB,WAAW;eAAvC,MAAM;eAAG,MAAM;;QAChB,aAAa;QACZ,IAAI;QACJ,MAAM;QACI,IAAI;KACzC,EAsHF;IAtEA;;;;OAIG;IACH,WAHU,KAAK,CAGwB;IAEvC;;;;OAIG;IACH,aAHU,KAAK,CAG0B;IAEzC;;;;OAIG;IACH,WAHU,MAAM,CAGE;IAElB;;;;;OAKG;IACH,WAHU,MAAM,CAGO;IAEvB;;;;;OAKG;IACH,cAHU,MAAM,CAGS;IAEzB;;;;;OAKG;IACH,YAHU,MAAM,CAGK;IAErB;;;;;OAKG;IACH,eAHU,MAAM,CAGO;IAEvB;;;;OAIG;IACH,UAHU,MAAM,CAGE;IAElB;;;;;OAKG;IACH,cAAe;IAMhB;;;OAGG;IACH,kDA8KC;IAjJA;;;;;;;;;;;;;;;;OAgBG;IACH,cARU,QAAQ,GAAC,SAAS,CAQC;IAE7B;;;;;;;;;;;;;;OAcG;IACH,qCAA2B;IA4F1B,8CAEE;IAGH;;;OAGG;IACH,wBAA4B;IAK3B,iCAAoC;IAOtC;;;OAGG;IACH,QAFa,IAAI,CAWhB;IAJC,UAA+B;IAMjC;;;OAGG;IACH,UAFa,IAAI,CAWhB;IAED;;;;;;;;OAQG;IACH,cAPW,MAAM,SACN,MAAM,GAAC,MAAM,GACX,IAAI,CAwChB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,MAAM,GAAC,MAAM,EAAE,GACpB,IAAI,CAuFhB;IAkBD,oCAZU,MAAM,EAiBf;IArBD;;;;;;;;;;;OAWG;IACH,gCARU,MAAM,CAUf;IAkCD,+BAlBU,MAAM,EA4Bf;IAnCD;;;;;;;;;;;;;;OAcG;IACH,2BARU,MAAM,CAgBf;IAiED;;;;;;;;;;;;OAYG;IACH,mBAXW,MAAM,GACJ,WAAW,CAYvB;IAED;;;OAGG;IACH,eAFW,QAAQ,QAqClB;IAED;;;OAGG;IACH,4EA+GC;IAED;;;;OAIG;IACH,gBAWC;CACD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wGAQG;uBAz2B8C,kBAAkB;sBANlC,qBAAqB;yBAE7B,yBAAyB;+BAEnB,gDAAgD;wBAGvD,kBAAkB;0BASjB,yBAAyB;8BAHvB,wBAAwB"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../../src/renderable/text/text.js"],"names":[],"mappings":"AAiDA;;;;;;;;;;;;;;;;GAgBG;AACH;IACC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8GG;IACH,eA9GW,MAAM,KACN,MAAM,YAEd;QAAyB,IAAI,EAArB,MAAM;QACkB,IAAI,EAA5B,MAAM,GAAC,MAAM;QACoB,SAAS;QACvB,eAAe;QACV,WAAW;QACjB,SAAS;QACQ,QAAQ;QACzB,UAAU;QACD,UAAU;QACnB,SAAS;QACT,YAAY;QACZ,UAAU;QACmB,WAAW;eAAvC,MAAM;eAAG,MAAM;;QAChB,aAAa;QACZ,IAAI;QACJ,MAAM;QACI,IAAI;KACzC,EA2PF;IA7JA;;;;OAIG;IACH,WAHU,KAAK,CAGwB;IAEvC;;;;OAIG;IACH,aAHU,KAAK,CAG0B;IAEzC;;;;OAIG;IACH,WAHU,MAAM,CAGE;IAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,UAfU,OAAO,GAAC,OAAO,GAAC,OAAO,CAeV;IAEvB;;;;;;;;;;;;;;;;;OAiBG;IACH,YARU,MAAM,CAQI;IAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,YAdU,QAAQ,GAAC,MAAM,CAcC;IAE1B;;;;;OAKG;IACH,WAHU,MAAM,CAGO;IAEvB;;;;;;;OAOG;IACH,cAHU,MAAM,CAGS;IAEzB;;;;;OAKG;IACH,YAHU,MAAM,CAGK;IAErB;;;;;;;OAOG;IACH,eAHU,MAAM,CAGO;IAEvB;;;;OAIG;IACH,UAHU,MAAM,CAGE;IAElB;;;;;OAKG;IACH,cAAe;IAMhB;;;OAGG;IACH,kDAkLC;IArJA;;;;;;;;;;;;;;;;OAgBG;IACH,cARU,QAAQ,GAAC,SAAS,CAQC;IAE7B;;;;;;;;;;;;;;OAcG;IACH,qCAA2B;IAgG1B,8CAEE;IAGH;;;OAGG;IACH,wBAA4B;IAK3B,iCAAoC;IAOtC;;;OAGG;IACH,QAFa,IAAI,CAWhB;IAJC,UAA+B;IAMjC;;;OAGG;IACH,UAFa,IAAI,CAWhB;IAED;;;;;;;;OAQG;IACH,cAPW,MAAM,SACN,MAAM,GAAC,MAAM,GACX,IAAI,CAwChB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,MAAM,GAAC,MAAM,EAAE,GACpB,IAAI,CA+FhB;IAkBD,oCAZU,MAAM,EAiBf;IArBD;;;;;;;;;;;OAWG;IACH,gCARU,MAAM,CAUf;IAkCD,+BAlBU,MAAM,EA4Bf;IAnCD;;;;;;;;;;;;;;OAcG;IACH,2BARU,MAAM,CAgBf;IAwDD;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAXW,MAAM,GAAC,MAAM,EAAE,GACb,WAAW,CAmBvB;IAED;;;OAGG;IACH,eAFW,QAAQ,QAsClB;IAED;;;OAGG;IACH,4EA+HC;IAED;;;;OAIG;IACH,gBAWC;CACD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wGAQG;uBAnhC8C,kBAAkB;sBANlC,qBAAqB;yBAE7B,yBAAyB;+BAEnB,gDAAgD;wBAG/B,kBAAkB;0BASzC,yBAAyB;8BAHvB,wBAAwB"}

package/build/renderable/text/textmetrics.d.ts

@@ -1,3 +1,4 @@
+
 export default TextMetrics;
 /**
  * a Text Metrics object that contains helper for text manipulation
@@ -36,12 +37,19 @@ declare class TextMetrics extends Bounds {
     glyphMaxBottom: number | undefined;
     inkPadTop: number | undefined;
     inkPadBottom: number | undefined;
+    inkPadLeft: number | undefined;
+    inkPadRight: number | undefined;
     /**
-     * wrap the given text based on the given width
+     * wrap the given text based on the given width.
+     *
+     * Each `\n`-separated line (each entry, for an array) is wrapped on its
+     * own, so wrapping only ever adds line breaks: the explicit ones are kept,
+     * blank lines included. A line breaks between words, never inside one: a
+     * word wider than `width` is put on a line of its own and overflows it.
      * @param {string|string[]} text - the text to be wrapped
      * @param {number} width - maximum width of one segment of text in css pixel
      * @param {CanvasRenderingContext2D} [context] - reference to an active 2d context for canvas rendering
-     * @returns {string[]} an array of string representing wrapped text
+     * @returns {string[]} an array of string representing wrapped text, one entry per line
      */
     wordWrap(text: string | string[], width: number, context?: CanvasRenderingContext2D): string[];
 }

package/build/renderable/text/textmetrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"textmetrics.d.ts","sourceRoot":"","sources":["../../../src/renderable/text/textmetrics.js"],"names":[],"mappings":";AA+BA;;GAEG;AACH;IACC;;OAEG;IACH,sBAFW,IAAI,GAAC,UAAU,EAczB;IARA;;;;OAIG;IACH,UAHU,UAAU,CAGI;IAKzB;;;OAGG;IACH,cAFa,MAAM,CAalB;IAED;;;;;OAKG;IACH,gBAJW,MAAM,YACN,wBAAwB,GACtB,MAAM,CA4BlB;IAED;;;;;OAKG;IACH,kBAJW,MAAM,YACN,wBAAwB,GACtB,WAAW,CAiHvB;IA/EA,iCAAqB;IACrB,mCAAuB;IAmCvB,8BAAkB;IAClB,iCAAqB;IA4CtB;;;;;;;;;;;;;;;OAeG;IACH,gBAJa,WAAW,CAoBvB;IAED;;;;;;OAMG;IACH,eALW,MAAM,GAAC,MAAM,EAAE,SACf,MAAM,YACN,wBAAwB,GACtB,MAAM,EAAE,CAyCpB;CACD;uBA/SsB,yBAAyB;4BAOrB,kBAAkB;iBAN5B,WAAW;4BAKD,iBAAiB"}
+{"version":3,"file":"textmetrics.d.ts","sourceRoot":"","sources":["../../../src/renderable/text/textmetrics.js"],"names":[],"mappings":"AA+BA;;;;;;;GAOG;AACH,gCALW,MAAM,GAAC,MAAM,GAAC,MAAM,EAAE,GAAC,IAAI,GACzB,MAAM,EAAE,CAWpB;AAED;;;;;;;;GAQG;AACH,6BANW,MAAM,EAAE,KACR,MAAM,EAAE,GACN,OAAO,CAcnB;;AAaD;;GAEG;AACH;IACC;;OAEG;IACH,sBAFW,IAAI,GAAC,UAAU,EAczB;IARA;;;;OAIG;IACH,UAHU,UAAU,CAGI;IAKzB;;;OAGG;IACH,cAFa,MAAM,CAalB;IAED;;;;;OAKG;IACH,gBAJW,MAAM,YACN,wBAAwB,GACtB,MAAM,CA4BlB;IAED;;;;;OAKG;IACH,kBAJW,MAAM,YACN,wBAAwB,GACtB,WAAW,CAuJvB;IArHA,iCAAqB;IACrB,mCAAuB;IAyCvB,8BAAkB;IAClB,iCAAqB;IACrB,+BAAmB;IACnB,gCAAoB;IA0ErB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAJa,WAAW,CAcvB;IAED;;;;;;;;;;;OAWG;IACH,cAJa,MAAM,CAclB;IAED;;;;;;;;;;;OAWG;IACH,eALW,MAAM,GAAC,MAAM,EAAE,SACf,MAAM,YACN,wBAAwB,GACtB,MAAM,EAAE,CA8CpB;CACD;uBAxasB,yBAAyB;4BAOrB,kBAAkB;iBAN5B,WAAW;4BAKD,iBAAiB"}

package/build/renderable/text/textstyle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"textstyle.d.ts","sourceRoot":"","sources":["../../../src/renderable/text/textstyle.js"],"names":[],"mappings":"AAmEA;;;;;;;;GAQG;AACH,iDAPW,wBAAwB,SACxB,MAAM,GACJ,MAAM,GAAC,cAAc,CAcjC"}
+{"version":3,"file":"textstyle.d.ts","sourceRoot":"","sources":["../../../src/renderable/text/textstyle.js"],"names":[],"mappings":"AAwFA;;;;;;;;;;;;GAYG;AACH,mCALW,MAAM,GACJ,MAAM,CAclB;AAED;;;;;;;;GAQG;AACH,iDAPW,wBAAwB,SACxB,MAAM,GACJ,MAAM,GAAC,cAAc,CAgBjC"}

package/build/renderable/ui/panelpaint.d.ts

@@ -1,5 +1,9 @@
 import { Color } from "../../math/color.ts";
 import type { Gradient } from "../../video/gradient.js";
-/** anything {@link Renderer#setColor} will take */
+/**
+ * A colour a widget is painted with: a CSS string, a {@link Color} (kept
+ * and read every frame, so changing it animates the widget), or a gradient.
+ * @category UI
+ */
 export type Paint = Color | string | Gradient;
 //# sourceMappingURL=panelpaint.d.ts.map

package/build/renderable/ui/panelpaint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"panelpaint.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/panelpaint.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAa,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGxD,mDAAmD;AACnD,MAAM,MAAM,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC"}
+{"version":3,"file":"panelpaint.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/panelpaint.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAa,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGxD;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC"}

package/build/renderable/ui/progressbar.d.ts

@@ -10,147 +10,298 @@ import type { Paint } from "./panelpaint.ts";
  * the event module; this gets the same set without widening that surface.
  */
 type EventName = Parameters<typeof on>[0];
-/** which way the fill grows */
+/**
+ * Which edge a {@link ProgressBar}'s fill grows from: `"left-to-right"`
+ * and `"right-to-left"` for a horizontal bar, `"top-to-bottom"` and
+ * `"bottom-to-top"` for a vertical one.
+ * @category UI
+ */
 export type ProgressBarDirection = "left-to-right" | "right-to-left" | "top-to-bottom" | "bottom-to-top";
 /**
- * Everything {@link ProgressBar} takes.
+ * The settings a {@link ProgressBar} takes. Only `width` and `height` are
+ * required.
+ * @category UI
  */
 export interface ProgressBarSettings {
     /** the bar's full width, in pixels */
     width: number;
     /** the bar's full height, in pixels */
     height: number;
-    /** the value that reads as empty */
+    /**
+     * the value that shows as empty
+     * @default 0
+     */
     min?: number;
-    /** the value that reads as full */
+    /**
+     * the value that shows as full; given below `min`, the two are swapped
+     * @default 1
+     */
     max?: number;
-    /** where to start */
+    /**
+     * the starting value, clamped between `min` and `max`; `min` if not given
+     */
     value?: number;
-    /** which edge the fill grows from */
+    /**
+     * which edge the fill grows from; see {@link ProgressBarDirection}
+     * @default "left-to-right"
+     */
     direction?: ProgressBarDirection;
-    /** behind the fill; `null` leaves it hollow, showing whatever is behind */
+    /**
+     * the colour behind the fill; `null` leaves it hollow, showing whatever
+     * is behind the bar
+     * @default null
+     */
     trackColor?: Paint | null;
     /**
-     * the fill itself. A {@link Color} is re-read every frame, so mutating the
-     * one you passed animates the bar
+     * The colour of the fill. A {@link Color} is read again every frame, so
+     * changing the one you passed changes the bar.
+     * @default "#ffffff"
      */
     fillColor?: Paint;
-    /** drawn around the track; `null` for none */
+    /**
+     * the colour of the border drawn around the bar; `null` for none
+     * @default null
+     */
     borderColor?: Paint | null;
-    /** how thick that border is */
+    /**
+     * the border's thickness, in pixels, drawn inside the bar's edge
+     * @default 1
+     */
     borderWidth?: number;
-    /** how far the fill sits inside the track, per side */
+    /**
+     * the gap between the track's edge and the fill on each side, in pixels
+     * @default 0
+     */
     padding?: number;
-    /** corner radius; `0` is square */
+    /**
+     * the corner radius, in pixels; `0` is square. The fill's corners are
+     * reduced by `padding`, so they stay parallel to the track's.
+     * @default 0
+     */
     radius?: number;
-    /** called whenever the value actually moves */
-    onChange?: (value: number, ratio: number) => void;
-    /** draw a label over the bar */
+    /**
+     * The colour of a drop shadow under the bar; `null` for none. Its alpha
+     * sets how dark the shadow is, e.g. `"#00000066"`.
+     * @default null
+     */
+    shadowColor?: Paint | null;
+    /**
+     * how far right the shadow falls, in pixels; negative goes left
+     * @default 0
+     */
+    shadowOffsetX?: number;
+    /**
+     * how far down the shadow falls, in pixels; negative goes up
+     * @default 4
+     */
+    shadowOffsetY?: number;
+    /**
+     * how far the shadow's soft edge spreads, in pixels; `0` is a sharp edge
+     * @default 8
+     */
+    shadowBlur?: number;
+    /**
+     * Called each time the value changes, with the new value, the same as a
+     * `0..1` fraction of the way from `min` to `max`, and the bar. Not called
+     * when the value is set to what it already is.
+     */
+    onChange?: (value: number, ratio: number, bar: ProgressBar) => void;
+    /**
+     * draw a text label centred over the bar
+     * @default false
+     */
     showLabel?: boolean;
-    /** the label's font family */
+    /**
+     * the label's CSS font family
+     * @default "sans-serif"
+     */
     font?: string;
-    /** the label's font size, in pixels */
+    /**
+     * the label's text height, in pixels; 70% of the bar's height (at least
+     * 8), rounded, if not given
+     */
     fontSize?: number;
-    /** the label's colour */
+    /**
+     * the label's colour
+     * @default "#ffffff"
+     */
     labelFillStyle?: Paint;
-    /** what the label says; the default is a rounded percentage */
+    /**
+     * What the label says, given the value and its `0..1` fraction. The
+     * default shows a rounded percentage, such as `"75%"`.
+     */
     labelFormat?: (value: number, ratio: number) => string;
     /**
-     * an event to take the value from, instead of setting it by hand.
-     *
-     * The bar subscribes for as long as it exists and unsubscribes when it is
-     * destroyed, which is the point: a subscription that outlives what it
-     * drives is a listener writing into a freed object.
+     * An event to take the value from, instead of setting it by hand: each
+     * time the event fires, its first argument becomes the value. The bar
+     * stops listening when it is destroyed.
      */
     bindEvent?: EventName;
 }
 /**
- * A bar that shows one value between two bounds.
+ * A bar that shows one value between a minimum and a maximum: a health
+ * bar, a shield or stamina gauge, a cooldown, a loading bar. Set
+ * {@link ProgressBar#value} and it redraws. The engine's own loading screen
+ * uses one.
+ *
+ * It draws its track, fill, border and optional label itself, as one
+ * renderable, so there is nothing to keep in step.
  *
- * A health bar, a shield gauge, a cooldown, a loading bar: all the same
- * object, and the engine's own loading screen is built on this one. Set
- * {@link ProgressBar#value} and it redraws.
+ * ## Look
+ * `trackColor` is behind the fill (`null` for a hollow frame), `fillColor`
+ * is the fill, `borderColor` and `borderWidth` draw an outline, `padding`
+ * insets the fill, and `radius` rounds the corners. `direction` sets which
+ * edge the fill grows from, horizontal or vertical.
  *
- * It draws the track, the fill, the border and the label itself, in that
- * order, which is the point of it being ONE renderable rather than a track
- * sprite with a fill sprite on top. Two renderables at the same place have to
- * be told which is in front, and that question has to be answered again every
- * time either one moves.
+ * ## Value
+ * `min` and `max` set the range (`0` to `1` by default). A value outside it
+ * is clamped. {@link ProgressBar#ratio} gives the value as a `0..1`
+ * fraction. `onChange(value, ratio, bar)` is called whenever the value
+ * changes, and `bindEvent` takes the value from an event.
  *
- * ## The colour can follow the value
+ * ## Label
+ * `showLabel` draws text over the bar, a percentage by default; `labelFormat`
+ * changes what it says, and `font`, `fontSize` and `labelFillStyle` how it
+ * looks.
  *
- * `fillColor` is read at draw time rather than copied, so passing a
- * {@link Color} you keep hold of and mutating it is all a value-driven colour
- * takes. That is deliberately not built in, because every game wants a
- * different rule and most want the colour somewhere else too, next to a shader
- * uniform or a glow:
+ * ## Drop shadow
+ * `shadowColor` draws a soft shadow under the bar; its alpha sets how dark
+ * it is. `shadowOffsetX` and `shadowOffsetY` move it and `shadowBlur`
+ * softens its edge.
+ *
+ * ## Colour that follows the value
+ * `fillColor` is read every frame, not copied, so pass a {@link Color} you
+ * keep and change it as the value changes. To make the bar blink, use
+ * {@link Renderable#setOpacity}.
+ * @category UI
+ * @example
+ * // a loading bar, fed by the loader
+ * import { ProgressBar, event } from "melonjs";
+ *
+ * const loading = new ProgressBar(0, 300, {
+ *     width: 800,
+ *     height: 4,
+ *     trackColor: "black",
+ *     fillColor: "#55aa00",
+ *     bindEvent: event.LOADER_PROGRESS,
+ * });
+ * app.world.addChild(loading);
+ * @example
+ * // a health bar with a label, and a range that is not 0 to 1
+ * const hp = new ProgressBar(20, 20, {
+ *     width: 200,
+ *     height: 24,
+ *     min: 0,
+ *     max: 100,
+ *     value: 100,
+ *     trackColor: "#3a1010",
+ *     fillColor: "#c0392b",
+ *     radius: 6,
+ *     showLabel: true,
+ *     labelFormat: (value) => `${Math.round(value)} HP`,
+ * });
+ * // when the player is hit
+ * hp.value -= 15;
+ * @example
+ * // a colour that follows the value, from red when empty to blue when full
+ * import { ProgressBar, Color } from "melonjs";
  *
- * ```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,                          // a hollow frame
+ * const mixed = full.clone();
+ * const shield = new ProgressBar(20, 52, {
+ *     width: 190,
+ *     height: 13,
+ *     value: 1,
+ *     trackColor: null, // a hollow frame
  *     borderColor: "rgba(122, 190, 235, 0.8)",
  *     padding: 2,
- *     fillColor: mixed,                          // kept, not copied
+ *     radius: 4,
+ *     fillColor: mixed, // kept, not copied
+ *     onChange: (value, ratio) => {
+ *         mixed.copy(empty).lerp(full, ratio);
+ *     },
  * });
- *
- * // each frame
- * mixed.copy(empty).lerp(full, hp);
- * shield.value = hp;
- * ```
- *
- * Blinking is the same story: {@link Renderable#setOpacity} already does it,
- * on whatever clock the game is already keeping.
- * @category UI
  * @example
- * // a loading bar
- * const bar = new ProgressBar(0, 100, {
- *     width: renderer.width, height: 4,
- *     trackColor: "black", fillColor: "#55aa00",
+ * // a vertical bar that fills from the bottom
+ * const power = new ProgressBar(740, 200, {
+ *     width: 16,
+ *     height: 120,
+ *     direction: "bottom-to-top",
+ *     trackColor: "#222222",
+ *     fillColor: "#f1c40f",
+ *     borderColor: "#ffffff",
+ *     borderWidth: 2,
+ *     padding: 3,
  * });
- * event.on(event.LOADER_PROGRESS, (progress) => { bar.value = progress; });
  * @example
- * // a label, and a value that is not a fraction
- * const hp = new ProgressBar(20, 20, {
- *     width: 200, height: 24,
- *     min: 0, max: 100, value: 100,
- *     fillColor: "#c0392b", radius: 6,
- *     showLabel: true,
- *     labelFormat: (v) => `${Math.round(v)} HP`,
+ * // a drop shadow under the bar
+ * const xp = new ProgressBar(20, 80, {
+ *     width: 240,
+ *     height: 16,
+ *     trackColor: "#1e1e2e",
+ *     fillColor: "#9b59b6",
+ *     radius: 8,
+ *     shadowColor: "#00000080", // the alpha sets how dark
+ *     shadowOffsetY: 3,
+ *     shadowBlur: 6,
+ * });
+ * @example
+ * // react when the bar is emptied
+ * const timer = new ProgressBar(20, 110, {
+ *     width: 200,
+ *     height: 8,
+ *     value: 1,
+ *     fillColor: "#2ecc71",
+ *     onChange: (value, ratio, bar) => {
+ *         if (ratio === 0) {
+ *             bar.setOpacity(0.5);
+ *             onTimeUp();
+ *         }
+ *     },
  * });
  */
 export default class ProgressBar extends Renderable {
-    /** the value that reads as empty */
-    min: number;
-    /** the value that reads as full */
-    max: number;
-    /** which edge the fill grows from */
+    /** which edge the fill grows from; see {@link ProgressBarDirection} */
     direction: ProgressBarDirection;
-    /** behind the fill; `null` leaves it hollow */
+    /** the colour behind the fill; `null` leaves it hollow */
     trackColor: Paint | null;
-    /** the fill. A {@link Color} here is re-read every frame */
+    /** the colour of the fill; a {@link Color} here is read every frame */
     fillColor: Paint;
-    /** drawn around the track; `null` for none */
+    /** the colour of the border; `null` for none */
     borderColor: Paint | null;
-    /** how thick that border is */
+    /** the border's thickness, in pixels */
     borderWidth: number;
-    /** how far the fill sits inside the track, per side */
+    /** the gap between the track's edge and the fill on each side, in pixels */
     padding: number;
-    /** corner radius; `0` is square */
+    /** the corner radius, in pixels; `0` is square */
     radius: number;
-    /** called whenever the value actually moves */
-    onChange?: ((value: number, ratio: number) => void) | undefined;
-    /** what the label says */
+    /** the colour of the drop shadow, its alpha setting how dark; `null` for none */
+    shadowColor: Paint | null;
+    /** how far right the shadow falls, in pixels */
+    shadowOffsetX: number;
+    /** how far down the shadow falls, in pixels */
+    shadowOffsetY: number;
+    /** how far the shadow's soft edge spreads, in pixels */
+    shadowBlur: number;
+    /**
+     * Called each time the value changes, with the new value, its `0..1`
+     * fraction from `min` to `max`, and the bar.
+     * @example
+     * bar.onChange = (value, ratio, bar) => {
+     *     bar.setOpacity(ratio < 0.25 ? 0.6 : 1);
+     * };
+     */
+    onChange?: ((value: number, ratio: number, bar: ProgressBar) => void) | undefined;
+    /** builds the label's text from the value and its `0..1` fraction */
     labelFormat: (value: number, ratio: number) => string;
-    /** the label, when `showLabel` was asked for */
+    /** the label's text object, when `showLabel` was set */
     label?: Text | undefined;
     /** the event the value is taken from, if any */
     readonly bindEvent?: EventName | undefined;
     private _value;
+    private _min;
+    private _max;
     /**
      * @param x - position of the bar's left edge
      * @param y - position of its top edge
@@ -158,22 +309,43 @@ export default class ProgressBar extends Renderable {
      */
     constructor(x: number, y: number, settings: ProgressBarSettings);
     /**
-     * Where the bar is now, between {@link ProgressBar#min} and
-     * {@link ProgressBar#max}.
-     *
-     * Writing a value outside that range clamps rather than throwing, since
-     * the usual source is a health or a timer that has just gone past its own
-     * limit. Writing the value it already has does nothing at all, so
-     * `onChange` means the value MOVED.
+     * The value that shows as empty. Setting it clamps the value into the
+     * new range, and a `min` above `max` raises `max` to it, so the bar never
+     * draws past its ends. A value moved by the clamp calls `onChange`, as
+     * any change of the value does; the label is rewritten either way.
+     * @example
+     * // a gauge that starts at 50 rather than 0
+     * pressure.min = 50;
+     */
+    get min(): number;
+    set min(v: number);
+    /**
+     * The value that shows as full. Setting it clamps the value into the
+     * new range, and a `max` below `min` lowers `min` to it, so the bar never
+     * draws past its ends. A value moved by the clamp calls `onChange`, as
+     * any change of the value does; the label is rewritten either way.
+     * @example
+     * // a debuff lowers the most health the player can have: a full bar
+     * // stays full, at the new maximum
+     * hp.max = 50;
+     */
+    get max(): number;
+    set max(v: number);
+    /**
+     * The current value, between {@link ProgressBar#min} and
+     * {@link ProgressBar#max}. Setting it redraws the bar and updates the
+     * label. A value outside the range is clamped, and setting the value it
+     * already has does nothing, so `onChange` only fires on a real change.
+     * @example
+     * // a cooldown that refills over 3 seconds
+     * cooldown.value = Math.min(1, elapsed / 3000);
      */
     get value(): number;
     set value(v: number);
     /**
-     * The value as a fraction, `0` at `min` and `1` at `max`.
-     *
-     * This is what the fill is drawn from, and what a caller usually wants for
-     * anything else keyed to the same number. Read only; set
-     * {@link ProgressBar#value}.
+     * The value as a fraction, `0` at `min` and `1` at `max`; how full the
+     * bar is drawn. Always within `0..1`, and `0` when `min` equals `max`.
+     * Read only: set {@link ProgressBar#value} instead.
      */
     get ratio(): number;
     /**

package/build/renderable/ui/progressbar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progressbar.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/progressbar.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"progressbar.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/progressbar.ts"],"names":[],"mappings":"AACA,OAAO,EAAO,EAAE,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,UAAU,MAAM,kBAAkB,CAAC;AAC1C,OAAO,IAAI,MAAM,iBAAiB,CAAC;AACnC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAG7C;;;;;GAKG;AACH,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC7B,eAAe,GACf,eAAe,GACf,eAAe,GACf,eAAe,CAAC;AAEnB;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,KAAK,IAAI,CAAC;IACpE;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACvD;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0HG;AACH,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,UAAU;IAClD,uEAAuE;IACvE,SAAS,EAAE,oBAAoB,CAAC;IAChC,0DAA0D;IAC1D,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;IACzB,uEAAuE;IACvE,SAAS,EAAE,KAAK,CAAC;IACjB,gDAAgD;IAChD,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,QAAQ,CAAC,EACN,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,KAAK,IAAI,CAAC,GAC1D,SAAS,CAAC;IACb,qEAAqE;IACrE,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACtD,wDAAwD;IACxD,KAAK,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IACzB,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAE3C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IAYrB;;;;OAIG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB;IAgE/D;;;;;;;;OAQG;IACH,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,GAAG,CAAC,CAAC,EAAE,MAAM,EAIhB;IAED;;;;;;;;;OASG;IACH,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,GAAG,CAAC,CAAC,EAAE,MAAM,EAIhB;IAqBD;;;;;;;;OAQG;IACH,IAAI,KAAK,IAII,MAAM,CAFlB;IAED,IAAI,KAAK,CAAC,CAAC,EAAE,MAAM,EAWlB;IAED;;;;OAIG;IACH,IAAI,KAAK,WAGR;IAYD;;;;OAIG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM;IAKlB;;;OAGG;IACM,IAAI,CAAC,QAAQ,EAAE,QAAQ;CA+GhC"}