@datamoc/mw_games 0.25.0 → 0.27.0

package/dist/two-d/pixi-interop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pixi-interop.d.ts","sourceRoot":"","sources":["../../src/two-d/pixi-interop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EACN,SAAS,EACT,MAAM,EACN,OAAO,EACP,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,GACnB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAM7C;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAM3C"}
+{"version":3,"file":"pixi-interop.d.ts","sourceRoot":"","sources":["../../src/two-d/pixi-interop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,gPAAgP;AAChP,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,+OAA+O;AAC/O,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,+OAA+O;AAC/O,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,uLAAuL;AACvL,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,sOAAsO;AACtO,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,0LAA0L;AAC1L,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,wNAAwN;AACxN,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,4OAA4O;AAC5O,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,6IAA6I;AAC7I,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAChE,0FAA0F;AAC1F,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAM7C;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAM3C"}

package/dist/two-d/pixi-interop.js

@@ -21,6 +21,11 @@
  * bundler and tree-shaking configuration the *consumer* uses, not a universal one, and the
  * port whose build tree-shook a pipe away is exactly the case this function is for.
  *
+ * Facade-gap accounting (P31): every primitive below already has a facade family, so no new
+ * facade coverage was needed - what stays interop-only is the Pixi-typed seam each note
+ * names, and a consumer budget justifies a use by pointing at the note instead of merely
+ * counting the import.
+ *
  * @example
  * ```ts
  * import { registerBuiltinPipes, TilingSprite } from '@datamoc/mw_games/two-d/pixi-interop';
@@ -31,7 +36,24 @@
  * const backdrop = new TilingSprite({ texture: undefined as never, width: 100, height: 100 });
  * ```
  */
-export { Container, Sprite, Texture, Graphics, Rectangle, Text, FillGradient, TilingSprite, TilingSpritePipe, NineSliceSpritePipe, } from 'pixi.js';
+/** Interop-only: the unadorned scene-graph node behind facade `Container2D`/`Node2D`. The facade subclasses it rather than wrapping it, so a value that never needed the subclass - or a Pixi API typed against the base - still names this. */
+export { Container } from 'pixi.js';
+/** Interop-only: the textured quad behind facade `Sprite2D`/`TintedSprite`/`AnimatedSprite`. Same subclass relationship: reach for this for Pixi sprite behaviour the facade subclasses do not model, not for an ordinary positioned image. */
+export { Sprite } from 'pixi.js';
+/** Interop-only: the GPU image behind facade `Texture2D`/`TextureRegion`. `TextureRegion` still carries one in its `texture` slot, and Pixi constructors (sprites, tilings, nine-slices, render textures) take one - that slot is the seam. */
+export { Texture } from 'pixi.js';
+/** Interop-only: the vector canvas behind facade `Shape2D`. `Shape2D` extends this with the game's fill/stroke vocabulary; a `Graphics` program outside that vocabulary stays here. */
+export { Graphics } from 'pixi.js';
+/** Interop-only: the Pixi rect behind facade `Rect`. Atlas frames, bounds and hit areas arrive as one; `render.rectOf` converts it to a plain `Rect` at the boundary, and code that hands a rect straight back to Pixi keeps this. */
+export { Rectangle } from 'pixi.js';
+/** Interop-only: the text node behind facade `Text2D`. Same subclass relationship as `Sprite`: ordinary labels are `Text2D`; Pixi text behaviour the facade does not model stays here. */
+export { Text } from 'pixi.js';
+/** Interop-only: the gradient behind facade `Gradient` (which is this, aliased). `Shape2D.fill`/`.stroke` accept it directly, so most gradient work never imports it; direct construction of a gradient object does. */
+export { FillGradient } from 'pixi.js';
+/** Interop-only: the repeating texture behind facade `TiledSprite`. `TiledSprite` extends this; tiling behaviour outside the facade's repeat/offset surface stays here (and needs `registerBuiltinPipes` in a tree-shaken build, below). */
+export { TilingSprite } from 'pixi.js';
+/** Interop-only: renderer pipes, not scene content. Only needed when a consumer bundler tree-shook them away; see `registerBuiltinPipes`. */
+export { TilingSpritePipe, NineSliceSpritePipe } from 'pixi.js';
 import { extensions, TilingSpritePipe, NineSliceSpritePipe } from 'pixi.js';
 let registered = false;
 /**

package/dist/two-d/pixi-interop.js.map

@@ -1 +1 @@
-{"version":3,"file":"pixi-interop.js","sourceRoot":"","sources":["../../src/two-d/pixi-interop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EACN,SAAS,EACT,MAAM,EACN,OAAO,EACP,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,GACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE5E,IAAI,UAAU,GAAG,KAAK,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IACnC,IAAI,UAAU;QAAE,OAAO;IACvB,UAAU,GAAG,IAAI,CAAC;IAElB,UAAU,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACjC,UAAU,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AACrC,CAAC"}
+{"version":3,"file":"pixi-interop.js","sourceRoot":"","sources":["../../src/two-d/pixi-interop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,gPAAgP;AAChP,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,+OAA+O;AAC/O,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,+OAA+O;AAC/O,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,uLAAuL;AACvL,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,sOAAsO;AACtO,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,0LAA0L;AAC1L,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,wNAAwN;AACxN,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,4OAA4O;AAC5O,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,6IAA6I;AAC7I,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAIhE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE5E,IAAI,UAAU,GAAG,KAAK,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IACnC,IAAI,UAAU;QAAE,OAAO;IACvB,UAAU,GAAG,IAAI,CAAC;IAElB,UAAU,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACjC,UAAU,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AACrC,CAAC"}

package/dist/two-d/render/Beam.d.ts

@@ -0,0 +1,93 @@
+import { Container } from 'pixi.js';
+import type { Texture2D } from './Types2D.ts';
+export interface BeamPoint {
+    x: number;
+    y: number;
+}
+export interface BeamOptions {
+    /** plain-line colour; ignored with `texture`. Default white */
+    colour?: number;
+    /** repeating strip drawn instead of a plain line */
+    texture?: Texture2D;
+    /** seconds till `done`; default 0.2 */
+    duration?: number;
+    /** line width, or strip height with a texture; default 2 */
+    width?: number;
+    /** additive blend; default true, set false for a solid beam */
+    additive?: boolean;
+}
+/**
+ * A one-shot beam between two screen points: a fading line by default, a fading
+ * repeating texture strip with `texture`. The sub-second ray flash - a zap, a laser,
+ * a life-link - where `LightningArc` is the persistent jittered geometry and
+ * `MultiTurnBeam` the multi-turn case.
+ *
+ * Fades from full to gone across `duration` and reports `done` exactly once, so a
+ * group can remove it without a second clock. `retarget` moves either endpoint for
+ * a beam tracking two moving points; z-order and parenting stay the caller's.
+ *
+ * @example
+ * ```ts
+ * import { Beam } from '@datamoc/mw_games/two-d/render';
+ *
+ * const zap = new Beam({ x: 0, y: 0 }, { x: 100, y: 0 }, { colour: 0x88ccff, duration: 0.2 });
+ * const expired = zap.update(0.25);
+ * console.log(expired); // true - the instant it outlives its duration
+ * zap.destroy();
+ * ```
+ */
+export declare class Beam extends Container {
+    private from;
+    private to;
+    private readonly colour;
+    private readonly texture?;
+    private readonly thickness;
+    private readonly duration;
+    private readonly body;
+    private elapsed;
+    private expired;
+    constructor(from: BeamPoint, to: BeamPoint, options?: BeamOptions);
+    /** 0 at launch, 1 at duration end */
+    get progress(): number;
+    get done(): boolean;
+    /** moves either endpoint, for a beam tracking two points that are themselves moving */
+    retarget(from?: BeamPoint, to?: BeamPoint): void;
+    /** @returns true the instant `duration` elapses, so a caller can remove the beam exactly once */
+    update(dt: number): boolean;
+    destroy(): void;
+    private redraw;
+}
+/**
+ * Owns the beams a game has flashing: one `add` per ray, one `update(dt)` fading
+ * them all and forgetting the finished ones, and no bookkeeping left to the caller.
+ * Beams are parented here and destroyed with their beam; z-order stays the caller's.
+ *
+ * @example
+ * ```ts
+ * import { Beams } from '@datamoc/mw_games/two-d/render';
+ * import type { Container2D } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const layer: Container2D;
+ *
+ * const beams = new Beams();
+ * layer.addChild(beams);
+ *
+ * beams.add({ x: 0, y: 0 }, { x: 100, y: 0 }, { colour: 0x88ccff });
+ * beams.update(1 / 60);
+ * console.log(beams.count); // 1 - still fading
+ * beams.clear();
+ * ```
+ */
+export declare class Beams extends Container {
+    private readonly live;
+    /** flashes a beam between two points; it fades on `update` and removes itself at duration end */
+    add(from: BeamPoint, to: BeamPoint, options?: BeamOptions): Beam;
+    /** fades every live beam, then forgets and destroys the finished ones */
+    update(dt: number): void;
+    /** how many beams are still fading */
+    get count(): number;
+    /** drops every live beam at once - a scene change, say */
+    clear(): void;
+    destroy(): void;
+}
+//# sourceMappingURL=Beam.d.ts.map

package/dist/two-d/render/Beam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Beam.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/Beam.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAA0B,MAAM,SAAS,CAAC;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,SAAS;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAED,MAAM,WAAW,WAAW;IAC3B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,IAAK,SAAQ,SAAS;IAClC,OAAO,CAAC,IAAI,CAAY;IACxB,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAY;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAE/C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,GAAE,WAAgB,EAiBpE;IAED,qCAAqC;IACrC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,uFAAuF;IACvF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,SAAS,GAAG,IAAI,CAI/C;IAED,iGAAiG;IACjG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAU1B;IAEQ,OAAO,IAAI,IAAI,CAIvB;IAED,OAAO,CAAC,MAAM;CAkBd;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,KAAM,SAAQ,SAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IAEnC,iGAAiG;IACjG,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAK/D;IAED,yEAAyE;IACzE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAQvB;IAED,sCAAsC;IACtC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,0DAA0D;IAC1D,KAAK,IAAI,IAAI,CAKZ;IAEQ,OAAO,IAAI,IAAI,CAGvB;CACD"}

package/dist/two-d/render/Beam.js

@@ -0,0 +1,154 @@
+import { Container, Graphics, TilingSprite } from 'pixi.js';
+/**
+ * A one-shot beam between two screen points: a fading line by default, a fading
+ * repeating texture strip with `texture`. The sub-second ray flash - a zap, a laser,
+ * a life-link - where `LightningArc` is the persistent jittered geometry and
+ * `MultiTurnBeam` the multi-turn case.
+ *
+ * Fades from full to gone across `duration` and reports `done` exactly once, so a
+ * group can remove it without a second clock. `retarget` moves either endpoint for
+ * a beam tracking two moving points; z-order and parenting stay the caller's.
+ *
+ * @example
+ * ```ts
+ * import { Beam } from '@datamoc/mw_games/two-d/render';
+ *
+ * const zap = new Beam({ x: 0, y: 0 }, { x: 100, y: 0 }, { colour: 0x88ccff, duration: 0.2 });
+ * const expired = zap.update(0.25);
+ * console.log(expired); // true - the instant it outlives its duration
+ * zap.destroy();
+ * ```
+ */
+export class Beam extends Container {
+    constructor(from, to, options = {}) {
+        super();
+        this.elapsed = 0;
+        this.expired = false;
+        this.from = { ...from };
+        this.to = { ...to };
+        this.colour = options.colour ?? 0xffffff;
+        this.texture = options.texture;
+        this.thickness = options.width ?? 2;
+        this.duration = Math.max(1e-6, options.duration ?? 0.2);
+        if (this.texture) {
+            this.body = new TilingSprite({ texture: this.texture, width: 1, height: this.thickness });
+        }
+        else {
+            this.body = new Graphics();
+        }
+        if (options.additive ?? true)
+            this.body.blendMode = 'add';
+        this.addChild(this.body);
+        this.redraw();
+    }
+    /** 0 at launch, 1 at duration end */
+    get progress() {
+        return Math.min(1, this.elapsed / this.duration);
+    }
+    get done() {
+        return this.expired;
+    }
+    /** moves either endpoint, for a beam tracking two points that are themselves moving */
+    retarget(from, to) {
+        if (from)
+            this.from = { ...from };
+        if (to)
+            this.to = { ...to };
+        this.redraw();
+    }
+    /** @returns true the instant `duration` elapses, so a caller can remove the beam exactly once */
+    update(dt) {
+        if (this.expired)
+            return false;
+        this.elapsed += dt;
+        this.alpha = 1 - this.progress;
+        if (this.elapsed >= this.duration) {
+            this.expired = true;
+            return true;
+        }
+        return false;
+    }
+    destroy() {
+        this.removeChild(this.body);
+        this.body.destroy();
+        super.destroy();
+    }
+    redraw() {
+        const dx = this.to.x - this.from.x;
+        const dy = this.to.y - this.from.y;
+        const length = Math.hypot(dx, dy);
+        this.position.set(this.from.x, this.from.y);
+        this.rotation = length > 0 ? Math.atan2(dy, dx) : 0;
+        if (this.body instanceof TilingSprite) {
+            this.body.width = length;
+            this.body.height = this.thickness;
+        }
+        else {
+            const line = this.body;
+            line.clear();
+            line.moveTo(0, 0);
+            line.lineTo(length, 0);
+            line.stroke({ width: this.thickness, color: this.colour });
+        }
+    }
+}
+/**
+ * Owns the beams a game has flashing: one `add` per ray, one `update(dt)` fading
+ * them all and forgetting the finished ones, and no bookkeeping left to the caller.
+ * Beams are parented here and destroyed with their beam; z-order stays the caller's.
+ *
+ * @example
+ * ```ts
+ * import { Beams } from '@datamoc/mw_games/two-d/render';
+ * import type { Container2D } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const layer: Container2D;
+ *
+ * const beams = new Beams();
+ * layer.addChild(beams);
+ *
+ * beams.add({ x: 0, y: 0 }, { x: 100, y: 0 }, { colour: 0x88ccff });
+ * beams.update(1 / 60);
+ * console.log(beams.count); // 1 - still fading
+ * beams.clear();
+ * ```
+ */
+export class Beams extends Container {
+    constructor() {
+        super(...arguments);
+        this.live = [];
+    }
+    /** flashes a beam between two points; it fades on `update` and removes itself at duration end */
+    add(from, to, options) {
+        const beam = new Beam(from, to, options);
+        this.addChild(beam);
+        this.live.push(beam);
+        return beam;
+    }
+    /** fades every live beam, then forgets and destroys the finished ones */
+    update(dt) {
+        for (let i = this.live.length - 1; i >= 0; i--) {
+            if (this.live[i].update(dt)) {
+                const [beam] = this.live.splice(i, 1);
+                this.removeChild(beam);
+                beam.destroy();
+            }
+        }
+    }
+    /** how many beams are still fading */
+    get count() {
+        return this.live.length;
+    }
+    /** drops every live beam at once - a scene change, say */
+    clear() {
+        for (const beam of this.live.splice(0)) {
+            this.removeChild(beam);
+            beam.destroy();
+        }
+    }
+    destroy() {
+        this.clear();
+        super.destroy();
+    }
+}
+//# sourceMappingURL=Beam.js.map

package/dist/two-d/render/Beam.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Beam.js","sourceRoot":"","sources":["../../../src/two-d/render/Beam.ts"],"names":[],"mappings":"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"}

package/dist/two-d/render/Flights.d.ts

@@ -0,0 +1,79 @@
+import { Container } from 'pixi.js';
+import { Projectile, type ProjectileOptions, type ProjectilePoint } from './Projectile.ts';
+import type { Texture2D } from './Types2D.ts';
+/** what a flight moves: position required, presentation optional and applied only when present */
+export interface FlightSprite {
+    x: number;
+    y: number;
+    rotation?: number;
+    alpha?: number;
+    tint?: number;
+}
+export interface FlightOptions extends ProjectileOptions {
+    /** set once at launch, when the sprite takes a tint */
+    tint?: number;
+    /** radians per second added to the sprite's rotation while flying */
+    spin?: number;
+    /** seconds the sprite fades 0 to 1 from launch; 0 or omitted means no fade */
+    fadeIn?: number;
+    /**
+     * Dispatched once, when this flight arrives - never on `cancel()` or `clear()`,
+     * and after the flight has left the list, so an arrival that launches another
+     * flight cannot disturb the iteration it arrived in.
+     */
+    onArrive?: () => void;
+}
+export interface FlightHandle {
+    /** the flight's own tween: `progress`, `frame`, `done` */
+    readonly projectile: Projectile;
+    /** whether the flight has arrived */
+    readonly done: boolean;
+    /** forgets the flight without dispatching `onArrive`; a manager-built sprite is destroyed */
+    cancel(): void;
+}
+/**
+ * Owns the projectile flights a game has in the air: one `add` per shot, one
+ * `update(dt)` driving them all, `onArrive` dispatched exactly once per arrival,
+ * and no bookkeeping left to the caller.
+ *
+ * Ownership follows who made the sprite. A sprite you pass stays yours - the
+ * manager positions it but never parents or destroys it, so layering and scene
+ * teardown stay the caller's. A texture builds a manager sprite instead: parented
+ * here and destroyed on arrival, cancel or clear. Destroying the `Flights` node
+ * itself clears first, so manager-built sprites never outlive it.
+ *
+ * @example
+ * ```ts
+ * import { Flights } from '@datamoc/mw_games/two-d/render';
+ * import type { Container2D } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const layer: Container2D;
+ * declare const bolt: { x: number; y: number };
+ *
+ * const flights = new Flights();
+ * layer.addChild(flights);
+ *
+ * const flight = flights.add(bolt, { x: 0, y: 0 }, { x: 200, y: 0 }, {
+ * 	speed: 400,
+ * 	onArrive: () => console.log('hit'),
+ * });
+ * flights.update(1 / 60);
+ * console.log(flights.count, flight.done); // 1 false - still flying
+ * flight.cancel();
+ * flights.clear();
+ * ```
+ */
+export declare class Flights extends Container {
+    private readonly live;
+    add(sprite: FlightSprite, from: ProjectilePoint, to: ProjectilePoint, options?: FlightOptions): FlightHandle;
+    add(texture: Texture2D, from: ProjectilePoint, to: ProjectilePoint, options?: FlightOptions): FlightHandle;
+    /** drives every live flight, then forgets the arrived ones (arrival first, callback after) */
+    update(dt: number): void;
+    /** how many flights are still in the air */
+    get count(): number;
+    /** drops every live flight at once without dispatching arrivals - a scene change, say */
+    clear(): void;
+    destroy(): void;
+    private release;
+}
+//# sourceMappingURL=Flights.d.ts.map

package/dist/two-d/render/Flights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Flights.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/Flights.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAmB,MAAM,SAAS,CAAC;AAErD,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC3F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACvD,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,6FAA6F;IAC7F,MAAM,IAAI,IAAI,CAAC;CACf;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,OAAQ,SAAQ,SAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IAEzC,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;IAC7G,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;IAgD3G,8FAA8F;IAC9F,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAgBvB;IAED,4CAA4C;IAC5C,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,yFAAyF;IACzF,KAAK,IAAI,IAAI,CAEZ;IAEQ,OAAO,IAAI,IAAI,CAGvB;IAED,OAAO,CAAC,OAAO;CAKf"}

package/dist/two-d/render/Flights.js

@@ -0,0 +1,120 @@
+import { Container, Sprite, Texture } from 'pixi.js';
+import { Projectile } from './Projectile.js';
+/**
+ * Owns the projectile flights a game has in the air: one `add` per shot, one
+ * `update(dt)` driving them all, `onArrive` dispatched exactly once per arrival,
+ * and no bookkeeping left to the caller.
+ *
+ * Ownership follows who made the sprite. A sprite you pass stays yours - the
+ * manager positions it but never parents or destroys it, so layering and scene
+ * teardown stay the caller's. A texture builds a manager sprite instead: parented
+ * here and destroyed on arrival, cancel or clear. Destroying the `Flights` node
+ * itself clears first, so manager-built sprites never outlive it.
+ *
+ * @example
+ * ```ts
+ * import { Flights } from '@datamoc/mw_games/two-d/render';
+ * import type { Container2D } from '@datamoc/mw_games/two-d/render';
+ *
+ * declare const layer: Container2D;
+ * declare const bolt: { x: number; y: number };
+ *
+ * const flights = new Flights();
+ * layer.addChild(flights);
+ *
+ * const flight = flights.add(bolt, { x: 0, y: 0 }, { x: 200, y: 0 }, {
+ * 	speed: 400,
+ * 	onArrive: () => console.log('hit'),
+ * });
+ * flights.update(1 / 60);
+ * console.log(flights.count, flight.done); // 1 false - still flying
+ * flight.cancel();
+ * flights.clear();
+ * ```
+ */
+export class Flights extends Container {
+    constructor() {
+        super(...arguments);
+        this.live = [];
+    }
+    add(art, from, to, options = {}) {
+        let sprite;
+        let built;
+        if (art instanceof Texture) {
+            built = new Sprite(art);
+            this.addChild(built);
+            sprite = built;
+        }
+        else {
+            sprite = art;
+        }
+        if (options.tint !== undefined && typeof sprite.tint === 'number')
+            sprite.tint = options.tint;
+        const fadeIn = options.fadeIn ?? 0;
+        const baseAlpha = typeof sprite.alpha === 'number' ? sprite.alpha : 1;
+        if (fadeIn > 0)
+            sprite.alpha = 0;
+        const flight = {
+            projectile: new Projectile(sprite, from, to, options),
+            sprite,
+            built,
+            onArrive: options.onArrive,
+            spin: options.spin,
+            fadeIn,
+            baseAlpha,
+            elapsed: 0,
+        };
+        this.live.push(flight);
+        return {
+            projectile: flight.projectile,
+            get done() {
+                return flight.projectile.done;
+            },
+            cancel: () => {
+                const index = this.live.indexOf(flight);
+                if (index === -1)
+                    return;
+                this.live.splice(index, 1);
+                this.release(flight);
+            },
+        };
+    }
+    /** drives every live flight, then forgets the arrived ones (arrival first, callback after) */
+    update(dt) {
+        for (let i = this.live.length - 1; i >= 0; i--) {
+            const flight = this.live[i];
+            flight.elapsed += dt;
+            if (flight.spin !== undefined) {
+                flight.sprite.rotation = (flight.sprite.rotation ?? 0) + flight.spin * dt;
+            }
+            if (flight.fadeIn > 0) {
+                flight.sprite.alpha = flight.baseAlpha * Math.min(1, flight.elapsed / flight.fadeIn);
+            }
+            if (flight.projectile.update(dt)) {
+                this.live.splice(i, 1);
+                this.release(flight);
+                flight.onArrive?.();
+            }
+        }
+    }
+    /** how many flights are still in the air */
+    get count() {
+        return this.live.length;
+    }
+    /** drops every live flight at once without dispatching arrivals - a scene change, say */
+    clear() {
+        for (const flight of this.live.splice(0))
+            this.release(flight);
+    }
+    destroy() {
+        this.clear();
+        super.destroy();
+    }
+    release(flight) {
+        if (!flight.built)
+            return;
+        this.removeChild(flight.built);
+        flight.built.destroy();
+    }
+}
+//# sourceMappingURL=Flights.js.map

package/dist/two-d/render/Flights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Flights.js","sourceRoot":"","sources":["../../../src/two-d/render/Flights.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAErD,OAAO,EAAE,UAAU,EAAgD,MAAM,iBAAiB,CAAC;AA+C3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,OAAQ,SAAQ,SAAS;IAAtC;;QACkB,SAAI,GAAiB,EAAE,CAAC;IA0F1C,CAAC;IAtFA,GAAG,CACF,GAA6B,EAC7B,IAAqB,EACrB,EAAmB,EACnB,OAAO,GAAkB,EAAE;QAE3B,IAAI,MAAoB,CAAC;QACzB,IAAI,KAAyB,CAAC;QAC9B,IAAI,GAAG,YAAY,OAAO,EAAE,CAAC;YAC5B,KAAK,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACrB,MAAM,GAAG,KAAK,CAAC;QAChB,CAAC;aAAM,CAAC;YACP,MAAM,GAAG,GAAG,CAAC;QACd,CAAC;QAED,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC9F,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QACnC,MAAM,SAAS,GAAG,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACtE,IAAI,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;QAEjC,MAAM,MAAM,GAAe;YAC1B,UAAU,EAAE,IAAI,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC;YACrD,MAAM;YACN,KAAK;YACL,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,MAAM;YACN,SAAS;YACT,OAAO,EAAE,CAAC;SACV,CAAC;QACF,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEvB,OAAO;YACN,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,IAAI,IAAI;gBACP,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;YAC/B,CAAC;YACD,MAAM,EAAE,GAAG,EAAE;gBACZ,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBACxC,IAAI,KAAK,KAAK,CAAC,CAAC;oBAAE,OAAO;gBACzB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;gBAC3B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACtB,CAAC;SACD,CAAC;IACH,CAAC;IAED,8FAA8F;IAC9F,MAAM,CAAC,EAAU;QAChB,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAChD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5B,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;YACrB,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC/B,MAAM,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;YAC3E,CAAC;YACD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;YACtF,CAAC;YACD,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;gBAClC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACvB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBACrB,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;YACrB,CAAC;QACF,CAAC;IACF,CAAC;IAED,4CAA4C;IAC5C,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IACzB,CAAC;IAED,yFAAyF;IACzF,KAAK;QACJ,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,CAAC;IAEQ,OAAO;QACf,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,KAAK,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAEO,OAAO,CAAC,MAAkB;QACjC,IAAI,CAAC,MAAM,CAAC,KAAK;YAAE,OAAO;QAC1B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;CACD"}

package/dist/two-d/render/Particles.d.ts

@@ -104,6 +104,24 @@ export interface ParticleEmitterOptions {
      */
     tint?: ParticleRange;
 }
+/** what an attached emitter follows: a display object, or a thunk reading live position */
+export type FollowTarget = Container | (() => {
+    x: number;
+    y: number;
+});
+/** options for {@link ParticleEmitter.attach} */
+export interface FollowOptions {
+    /** added to the target position on every sync */
+    offsetX?: number;
+    offsetY?: number;
+    /**
+     * Consulted on every update tick; a false return pauses emission while the target
+     * is off-screen or paused, without consumer bookkeeping. Particles already alive
+     * still finish their lives, and an explicit `burst()` always fires - the callback
+     * gates the tick, not the call.
+     */
+    enabled?: () => boolean;
+}
 /**
  * A pooled particle emitter: sparks off a sword hit, dust under a footstep, rain over a map.
  *
@@ -160,6 +178,10 @@ export declare class ParticleEmitter extends Container {
     /** where in local space births happen, or null for a single point at the origin */
     private readonly spawnArea;
     private emitting;
+    private followTarget;
+    private followOffsetX;
+    private followOffsetY;
+    private followEnabled;
     /** where the next pool search starts, so reuse stays O(1) amortised rather than O(pool) */
     private poolCursor;
     /** fractional particles owed from previous frames, so a low rate still emits accurately */
@@ -169,6 +191,32 @@ export declare class ParticleEmitter extends Container {
     start(): void;
     /** stops emitting; particles already alive still finish their lives */
     stop(): void;
+    /**
+     * Follows `target`, repositioning on every update tick and every `burst()`, plus
+     * once right now so the position is fresh before the first tick. A second `attach`
+     * replaces the first; `detach()` stops following and keeps the last position. A
+     * destroyed `Container` target cannot move again, so it auto-detaches (thunk
+     * targets are read unconditionally - their liveness is the caller's).
+     *
+     * @example
+     * ```ts
+     * import { ParticleEmitter } from '@datamoc/mw_games/two-d/render';
+     *
+     * const aura = new ParticleEmitter({ rate: 20 });
+     * const hero = { x: 100, y: 200 };
+     * aura.attach(() => hero, { offsetY: -10 });
+     * aura.start();
+     * aura.update(1 / 60);
+     * aura.detach();
+     * ```
+     */
+    attach(target: FollowTarget, options?: FollowOptions): void;
+    /** stops following; the emitter keeps its last position and its emitting state */
+    detach(): void;
+    /** the current follow target, or null when detached */
+    get attachedTo(): FollowTarget | null;
+    private syncFollow;
+    private followEmissionAllowed;
     get isEmitting(): boolean;
     /** how many particles are alive right now */
     get activeCount(): number;

package/dist/two-d/render/Particles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Particles.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/Particles.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Particles.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/Particles.ts"],"names":[],"mappings":"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"}