melonjs 20.7.0 → 20.9.0

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

@@ -4,7 +4,36 @@ import Container from "../container.js";
 /**
  * This is a basic clickable and draggable container which you can use in your game UI.
  * Use this for example if you want to display a panel that contains text, images or other UI elements.
+ *
+ * Regions under the pointer are asked in the order they are drawn, topmost
+ * first, and the walk carries on downwards until a handler returns `false`. An
+ * element that can overlap another one is therefore not opaque until it says
+ * so: by default a widget it covers still answers clicks and still lights up on
+ * hover. {@link UIBaseElement#onClick}, {@link UIBaseElement#onRelease} and
+ * {@link UIBaseElement#onOver} each consume by returning `false`.
  * @category UI
+ * @example
+ * // a panel that is opaque to the pointer and comes to the front when picked
+ * class Panel extends UIBaseElement {
+ *     onClick() {
+ *         this.ancestor.moveToTop(this);
+ *         return false;
+ *     }
+ *     // the frame the pointer crosses in
+ *     onOver() {
+ *         return false;
+ *     }
+ *     // and every frame after that, when the pointer is already inside and
+ *     // `onOver` no longer fires
+ *     onActivateEvent() {
+ *         super.onActivateEvent();
+ *         me.input.registerPointerEvent("pointermove", this, () => false);
+ *     }
+ *     onDeactivateEvent() {
+ *         me.input.releasePointerEvent("pointermove", this);
+ *         super.onDeactivateEvent();
+ *     }
+ * }
  */
 export default class UIBaseElement extends Container {
     /**
@@ -65,12 +94,28 @@ export default class UIBaseElement extends Container {
      */
     onMove(_event?: Pointer): void;
     /**
-     * function called when the pointer is over the object
+     * function called when the pointer is over the object.
+     *
+     * Fires once, on the frame the pointer crosses into the element. To stay
+     * opaque for as long as the pointer rests on it, an element also wants a
+     * `"pointermove"` callback registered through
+     * {@link input.registerPointerEvent} returning `false`, since by then the
+     * pointer is already inside and this no longer runs.
      * @param _event - the event object
+     * @returns return false if we need to stop propagating the event, so that an
+     * element covered by this one does not also light up on hover
      */
-    onOver(_event?: Pointer): void;
+    onOver(_event?: Pointer): boolean | void;
     /**
-     * function called when the pointer is leaving the object area
+     * function called when the pointer is leaving the object area.
+     *
+     * Fires when the pointer leaves the element's bounds, and also when it is
+     * still inside them but something drawn above has consumed the move, since
+     * the pointer is then over that instead.
+     *
+     * Unlike {@link UIBaseElement#onOver} this one cannot consume the event, on
+     * purpose: an element that suppressed its own leave would stay in its hover
+     * state after the pointer had gone.
      * @param _event - the event object
      */
     onOut(_event?: Pointer): void;

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

@@ -1 +1 @@
-{"version":3,"file":"uibaseelement.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uibaseelement.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIvD,OAAO,SAAS,MAAM,iBAAiB,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,SAAS;IACnD;;;;;OAKG;IACM,QAAQ,UAAQ;IAEzB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;IAEf;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAGlB,WAAW,EAAE,MAAM,CAAC;IAGpB,UAAU,EAAE,QAAQ,GAAG,SAAS,CAAC;IAEjC;;;;;OAKG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM;IA+CxD;;;;OAIG;IAEH,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAuClC;;;OAGG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAI9B;;;OAGG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAuB9B;;;OAGG;IAEH,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAmB7B;;;;OAIG;IAEH,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAkBpC;;;OAGG;IACH,MAAM,IAAI,IAAI;CA4Dd"}
+{"version":3,"file":"uibaseelement.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uibaseelement.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIvD,OAAO,SAAS,MAAM,iBAAiB,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,SAAS;IACnD;;;;;OAKG;IACM,QAAQ,UAAQ;IAEzB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;IAEf;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAGlB,WAAW,EAAE,MAAM,CAAC;IAGpB,UAAU,EAAE,QAAQ,GAAG,SAAS,CAAC;IAEjC;;;;;OAKG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM;IA+CxD;;;;OAIG;IAEH,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAuClC;;;OAGG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAI9B;;;;;;;;;;;OAWG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI;IAuBxC;;;;;;;;;;;OAWG;IAEH,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAmB7B;;;;OAIG;IAEH,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAkBpC;;;OAGG;IACH,MAAM,IAAI,IAAI;CA4Dd"}

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

@@ -0,0 +1,245 @@
+import type Camera2d from "../../camera/camera2d.ts";
+import type { Matrix3d } from "../../math/matrix3d.ts";
+import type { Vector3d } from "../../math/vector3d.ts";
+import type Renderer from "../../video/renderer.js";
+import type { Paint } from "./panelpaint.ts";
+import UIBaseElement from "./uibaseelement.ts";
+/**
+ * Everything {@link UIPanel} takes.
+ */
+export interface UIPanelSettings {
+    /** the panel's width, in pixels */
+    width: number;
+    /** the panel's height, in pixels */
+    height: number;
+    /**
+     * The fill behind the children; `null` leaves it transparent.
+     *
+     * NOT `backgroundColor`, which a `Container` already has and which does
+     * something else entirely: that one is handed to `clearColor` and wipes
+     * the whole render target, so a panel setting it would repaint the
+     * screen. The name here matches {@link ProgressBarSettings} instead.
+     */
+    fillColor?: Paint | null;
+    /** drawn around the edge; `null` for none */
+    borderColor?: Paint | null;
+    /** how thick that border is */
+    borderWidth?: number;
+    /** corner radius; `0` is square */
+    radius?: number;
+    /**
+     * How far the panel drifts up and down, in pixels. `0`, the default,
+     * leaves it still.
+     *
+     * See {@link UIPanel#bobAmplitude}.
+     */
+    bobAmplitude?: number;
+    /**
+     * How long one full up and down cycle takes, in milliseconds.
+     *
+     * See {@link UIPanel#bobPeriod}.
+     */
+    bobPeriod?: number;
+    /**
+     * Whether the panel swallows pointer events aimed at what is behind it.
+     *
+     * `true` by default, which is what a dialog wants: a click on the panel,
+     * or on the dimmed scene it covers, must not reach the game underneath.
+     * Children are unaffected either way, because the dispatcher asks a child
+     * before the container holding it.
+     *
+     * Set `false` for a panel that is only a backdrop, such as a HUD frame
+     * drawn over a playfield that still has to receive clicks.
+     */
+    blocking?: boolean;
+}
+/**
+ * A rectangular surface with a background, an optional border and children.
+ *
+ * The thing every menu, dialog and HUD frame starts by writing: a rounded
+ * rectangle, a fill, an outline, and some labels on top. One example in this
+ * repository had three of them, each repeating the same half dozen renderer
+ * calls, and each repeating the same correction for the way `setColor` folds
+ * the global alpha in. That correction is the reason this is a widget rather
+ * than a snippet: it is easy to leave out, and leaving it out does not fail,
+ * it just renders a panel at the wrong opacity.
+ *
+ * It is a {@link UIBaseElement}, so it is a container that carries pointer
+ * events, and children added to it are drawn over its background and are
+ * asked about a click before it is.
+ *
+ * It is floating, as every UI element is, and where it lands in the paint
+ * order is the depth it is added at. In a world sorted on `"depth"`, which
+ * is every `Camera3d` scene, that depth is read the other way round from
+ * the 2D habit: a floating child is ranked by `|pos.z|` there and the
+ * SMALLER magnitude draws on top, so a panel added at 9000 to sit above
+ * everything sits behind everything instead, and a dialog there wants a
+ * small depth, 0 or 1.
+ * @example
+ * import { UIPanel, Text } from "melonjs";
+ *
+ * const panel = new UIPanel(cx - 200, cy - 120, {
+ *     width: 400,
+ *     height: 240,
+ *     fillColor: "#0a1526",
+ *     borderColor: "rgba(130, 200, 240, 0.55)",
+ *     borderWidth: 2,
+ *     radius: 14,
+ * });
+ * // positioned relative to the panel, not to the screen
+ * panel.addChild(new Text(200, 24, { text: "PAUSED", textAlign: "center" }));
+ * app.world.addChild(panel);
+ * @category UI
+ */
+export default class UIPanel extends UIBaseElement {
+    /** the fill behind the children; `null` leaves it transparent */
+    fillColor: Paint | null;
+    /** drawn around the edge; `null` for none */
+    borderColor: Paint | null;
+    /** how thick that border is */
+    borderWidth: number;
+    /** corner radius; `0` is square */
+    radius: number;
+    /** whether it swallows pointer events aimed at what is behind it */
+    blocking: boolean;
+    /**
+     * How far the panel drifts up and down, in pixels. `0`, the default,
+     * leaves it still.
+     *
+     * The slow float an idle dialogue or pause panel has in a lot of games,
+     * which is there so a screen waiting for input does not look frozen. It
+     * is a sine, so this is the distance to either extreme and the panel
+     * covers twice it over a cycle; 2 to 4 is the usual range, and it starts
+     * by rising rather than sinking.
+     *
+     * Do not go much below 2. The renderer snaps a translation to whole
+     * pixels, truncating, so an amplitude of 1 spends most of the cycle
+     * reading as 0 and the panel twitches rather than drifts.
+     *
+     * The panel is CLICKABLE where it is drawn: the offset goes into
+     * {@link UIPanel#getAbsolutePosition}, which is what the bounds pipeline
+     * reads, so the hit area of the panel and of every widget inside it
+     * follows the float at any depth. `pos` is deliberately left alone, so a
+     * caller still reads and writes the resting place rather than a value
+     * that moves under them.
+     *
+     * The bounds are rebuilt only on the frames the offset actually changes,
+     * so a panel with no bob costs nothing.
+     * @default 0
+     */
+    bobAmplitude: number;
+    /**
+     * How long one full up and down cycle takes, in milliseconds.
+     *
+     * Anything at or below zero turns the bob off rather than dividing by it.
+     * That is not politeness: the offset would be `NaN`, and one `translate`
+     * by `NaN` writes it into the transform, where every batched vertex under
+     * it inherits the poison and the GPU clips the lot away. A panel that
+     * silently vanished would be a long way from an obviously bad period.
+     * @default 2000
+     */
+    bobPeriod: number;
+    /**
+     * @param x - position of the panel's left edge
+     * @param y - position of the panel's top edge
+     * @param settings - see {@link UIPanelSettings}
+     */
+    constructor(x: number, y: number, settings: UIPanelSettings);
+    /**
+     * Advance the bob.
+     * @param dt - time since the last frame, in milliseconds
+     * @returns whether the panel needs redrawing
+     */
+    update(dt: number): boolean;
+    /**
+     * Draw the fill, the border, and then the children over both.
+     * @param renderer - the renderer to draw with
+     * @param viewport - the camera being drawn through, passed to the children
+     */
+    draw(renderer: Renderer, viewport?: Camera2d): void;
+    /**
+     * Where the panel IS, bob included.
+     *
+     * THE hook that makes a floating panel honest. Both bounds paths funnel
+     * through this one method, and a child's absolute position is the sum of
+     * the chain above it, so adding the offset here reaches the panel's own
+     * hit area and every descendant's, at any depth, without any of them
+     * knowing a bob exists.
+     *
+     * Not `currentTransform`, which was the obvious guess: that reaches a
+     * renderable's OWN bounds and not its children's, so a bobbing panel's
+     * swallow rectangle would drift off the widgets sitting in it. And not a
+     * write to `pos`, which would reach everything correctly but silently
+     * overwrite a caller's own write on the very next frame.
+     *
+     * {@link Particle} overrides this method for the same reason, its
+     * placement not being in its `pos` chain either.
+     * @returns the absolute position, offset by the bob
+     */
+    getAbsolutePosition(): Vector3d;
+    /**
+     * The matrix form of the same offset.
+     *
+     * Without it `getWorldTransform()` and `getAbsolutePosition()` disagree
+     * about a bobbing panel, and the contract on those two says that for a
+     * `Container` they coincide.
+     * @param out - matrix to write into
+     * @returns `out`, for chaining
+     */
+    protected getLocalTransform(out: Matrix3d): Matrix3d;
+    /**
+     * Resize this panel's bounds, and refresh its children's.
+     *
+     * `Container` does those two jobs in ONE loop, both gated on
+     * `enableChildBoundsUpdate`, and a panel wants exactly one of them. The
+     * flag is off here so that a label overhanging the edge cannot grow the
+     * rectangle a blocking panel swallows clicks inside, and turning it off
+     * took the other job with it: a child's bounds are absolute, worked out
+     * once through `getAbsolutePosition()` and then cached, so moving the
+     * panel left every child's HIT AREA behind at the old place while the
+     * whole panel drew at the new one. A dialog slid or snapped into position
+     * after it was built had buttons that only answered where they used to
+     * be.
+     *
+     * This costs nothing per frame: `pos` calls `updateBounds` when it is
+     * written, so the walk happens when the panel actually moves.
+     * @param absolute - update in world absolute coordinates
+     * @returns this panel's bounds
+     */
+    updateBounds(absolute?: boolean): import("../../index.ts").Bounds;
+    /**
+     * Consume a click on the panel itself, unless told not to.
+     *
+     * Returning `false` is how {@link UIBaseElement} consumes. A child is
+     * asked before the container holding it, so this only ever sees a click
+     * that missed every one of them, which for a dialog means a click on its
+     * own background and should go no further.
+     * @returns false while {@link UIPanel#blocking}
+     */
+    onClick(): boolean;
+    /**
+     * Consume the release that follows a click on the panel, unless told not
+     * to.
+     *
+     * The three handlers consume independently. Taking the press and leaving
+     * the release is half a block: the pointer-up still reaches whatever is
+     * under the dialog, so a button there completes an interaction it never
+     * began.
+     * @returns false while {@link UIPanel#blocking}
+     */
+    onRelease(): boolean;
+    /**
+     * Consume a hover on the panel itself, unless told not to.
+     *
+     * Without this a widget UNDER a dialog keeps lighting up as the pointer
+     * crosses the panel covering it.
+     * @returns false while {@link UIPanel#blocking}
+     */
+    onOver(): boolean;
+    /**
+     * Hand back what the painter borrowed.
+     * @ignore
+     */
+    onDestroyEvent(): void;
+}
+//# sourceMappingURL=uipanel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"uipanel.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uipanel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACzB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,OAAO,OAAO,OAAQ,SAAQ,aAAa;IACjD,iEAAiE;IACjE,SAAS,EAAE,KAAK,GAAG,IAAI,CAAC;IACxB,6CAA6C;IAC7C,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,SAAS,EAAE,MAAM,CAAC;IAmClB;;;;OAIG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe;IAiE3D;;;;OAIG;IACM,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAmBpC;;;;OAIG;IACM,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,QAAQ;IA6CrD;;;;;;;;;;;;;;;;;;OAkBG;IACM,mBAAmB,IAAI,QAAQ;IAMxC;;;;;;;;OAQG;cACgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ;IAS7D;;;;;;;;;;;;;;;;;;OAkBG;IACM,YAAY,CAAC,QAAQ,UAAO;IAQrC;;;;;;;;OAQG;IACM,OAAO,IAAI,OAAO;IAI3B;;;;;;;;;OASG;IACM,SAAS,IAAI,OAAO;IAI7B;;;;;;OAMG;IACM,MAAM,IAAI,OAAO;IAI1B;;;OAGG;IACM,cAAc;CAIvB"}

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

@@ -74,12 +74,28 @@ export default class UISpriteElement extends Sprite {
      */
     onClick(_event?: Pointer): boolean;
     /**
-     * function called when the pointer is over the object
+     * function called when the pointer is over the object.
+     *
+     * Fires once, on the frame the pointer crosses into the element. To stay
+     * opaque for as long as the pointer rests on it, an element also wants a
+     * `"pointermove"` callback registered through
+     * {@link input.registerPointerEvent} returning `false`, since by then the
+     * pointer is already inside and this no longer runs.
      * @param _event - the event object
+     * @returns return false if we need to stop propagating the event, so that an
+     * element covered by this one does not also light up on hover
      */
-    onOver(_event?: Pointer): void;
+    onOver(_event?: Pointer): boolean | void;
     /**
-     * function called when the pointer is leaving the object area
+     * function called when the pointer is leaving the object area.
+     *
+     * Fires when the pointer leaves the element's bounds, and also when it is
+     * still inside them but something drawn above has consumed the move, since
+     * the pointer is then over that instead.
+     *
+     * Unlike {@link UISpriteElement#onOver} this one cannot consume the event, on
+     * purpose: an element that suppressed its own leave would stay in its hover
+     * state after the pointer had gone.
      * @param _event - the event object
      */
     onOut(_event?: Pointer): void;

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

@@ -1 +1 @@
-{"version":3,"file":"uispriteelement.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uispriteelement.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAC;AAEpD,OAAO,MAAM,MAAM,gBAAgB,CAAC;AAEpC;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,eAAgB,SAAQ,MAAM;IAClD;;;;;OAKG;IACM,QAAQ,UAAQ;IAEzB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;IAGf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;gBAEF,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE;IAyC7C;;;;OAIG;IAEH,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAelC;;;OAGG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAgB9B;;;OAGG;IAEH,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAmB7B;;;;OAIG;IAEH,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAkBpC;;;OAGG;IACH,MAAM,IAAI,IAAI;CAyCd"}
+{"version":3,"file":"uispriteelement.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uispriteelement.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAC;AAEpD,OAAO,MAAM,MAAM,gBAAgB,CAAC;AAEpC;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,eAAgB,SAAQ,MAAM;IAClD;;;;;OAKG;IACM,QAAQ,UAAQ;IAEzB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;IAGf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;gBAEF,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE;IAyC7C;;;;OAIG;IAEH,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAelC;;;;;;;;;;;OAWG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI;IAgBxC;;;;;;;;;;;OAWG;IAEH,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAmB7B;;;;OAIG;IAEH,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAkBpC;;;OAGG;IACH,MAAM,IAAI,IAAI;CAyCd"}

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

@@ -1,5 +1,6 @@
 import type Camera2d from "../../camera/camera2d.ts";
 import { RoundRect } from "../../geometries/roundrect.ts";
+import type Pointer from "../../input/pointer.ts";
 import type { Bounds } from "../../physics/bounds.ts";
 import type Renderer from "../../video/renderer.js";
 import BitmapText from "../text/bitmaptext.js";
@@ -8,6 +9,7 @@ interface UITextButtonSettings {
     font?: string;
     size?: number;
     text?: string;
+    /** see {@link UITextButton.bindKey} */
     bindKey?: string | number;
     hoverOffColor?: string;
     hoverOnColor?: string;
@@ -25,9 +27,31 @@ interface UITextButtonSettings {
  */
 export default class UITextButton extends UIBaseElement {
     /**
-     * The key to bind the action to
+     * Keyboard shortcut: an input.KEY keycode or an existing input action name.
+     * A press calls onClick() and its matching release calls onRelease(), both
+     * without a pointer event. Shortcuts are active only while the button is
+     * activated and never change global key bindings. The first input to press
+     * owns the button until released; shortcuts do not start pointer dragging
+     * or tap-and-hold.
+     *
+     * `isClickable` gates the PRESS, not the release: a button disabled while
+     * its key is held still releases when that key comes up, so it cannot be
+     * left stuck down.
+     *
+     * **Losing focus or being removed cancels a held press WITHOUT calling
+     * `onRelease()`.** The press was abandoned rather than completed, so the
+     * button returns to its released state silently. Code that treats the pair
+     * as press and depress, firing a weapon on click and stopping on release,
+     * needs to stop on {@link event.BLUR} too or it will still be firing when
+     * the window comes back.
+     * @default -1
      */
     bindKey: string | number;
+    private keyboardKey;
+    private keyboardActive;
+    private readonly keyDown;
+    private readonly keyUp;
+    private readonly cancelKeyboardPress;
     /**
      * The css value of a color to be used if the pointer is not hovering over the button
      */
@@ -95,6 +119,11 @@ export default class UITextButton extends UIBaseElement {
      * world.addChild(new PlayButton(15,200));
      */
     constructor(x: number, y: number, settings: UITextButtonSettings);
+    onActivateEvent(): void;
+    onDeactivateEvent(): void;
+    clicked(event: Pointer): boolean | void;
+    release(event: Pointer): boolean | void;
+    pointerMove(event: Pointer): void;
     draw(renderer: Renderer, viewport?: Camera2d): void;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"uitextbutton.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uitextbutton.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAE/C,UAAU,oBAAoB;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,aAAa;IACtD;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,UAAU,EAAE,UAAU,CAAC;IAEvB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,EAAE,SAAS,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB;IAyCvD,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI;CAY5D"}
+{"version":3,"file":"uitextbutton.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uitextbutton.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC1D,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAE/C,UAAU,oBAAoB;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,aAAa;IACtD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzB,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,cAAc,CAAS;IAE/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAkBtB;IAEF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAQpB;IAEF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAMlC;IAEF;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,UAAU,EAAE,UAAU,CAAC;IAEvB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,EAAE,SAAS,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB;IAyCvD,eAAe,IAAI,IAAI;IAWvB,iBAAiB,IAAI,IAAI;IASzB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI;IAOvC,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI;IAOvC,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAMjC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI;CAY5D"}

package/build/state/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/state/state.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,MAAM,qBAAqB,CAAC;AA4QxC;;GAEG;AACH,QAAA,MAAM,KAAK;IACV;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;;OAGG;;IAGH;;;;;;;OAOG;;IAGH;;;OAGG;4BACoB,OAAO,GAAW,IAAI;IAqB7C;;;OAGG;kBACU,OAAO,GAAW,IAAI;IAkBnC;;;OAGG;oBACY,OAAO,GAAW,IAAI;IAiBrC;;;OAGG;mBACW,OAAO,GAAW,IAAI;IAmBpC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;qBACc,MAAM,UAAS,OAAO,GAAW,OAAO,CAAC,IAAI,CAAC;IAkC/D;;;OAGG;iBACU,OAAO;IAIpB;;;OAGG;gBACS,OAAO;IAInB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;iBACU,MAAM,SAAS,KAAK,UAAS,OAAO,GAAW,IAAI;IAchE;;;;;OAKG;kBACU,MAAM,GAAY,KAAK,GAAG,SAAS;IAQhD;;;;OAIG;eACQ,KAAK,GAAG,SAAS;IAI5B;;;;;;;;;;;;;;;;;;OAkBG;uBAEM,MAAM,GAAG,MAAM,SAChB,MAAM,aACH,MAAM,UAEb,OAAO,0BAA0B,EAAE,OAAO,GAC1C,OAAO,0BAA0B,EAAE,OAAO,GAC3C,IAAI;IAOP;;;;OAIG;2BACoB,MAAM,UAAU,OAAO,GAAG,IAAI;IAIrD;;;;;;;;;OASG;oBAEO,MAAM,gBACF,OAAO,gBACN,OAAO,EAAE,GACrB,IAAI;IA4FP;;;;OAIG;uBACgB,MAAM,GAAG,OAAO;CAGnC,CAAC;AACF,eAAe,KAAK,CAAC"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/state/state.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,MAAM,qBAAqB,CAAC;AA4QxC;;GAEG;AACH,QAAA,MAAM,KAAK;IACV;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;;OAGG;;IAGH;;;;;;;OAOG;;IAGH;;;OAGG;4BACoB,OAAO,GAAW,IAAI;IAqB7C;;;OAGG;kBACU,OAAO,GAAW,IAAI;IAkBnC;;;OAGG;oBACY,OAAO,GAAW,IAAI;IAiBrC;;;OAGG;mBACW,OAAO,GAAW,IAAI;IAmBpC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;qBACc,MAAM,UAAS,OAAO,GAAW,OAAO,CAAC,IAAI,CAAC;IAkC/D;;;OAGG;iBACU,OAAO;IAIpB;;;OAGG;gBACS,OAAO;IAInB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;iBACU,MAAM,SAAS,KAAK,UAAS,OAAO,GAAW,IAAI;IAchE;;;;;OAKG;kBACU,MAAM,GAAY,KAAK,GAAG,SAAS;IAQhD;;;;OAIG;eACQ,KAAK,GAAG,SAAS;IAI5B;;;;;;;;;;;;;;;;;;OAkBG;uBAEM,MAAM,GAAG,MAAM,SAChB,MAAM,aACH,MAAM,UAEb,OAAO,0BAA0B,EAAE,OAAO,GAC1C,OAAO,0BAA0B,EAAE,OAAO,GAC3C,IAAI;IAOP;;;;OAIG;2BACoB,MAAM,UAAU,OAAO,GAAG,IAAI;IAIrD;;;;;;;;;OASG;oBAEO,MAAM,gBACF,OAAO,gBACN,OAAO,EAAE,GACrB,IAAI;IA0GP;;;;OAIG;uBACgB,MAAM,GAAG,OAAO;CAGnC,CAAC;AACF,eAAe,KAAK,CAAC"}

package/build/system/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/system/bootstrap.ts"],"names":[],"mappings":"AAsBA;;GAEG;AACH,eAAO,IAAI,WAAW,SAAQ,CAAC;AAE/B;;;;;;GAMG;AACH,wBAAgB,IAAI,SA0DnB"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/system/bootstrap.ts"],"names":[],"mappings":"AAmBA;;GAEG;AACH,eAAO,IAAI,WAAW,SAAQ,CAAC;AAE/B;;;;;;GAMG;AACH,wBAAgB,IAAI,SAmDnB"}

package/build/system/legacy_pool.d.ts

@@ -27,6 +27,17 @@ declare const pool: ObjectPool;
  * which means, that on level loading the engine will try to instantiate every object
  * found in the map, based on the user defined name in each Object Properties<br>
  * <img src="../images/object_properties.png"/><br>
+ *
+ * **Superseded by the typed pools.** `createPool` arrived in 18.0.0 and does
+ * the same job without the string keys: `getPool("tween")`, `getPool("text")`
+ * and the rest are typed, so a wrong name is a compile error rather than a
+ * throw, and a pool can be created for any class with `createPool`. For
+ * registering a class so a Tiled map can name it, use
+ * {@link registerTiledObjectClass}, which is what this now delegates to.
+ *
+ * The engine itself no longer uses this pool for anything.
+ * @deprecated since 18.0.0, use {@link getPool} / `createPool`, and
+ * {@link registerTiledObjectClass} for Tiled classes
  * @see {@link pool} the default global instance of ObjectPool
  */
 declare class ObjectPool {
@@ -76,7 +87,7 @@ declare class ObjectPool {
     /**
      * Pull a new instance of the requested object (if added into the object pool)
      * @param {string} name - as used in {@link pool.register}
-     * @param {...*} [args] - arguments to be passed when instantiating/reinitializing the object
+     * @param {...*} args - arguments to be passed when instantiating/reinitializing the object
      * @returns {object} the instance of the requested object
      * @example
      * me.pool.register("bullet", BulletEntity, true);
@@ -94,7 +105,7 @@ declare class ObjectPool {
      * app.world.removeChild(enemy);
      * app.world.removeChild(bullet);
      */
-    pull(name: string, ...args?: any[]): object;
+    pull(name: string, ...args: any[]): object;
     /**
      * purge the object pool from any inactive object <br>
      * Object pooling must be enabled for this function to work<br>
@@ -106,9 +117,18 @@ declare class ObjectPool {
      * Object pooling for the object class must be enabled,
      * and object must have been instantiated using {@link pull},
      * otherwise this function won't work
-     * @throws will throw an error if the object cannot be recycled
+     *
+     * Reports failure by RETURNING FALSE. It used to throw by default, and
+     * nothing at the call site made that visible: a class that was never
+     * registered, or registered without recycling, aborted whatever was
+     * running. Both of the internal uses removed in 20.7.0 failed that way,
+     * inside a `destroy()` that had already recycled other state, which left
+     * a half-torn-down object to die later somewhere unrelated. Pass
+     * `throwOnError` to opt back in where a missed registration is a bug you
+     * want to hear about immediately.
      * @param {object} obj - instance to be recycled
-     * @param {boolean} [throwOnError=true] - throw an exception if the object cannot be recycled
+     * @param {boolean} [throwOnError=false] - throw an exception instead of returning false
+     * @throws when the object cannot be recycled AND `throwOnError` is true
      * @returns {boolean} true if the object was successfully recycled in the object pool
      */
     push(obj: object, throwOnError?: boolean): boolean;

package/build/system/legacy_pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legacy_pool.d.ts","sourceRoot":"","sources":["../../src/system/legacy_pool.js"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,kEAEC;;AAmND;;;;;;;;;;;;;;GAcG;AACH,+BAA8B;AAhO9B;;;;;;;;;;;;GAYG;AACH;IAEE,gBAAqB;IACrB,yBAAyB;IAEzB;;;;;;;;;;;;;;OAcG;IACH,mBARU,OAAO,CAQY;IAG9B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,oBAhBW,MAAM,YACN,MAAM,cACN,OAAO,QAsCjB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAnBW,MAAM,YACH,GAAC,EAAA,GACF,MAAM,CAsClB;IAED;;;;OAIG;IACH,cAOC;IAED;;;;;;;;;OASG;IACH,UAJW,MAAM,iBACN,OAAO,GACL,OAAO,CAgBnB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;OAUG;IACH,cAPW,MAAM,GACJ,OAAO,CAcnB;IAED;;;OAGG;IACH,oBAFa,MAAM,CAIlB;CACD"}
+{"version":3,"file":"legacy_pool.d.ts","sourceRoot":"","sources":["../../src/system/legacy_pool.js"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,kEAEC;;AA4QD;;;;;;;;;;;;;;GAcG;AACH,+BAA8B;AAvP9B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAEE,gBAAqB;IACrB,yBAAyB;IAEzB;;;;;;;;;;;;;;OAcG;IACH,mBARU,OAAO,CAQY;IAG9B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,oBAhBW,MAAM,YACN,MAAM,cACN,OAAO,QAuCjB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAnBW,MAAM,WACH,GAAC,EAAA,GACF,MAAM,CAuClB;IAED;;;;OAIG;IACH,cAOC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,UALW,MAAM,iBACN,OAAO,GAEL,OAAO,CAiBnB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;OAUG;IACH,cAPW,MAAM,GACJ,OAAO,CAcnB;IAED;;;OAGG;IACH,oBAFa,MAAM,CAIlB;CACD"}

package/build/system/pool.d.ts

@@ -1,17 +1,24 @@
-export interface Pool<T, A extends unknown[]> {
+export interface Pool<T extends object, A extends unknown[]> {
     get(...args: A): T;
     release(object: T): void;
     purge(): void;
     size(): number;
     used(): number;
 }
-type Reset<A extends unknown[]> = ((...args: A) => void) | undefined;
-type Release = (() => void) | undefined;
-export interface CreatePoolOptions<T, A extends unknown[]> {
+export interface CreatePoolOptions<T extends object, A extends unknown[]> {
     instance: T;
-    reset?: Reset<A>;
-    release?: Release;
+    reset?: ((...args: A) => void) | undefined;
+    release?: (() => void) | undefined;
 }
-export declare const createPool: <T, A extends unknown[]>(options: (...args: A) => CreatePoolOptions<T, A>) => Pool<T, A>;
-export {};
+/**
+ * Register a pool instance to the pool registry.
+ *
+ * Public because `pool.js` re-exports it. Marked internal it was stripped
+ * from the declarations while that re-export kept naming it, which left the
+ * public `pool` module exporting something no longer declared.
+ * @param key - the name this pool is reachable by
+ * @param pool - the pool instance to register under it
+ */
+export declare const registerPool: (key: string, pool: Pool<any, any[]>) => void;
+export declare const createPool: <T extends object, A extends unknown[]>(options: (...args: A) => CreatePoolOptions<T, A>) => Pool<T, A>;
 //# sourceMappingURL=pool.d.ts.map

package/build/system/pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/system/pool.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EAAE;IAC3C,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,MAAM,CAAC;IACf,IAAI,IAAI,MAAM,CAAC;CACf;AAED,KAAK,KAAK,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;AACrE,KAAK,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;AAExC,MAAM,WAAW,iBAAiB,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EAAE;IACxD,QAAQ,EAAE,CAAC,CAAC;IACZ,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAoBD,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,SAAS,OAAO,EAAE,EAChD,SAAS,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,KAC9C,IAAI,CAAC,CAAC,EAAE,CAAC,CA2DX,CAAC"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/system/pool.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,EAAE;IAC1D,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,MAAM,CAAC;IACf,IAAI,IAAI,MAAM,CAAC;CACf;AAKD,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,EAAE;IACvE,QAAQ,EAAE,CAAC,CAAC;IAIZ,KAAK,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAC3C,OAAO,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CACnC;AAKD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,SAE/D,CAAC;AAuEF,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,EAAE,EAC/D,SAAS,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,KAC9C,IAAI,CAAC,CAAC,EAAE,CAAC,CAyGX,CAAC"}

package/build/tweens/tween.d.ts

@@ -1,5 +1,21 @@
 import { EasingFunction } from "./easing.js";
 import { InterpolationFunction } from "./interpolation.js";
+/**
+ * Called once when a tween starts, with `this` bound to the tweened object.
+ * @see Tween#onStart
+ */
+export type OnStartCallback<T> = (this: T) => void;
+/**
+ * Called on every tween step with the eased progress in `[0, 1]`, and `this`
+ * bound to the tweened object.
+ * @see Tween#onUpdate
+ */
+export type OnUpdateCallback<T> = (this: T, value: number) => void;
+/**
+ * Called once when a tween finishes, with `this` bound to the tweened object.
+ * @see Tween#onComplete
+ */
+export type OnCompleteCallback<T> = (this: T) => void;
 /**
  * A tweening engine for smoothly interpolating object properties over time.
  * Based on <a href="https://github.com/sole/Tween.js">tween.js</a> with
@@ -140,12 +156,43 @@ export default class Tween {
     onComplete(onCompleteCallback: OnCompleteCallback<object>): this;
     /**
      * Available easing functions, accessed via `Tween.Easing`.
-     * Each family provides `In`, `Out`, and `InOut` variants.
-     * @see {@link Easing} for the full list
+     *
+     * Eleven families, each providing `In`, `Out` and `InOut`. `In` applies the
+     * curve at the start, `Out` at the end, and `InOut` at both. `Out` is what
+     * most UI wants: the value arrives decisively rather than creeping in.
+     *
+     * | family | shape | reach for it when |
+     * | --- | --- | --- |
+     * | `Linear.None` | no curve at all | the value IS the progress, e.g. a loading bar |
+     * | `Quadratic` `Cubic` `Quartic` `Quintic` | progressively sharper power curves | general motion; higher powers start slower and finish harder |
+     * | `Sinusoidal` | gentlest of all | a drift or a breath that should not call attention |
+     * | `Exponential` | extreme, near-instant at one end | something that snaps |
+     * | `Circular` | hard, like the quarter of a circle | a mechanical slide |
+     * | `Back` | **overshoots past the target and settles back** | impact: a stamp, a button press, anything that should land rather than arrive |
+     * | `Elastic` | overshoots repeatedly, oscillating | springy, cartoon motion |
+     * | `Bounce` | lands and bounces, settling | something falling onto a surface |
+     *
+     * `Back` and `Elastic` overshoot, so the value LEAVES the range between
+     * your start and end: clamp anything that cannot take it, an opacity or a
+     * colour channel in particular. Note the direction of the overshoot follows
+     * the direction of travel, so a value tweened DOWN to its target overshoots
+     * below it.
+     * @see https://easings.net/ for a visual reference of every curve
      * @example
      * me.Tween.Easing.Quadratic.InOut
      * me.Tween.Easing.Bounce.Out
      * me.Tween.Easing.Elastic.In
+     * @example
+     * // a stamp: scale falls to 1 and springs through it
+     * const driver = { scale: 5 };
+     * new me.Tween(driver)
+     *     .to({ scale: 1 }, { duration: 420 })
+     *     .easing(me.Tween.Easing.Back.Out)
+     *     .onUpdate(() => {
+     *         label.currentTransform.identity();
+     *         label.scale(driver.scale);
+     *     })
+     *     .start();
      */
     static get Easing(): {
         Linear: {
@@ -216,5 +263,5 @@ export default class Tween {
         CatmullRom: (v: number[], k: number) => number;
     };
 }
-export declare const tweenPool: import("../system/pool.ts").Pool<Tween, [obj: object]>;
+export declare const tweenPool: import("../index.ts").Pool<Tween, [obj: object]>;
 //# sourceMappingURL=tween.d.ts.map

package/build/tweens/tween.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tween.d.ts","sourceRoot":"","sources":["../../src/tweens/tween.ts"],"names":[],"mappings":"AAWA,OAAO,EAAU,cAAc,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAiB,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAuB1E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,OAAO,OAAO,KAAK;IAqHzB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAE1B;;OAEG;gBACS,MAAM,EAAE,MAAM;IA+I1B;;;;;;;;;;;;;OAaG;IACH,EAAE,CACD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,CAAC,EAAE;QACT,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;QACpC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACjC,aAAa,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;QAClD,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;KAChC;IAkCF;;;;OAIG;IACH,KAAK,CAAC,IAAI,SAAkB;IA4C5B;;;OAGG;IACH,IAAI;IAKJ;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM;IAKpB;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM;IAKpB;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM;IAK1B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,OAAO;IAKlB;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,cAAc;IAK7B;;;;OAIG;IACH,aAAa,CAAC,aAAa,EAAE,qBAAqB;IAKlD;;;;OAIG;IACH,KAAK,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE;IAKxB;;;;OAIG;IACH,OAAO,CAAC,eAAe,EAAE,eAAe,CAAC,MAAM,CAAC;IAKhD;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,MAAM,CAAC;IAKnD;;;;OAIG;IACH,UAAU,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,MAAM,CAAC;IA0HzD;;;;;;;;OAQG;IACH,MAAM,KAAK,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAEhB;IAED;;;;;;;OAOG;IACH,MAAM,KAAK,aAAa;;;;MAEvB;CACD;AAED,eAAO,MAAM,SAAS,wDASpB,CAAC"}
+{"version":3,"file":"tween.d.ts","sourceRoot":"","sources":["../../src/tweens/tween.ts"],"names":[],"mappings":"AAWA,OAAO,EAAU,cAAc,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAiB,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAO1E;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;AACnD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AACnE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,OAAO,OAAO,KAAK;IAqHzB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAE1B;;OAEG;gBACS,MAAM,EAAE,MAAM;IA+I1B;;;;;;;;;;;;;OAaG;IACH,EAAE,CACD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,CAAC,EAAE;QACT,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;QACpC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACjC,aAAa,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;QAClD,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;KAChC;IAkCF;;;;OAIG;IACH,KAAK,CAAC,IAAI,SAAkB;IA4C5B;;;OAGG;IACH,IAAI;IAKJ;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM;IAKpB;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM;IAKpB;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM;IAK1B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,OAAO;IAKlB;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,cAAc;IAK7B;;;;OAIG;IACH,aAAa,CAAC,aAAa,EAAE,qBAAqB;IAKlD;;;;OAIG;IACH,KAAK,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE;IAKxB;;;;OAIG;IACH,OAAO,CAAC,eAAe,EAAE,eAAe,CAAC,MAAM,CAAC;IAKhD;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,MAAM,CAAC;IAKnD;;;;OAIG;IACH,UAAU,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,MAAM,CAAC;IA0HzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,MAAM,KAAK,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAEhB;IAED;;;;;;;OAOG;IACH,MAAM,KAAK,aAAa;;;;MAEvB;CACD;AAED,eAAO,MAAM,SAAS,kDASpB,CAAC"}