@datamoc/mw_games 0.7.6 → 0.7.8

package/dist/audio/Positional.js

@@ -0,0 +1,135 @@
+/**
+ * The gain a listener at `distance` hears a source at, clamped to [0, 1]: 1 at or inside
+ * `refDistance`, 0 at or beyond `maxDistance`, an inverse-distance curve between them.
+ *
+ * @example
+ * ```ts
+ * import { audioGain } from '@datamoc/mw_games/audio';
+ *
+ * audioGain(0, { refDistance: 2 }); // 1 - inside the full-volume radius
+ * audioGain(2, { refDistance: 2 }); // 1 - the reference distance itself
+ * audioGain(4, { refDistance: 2 }); // 0.5 - one doubling away
+ * audioGain(4, { refDistance: 2, maxDistance: 4 }); // 0 - at the edge of hearing
+ * ```
+ */
+export function audioGain(distance, falloff = {}) {
+    const refDistance = falloff.refDistance ?? 1;
+    const maxDistance = falloff.maxDistance ?? Infinity;
+    const rolloff = falloff.rolloff ?? 1;
+    if (!(distance > refDistance))
+        return 1;
+    if (!(distance < maxDistance))
+        return 0;
+    const gain = Math.pow(refDistance / distance, rolloff);
+    return Math.max(0, Math.min(1, gain));
+}
+/**
+ * Stereo pan in [-1, 1] for a source: -1 is hard left of the listener, 1 hard right, 0
+ * directly ahead or behind. The listener's `facing` is its heading in radians (0 faces +x,
+ * increasing clockwise on a screen where y grows downward), so turning the listener turns
+ * what counts as "right" with it - a sound to the world's east is centred when the listener
+ * faces east and hard right when the listener faces north.
+ *
+ * A game with a stereo backend applies this itself; the framework has no panner node of its
+ * own, so it reports the number rather than pretending to pan.
+ *
+ * @example
+ * ```ts
+ * import { audioPan } from '@datamoc/mw_games/audio';
+ *
+ * const listener = { x: 0, y: 0, facing: 0 }; // facing east
+ * audioPan(listener, { x: 10, y: 0 }); // 0 - straight ahead
+ * audioPan(listener, { x: 0, y: 10 }); // 1 - to the listener's right
+ * audioPan(listener, { x: 0, y: -10 }); // -1 - to its left
+ * ```
+ */
+export function audioPan(listener, source) {
+    const dx = source.x - listener.x;
+    const dy = source.y - listener.y;
+    const distance = Math.hypot(dx, dy);
+    if (distance === 0)
+        return 0;
+    //the listener's right-hand direction at heading `facing`, in screen coordinates
+    const rightX = Math.sin(listener.facing);
+    const rightY = Math.cos(listener.facing);
+    const pan = (dx * rightX + dy * rightY) / distance;
+    return Math.max(-1, Math.min(1, pan));
+}
+/**
+ * Where sounds are heard from: a game moves one listener to its camera or its party leader
+ * each frame, and every `SoundSource` is mixed against it.
+ *
+ * @example
+ * ```ts
+ * import { AudioListener } from '@datamoc/mw_games/audio';
+ *
+ * const listener = new AudioListener({ x: 40, y: 12 });
+ * listener.moveTo(41, 12); // following the camera
+ * listener.face(Math.PI / 2); // now facing the world's south
+ * ```
+ */
+export class AudioListener {
+    constructor(options = {}) {
+        this.x = options.x ?? 0;
+        this.y = options.y ?? 0;
+        this.facing = options.facing ?? 0;
+    }
+    moveTo(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+    face(radians) {
+        this.facing = radians;
+    }
+}
+/**
+ * One positional one-shot: a `Sound` attached to a point in the world, heard from a
+ * listener with the distance gain `audioGain` computes. `playFor` applies that gain through
+ * `Sound.play(gain)`, and stays silent past `maxDistance` rather than playing at volume 0.
+ *
+ * Long-running position (a waterfall, an engine) is the game's own loop calling `playFor` on
+ * a cadence it chooses; this is the placement and the mix, not a scheduler.
+ *
+ * @example
+ * ```ts
+ * import { AudioListener, Sound, SoundSource } from '@datamoc/mw_games/audio';
+ *
+ * const listener = new AudioListener({ x: 0, y: 0 });
+ * const arrow = new Sound('sounds/arrow.mp3');
+ * const source = new SoundSource(arrow, { x: 6, y: 8, refDistance: 4, maxDistance: 20 });
+ *
+ * const gain = source.gainTo(listener); // 0.4 at distance 10
+ * source.playFor(listener); // plays at that gain, or not at all when silent
+ * ```
+ */
+export class SoundSource {
+    constructor(sound, options = {}) {
+        this.sound = sound;
+        this.x = options.x ?? 0;
+        this.y = options.y ?? 0;
+        this.falloff = {
+            refDistance: options.refDistance,
+            maxDistance: options.maxDistance,
+            rolloff: options.rolloff,
+        };
+    }
+    moveTo(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+    gainTo(listener) {
+        return audioGain(Math.hypot(this.x - listener.x, this.y - listener.y), this.falloff);
+    }
+    panTo(listener) {
+        return audioPan(listener, this);
+    }
+    /** Plays the source at the gain the listener hears it; returns the gain actually used. */
+    playFor(listener) {
+        const gain = this.gainTo(listener);
+        if (gain <= 0)
+            return 0;
+        this.sound.play(gain);
+        return gain;
+    }
+}
+//# sourceMappingURL=Positional.js.map

package/dist/audio/Positional.js.map

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

package/dist/audio/Sound.d.ts

@@ -28,7 +28,13 @@ export declare class Sound {
     private caption?;
     volume: number;
     constructor(path: string, options?: SoundOptions);
-    play(): void;
+    /**
+     * Plays one instance from the pool.
+     *
+     * @param gain multiplied into the sound's own volume, for a distance-attenuated one-shot
+     * (`Positional.SoundSource.playFor`); 1 leaves it at `volume`.
+     */
+    play(gain?: number): void;
     stopAll(): void;
 }
 //# sourceMappingURL=Sound.d.ts.map

package/dist/audio/Sound.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sound.d.ts","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAEpC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,EAMnD;IAED,IAAI,IAAI,IAAI,CAYX;IAED,OAAO,IAAI,IAAI,CAKd;CACD"}
+{"version":3,"file":"Sound.d.ts","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAEpC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,EAMnD;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAI,SAAI,GAAG,IAAI,CAYnB;IAED,OAAO,IAAI,IAAI,CAKd;CACD"}

package/dist/audio/Sound.js

@@ -23,10 +23,16 @@ export class Sound {
         this.caption = options.caption;
         this.pool = Array.from({ length: size }, () => create(path));
     }
-    play() {
+    /**
+     * Plays one instance from the pool.
+     *
+     * @param gain multiplied into the sound's own volume, for a distance-attenuated one-shot
+     * (`Positional.SoundSource.playFor`); 1 leaves it at `volume`.
+     */
+    play(gain = 1) {
         const audio = this.pool[this.next];
         this.next = (this.next + 1) % this.pool.length;
-        audio.volume = this.volume;
+        audio.volume = this.volume * gain;
         audio.currentTime = 0;
         // play() can return a Promise that rejects if this reuse interrupts its own prior,
         // still-loading play() (a real browser, not the fakes tests supply) - swallow it the

package/dist/audio/Sound.js.map

@@ -1 +1 @@
-{"version":3,"file":"Sound.js","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAc1C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,KAAK;IAMjB,YAAY,IAAY,EAAE,OAAO,GAAiB,EAAE;QAJ5C,SAAI,GAAG,CAAC,CAAC;QAKhB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,WAAW,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAE/C,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACtB,mFAAmF;QACnF,qFAAqF;QACrF,wFAAwF;QACxF,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAEnD,IAAI,IAAI,CAAC,OAAO;YAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO;QACN,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/B,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;CACD"}
+{"version":3,"file":"Sound.js","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAc1C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,KAAK;IAMjB,YAAY,IAAY,EAAE,OAAO,GAAiB,EAAE;QAJ5C,SAAI,GAAG,CAAC,CAAC;QAKhB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,WAAW,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAI,GAAG,CAAC;QACZ,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAE/C,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QAClC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACtB,mFAAmF;QACnF,qFAAqF;QACrF,wFAAwF;QACxF,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAEnD,IAAI,IAAI,CAAC,OAAO;YAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO;QACN,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/B,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;CACD"}

package/dist/audio/index.d.ts

@@ -12,4 +12,6 @@ export { synthesizeTone, playTone } from './Synth.ts';
 export type { Waveform, ToneOptions } from './Synth.ts';
 export { parseMidi, scheduleMidi, noteToFrequency, MidiPlayer } from './Midi.ts';
 export type { MidiFile, MidiEvent, MidiNoteEvent, MidiTempoEvent, ScheduledNote, MidiPlayerOptions } from './Midi.ts';
+export { AudioListener, SoundSource, audioGain, audioPan } from './Positional.ts';
+export type { AudioPoint, AudioFalloff, SoundSourceOptions } from './Positional.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/audio/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audio/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACjF,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audio/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACjF,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACtH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAClF,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/audio/index.js

@@ -5,4 +5,5 @@ export { createAudio } from './Playable.js';
 export { Orchestrator } from './Orchestrator.js';
 export { synthesizeTone, playTone } from './Synth.js';
 export { parseMidi, scheduleMidi, noteToFrequency, MidiPlayer } from './Midi.js';
+export { AudioListener, SoundSource, audioGain, audioPan } from './Positional.js';
 //# sourceMappingURL=index.js.map

package/dist/audio/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audio/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audio/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEjF,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/battle/AttackDialog.d.ts

@@ -0,0 +1,75 @@
+import { Signal } from '../core/Signal.ts';
+import { AttackPreview, type AttackFrame } from './AttackPreview.ts';
+import { UnitSelector, type SelectableUnit, type SelectorStage } from './UnitSelector.ts';
+/** The per-strike numbers a game's own rules produce for one attacker/target pair. */
+export interface StrikeNumbers {
+    damage: number;
+    strikes: number;
+    chanceToHit?: number;
+    hits?: readonly boolean[];
+}
+export interface AttackDialogOptions {
+    units: readonly SelectableUnit[];
+    side?: string;
+    disabled?: (unit: SelectableUnit) => boolean;
+    canTarget?: (attacker: SelectableUnit, target: SelectableUnit) => boolean;
+    /** the game's damage rules, called once the attacker and target are both chosen */
+    damageFor: (attacker: SelectableUnit, target: SelectableUnit) => StrikeNumbers;
+    /** seconds between strikes in the preview animation */
+    strikeDuration?: number;
+}
+/**
+ * The attack dialog's whole state, with no renderer: the unit selector, the damage preview the
+ * game's numbers build, and the animation clock the preview is sampled on.
+ *
+ * The order of business is the one a player sees - choose an attacker, choose a target, and the
+ * dialog shows a blow that lands over time - so the clock is here rather than in a widget: `update`
+ * takes the frame's `dt` and returns the preview frame to draw, and `finished` says when the
+ * animation has run out and the caller may apply the result. `damageFor` is where the game's own
+ * rules live; this model never invents damage.
+ *
+ * @example
+ * ```ts
+ * import { AttackDialog } from '@datamoc/mw_games/battle';
+ *
+ * const dialog = new AttackDialog({
+ *   units: [{ id: 'hero', side: '1' }, { id: 'rat', side: '2' }],
+ *   side: '1',
+ *   damageFor: () => ({ damage: 4, strikes: 2 }),
+ *   strikeDuration: 0.25,
+ * });
+ * dialog.select();
+ * dialog.select();
+ * console.log(dialog.update(0.3)?.defenderHp); // the defender after the second strike
+ * ```
+ */
+export declare class AttackDialog {
+    readonly onChange: Signal<void>;
+    readonly selector: UnitSelector;
+    private readonly damageFor;
+    private readonly strikeDuration;
+    private built;
+    private elapsed_;
+    constructor(options: AttackDialogOptions);
+    get stage(): SelectorStage;
+    get attacker(): SelectableUnit | null;
+    get target(): SelectableUnit | null;
+    /** the damage preview, built once both choices are made */
+    get preview(): AttackPreview | null;
+    /** how long the animation has been playing, in seconds */
+    get elapsed(): number;
+    /** whether the animation has reached the end of the preview */
+    get finished(): boolean;
+    /** the frame to draw right now, or `null` before both choices are made */
+    get frame(): AttackFrame | null;
+    move(delta: number): void;
+    select(): boolean;
+    back(): void;
+    /** advances the animation, returning the frame to draw */
+    update(dt: number): AttackFrame | null;
+    /** skips the animation to its end, the click-through a player makes */
+    finish(): void;
+    reset(): void;
+    private readonly handleSelectorChange;
+}
+//# sourceMappingURL=AttackDialog.d.ts.map

package/dist/battle/AttackDialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttackDialog.d.ts","sourceRoot":"","sources":["../../src/battle/AttackDialog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE1F,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;IAC7C,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC;IAC1E,mFAAmF;IACnF,SAAS,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,cAAc,KAAK,aAAa,CAAC;IAC/E,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,YAAY;IACxB,QAAQ,CAAC,QAAQ,eAAsB;IACvC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAEhC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsE;IAChG,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,QAAQ,CAAK;IAErB,YAAY,OAAO,EAAE,mBAAmB,EAUvC;IAED,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED,IAAI,QAAQ,IAAI,cAAc,GAAG,IAAI,CAEpC;IAED,IAAI,MAAM,IAAI,cAAc,GAAG,IAAI,CAElC;IAED,2DAA2D;IAC3D,IAAI,OAAO,IAAI,aAAa,GAAG,IAAI,CAElC;IAED,0DAA0D;IAC1D,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,+DAA+D;IAC/D,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,0EAA0E;IAC1E,IAAI,KAAK,IAAI,WAAW,GAAG,IAAI,CAE9B;IAED,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAExB;IAED,MAAM,IAAI,OAAO,CAEhB;IAED,IAAI,IAAI,IAAI,CAEX;IAED,0DAA0D;IAC1D,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAIrC;IAED,uEAAuE;IACvE,MAAM,IAAI,IAAI,CAEb;IAED,KAAK,IAAI,IAAI,CAIZ;IAED,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAiBnC;CACF"}

package/dist/battle/AttackDialog.js

@@ -0,0 +1,115 @@
+import { Signal } from '../core/Signal.js';
+import { AttackPreview } from './AttackPreview.js';
+import { UnitSelector } from './UnitSelector.js';
+/**
+ * The attack dialog's whole state, with no renderer: the unit selector, the damage preview the
+ * game's numbers build, and the animation clock the preview is sampled on.
+ *
+ * The order of business is the one a player sees - choose an attacker, choose a target, and the
+ * dialog shows a blow that lands over time - so the clock is here rather than in a widget: `update`
+ * takes the frame's `dt` and returns the preview frame to draw, and `finished` says when the
+ * animation has run out and the caller may apply the result. `damageFor` is where the game's own
+ * rules live; this model never invents damage.
+ *
+ * @example
+ * ```ts
+ * import { AttackDialog } from '@datamoc/mw_games/battle';
+ *
+ * const dialog = new AttackDialog({
+ *   units: [{ id: 'hero', side: '1' }, { id: 'rat', side: '2' }],
+ *   side: '1',
+ *   damageFor: () => ({ damage: 4, strikes: 2 }),
+ *   strikeDuration: 0.25,
+ * });
+ * dialog.select();
+ * dialog.select();
+ * console.log(dialog.update(0.3)?.defenderHp); // the defender after the second strike
+ * ```
+ */
+export class AttackDialog {
+    constructor(options) {
+        this.onChange = new Signal();
+        this.built = null;
+        this.elapsed_ = 0;
+        this.handleSelectorChange = () => {
+            if (this.selector.done && this.attacker && this.target) {
+                const numbers = this.damageFor(this.attacker, this.target);
+                this.built = new AttackPreview({
+                    attacker: { hp: this.attacker.hp ?? 0, name: this.attacker.id },
+                    defender: { hp: this.target.hp ?? 0, name: this.target.id },
+                    damage: numbers.damage,
+                    strikes: numbers.strikes,
+                    ...(numbers.chanceToHit === undefined ? {} : { chanceToHit: numbers.chanceToHit }),
+                    ...(numbers.hits === undefined ? {} : { hits: numbers.hits }),
+                    strikeDuration: this.strikeDuration,
+                });
+                this.elapsed_ = 0;
+            }
+            else {
+                this.built = null;
+            }
+            this.onChange.dispatch();
+        };
+        this.damageFor = options.damageFor;
+        this.strikeDuration = options.strikeDuration ?? 0;
+        this.selector = new UnitSelector({
+            units: options.units,
+            ...(options.side === undefined ? {} : { side: options.side }),
+            ...(options.disabled === undefined ? {} : { disabled: options.disabled }),
+            ...(options.canTarget === undefined ? {} : { canTarget: options.canTarget }),
+        });
+        this.selector.onChange.add(this.handleSelectorChange);
+    }
+    get stage() {
+        return this.selector.stage;
+    }
+    get attacker() {
+        return this.selector.attacker;
+    }
+    get target() {
+        return this.selector.target;
+    }
+    /** the damage preview, built once both choices are made */
+    get preview() {
+        return this.built;
+    }
+    /** how long the animation has been playing, in seconds */
+    get elapsed() {
+        return this.elapsed_;
+    }
+    /** whether the animation has reached the end of the preview */
+    get finished() {
+        return this.built !== null && this.elapsed_ >= this.built.duration;
+    }
+    /** the frame to draw right now, or `null` before both choices are made */
+    get frame() {
+        return this.built ? this.built.sampleAt(this.elapsed_) : null;
+    }
+    move(delta) {
+        this.selector.move(delta);
+    }
+    select() {
+        return this.selector.select();
+    }
+    back() {
+        this.selector.back();
+    }
+    /** advances the animation, returning the frame to draw */
+    update(dt) {
+        if (!this.built)
+            return null;
+        this.elapsed_ = Math.min(this.built.duration, this.elapsed_ + Math.max(0, dt));
+        return this.frame;
+    }
+    /** skips the animation to its end, the click-through a player makes */
+    finish() {
+        if (this.built)
+            this.elapsed_ = this.built.duration;
+    }
+    reset() {
+        this.selector.reset();
+        this.built = null;
+        this.elapsed_ = 0;
+    }
+}
+//# sourceMappingURL=AttackDialog.js.map

package/dist/battle/AttackDialog.js.map

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

package/dist/battle/AttackPreview.d.ts

@@ -0,0 +1,70 @@
+export interface PreviewCombatant {
+    hp: number;
+    maxHp?: number;
+    name?: string;
+}
+export interface AttackPreviewOptions {
+    attacker: PreviewCombatant;
+    defender: PreviewCombatant;
+    /** damage per strike, from the game's own formula - `mwg` supplies none */
+    damage: number;
+    strikes: number;
+    /** chance to hit, 0 to 1; 1 (always hits) when omitted */
+    chanceToHit?: number;
+    /** which strikes land; every strike when omitted, for the maximum-damage preview */
+    hits?: readonly boolean[];
+    /** seconds between strikes in the animation; 0 when there is no animation */
+    strikeDuration?: number;
+}
+/** One moment of the attack animation: the board after `strike` strikes. */
+export interface AttackFrame {
+    strike: number;
+    time: number;
+    attackerHp: number;
+    defenderHp: number;
+    /** hp taken off the defender by the strikes so far */
+    defenderDamage: number;
+}
+/**
+ * The numbers an attack dialog shows and animates: the attacker and defender's hp over the course
+ * of a blow, plus the totals the labels print.
+ *
+ * It deliberately computes no damage of its own - this framework supplies no damage formula, so a
+ * game hands in the per-strike `damage` exactly as its own rules worked it out. What the preview
+ * adds is the part a dialog needs and a formula does not: the *timeline* (one frame per strike,
+ * `sampleAt` the animation's own clock) and the two totals (the maximum, `damage * strikes`, and
+ * the expected value once `chanceToHit` is weighed). Which strikes actually land is `hits`, so a
+ * preview can show the maximum by default or a known outcome a replay already rolled.
+ *
+ * @example
+ * ```ts
+ * import { AttackPreview } from '@datamoc/mw_games/battle';
+ *
+ * const preview = new AttackPreview({
+ *   attacker: { hp: 20 },
+ *   defender: { hp: 12 },
+ *   damage: 4,
+ *   strikes: 3,
+ *   chanceToHit: 0.6,
+ *   strikeDuration: 0.2,
+ * });
+ * console.log(preview.totalDamage); // 12
+ * console.log(preview.sampleAt(0.25).defenderHp); // 8, after the second strike
+ * ```
+ */
+export declare class AttackPreview {
+    readonly frames: readonly AttackFrame[];
+    readonly totalDamage: number;
+    readonly expectedDamage: number;
+    readonly chanceToHit: number;
+    private readonly strikeDuration;
+    private readonly defenderHp0;
+    constructor(options: AttackPreviewOptions);
+    /** how long the animation runs, in seconds */
+    get duration(): number;
+    /** whether the defender would be at 0 hp once every landing strike has been shown */
+    get defenderKilled(): boolean;
+    /** the frame the animation shows at `time`, clamped to its own start and end */
+    sampleAt(time: number): AttackFrame;
+}
+//# sourceMappingURL=AttackPreview.d.ts.map

package/dist/battle/AttackPreview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttackPreview.d.ts","sourceRoot":"","sources":["../../src/battle/AttackPreview.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,aAAa;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,YAAY,OAAO,EAAE,oBAAoB,EAoBxC;IAED,8CAA8C;IAC9C,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,qFAAqF;IACrF,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAWlC;CACD"}

package/dist/battle/AttackPreview.js

@@ -0,0 +1,78 @@
+/**
+ * The numbers an attack dialog shows and animates: the attacker and defender's hp over the course
+ * of a blow, plus the totals the labels print.
+ *
+ * It deliberately computes no damage of its own - this framework supplies no damage formula, so a
+ * game hands in the per-strike `damage` exactly as its own rules worked it out. What the preview
+ * adds is the part a dialog needs and a formula does not: the *timeline* (one frame per strike,
+ * `sampleAt` the animation's own clock) and the two totals (the maximum, `damage * strikes`, and
+ * the expected value once `chanceToHit` is weighed). Which strikes actually land is `hits`, so a
+ * preview can show the maximum by default or a known outcome a replay already rolled.
+ *
+ * @example
+ * ```ts
+ * import { AttackPreview } from '@datamoc/mw_games/battle';
+ *
+ * const preview = new AttackPreview({
+ *   attacker: { hp: 20 },
+ *   defender: { hp: 12 },
+ *   damage: 4,
+ *   strikes: 3,
+ *   chanceToHit: 0.6,
+ *   strikeDuration: 0.2,
+ * });
+ * console.log(preview.totalDamage); // 12
+ * console.log(preview.sampleAt(0.25).defenderHp); // 8, after the second strike
+ * ```
+ */
+export class AttackPreview {
+    constructor(options) {
+        this.chanceToHit = clamp01(options.chanceToHit ?? 1);
+        this.strikeDuration = Math.max(0, options.strikeDuration ?? 0);
+        this.totalDamage = Math.max(0, options.damage) * Math.max(0, options.strikes);
+        this.expectedDamage = this.totalDamage * this.chanceToHit;
+        this.defenderHp0 = options.defender.hp;
+        const frames = [];
+        let defenderHp = options.defender.hp;
+        for (let strike = 0; strike <= options.strikes; strike++) {
+            if (strike > 0 && (options.hits?.[strike - 1] ?? true))
+                defenderHp -= Math.max(0, options.damage);
+            frames.push({
+                strike,
+                time: strike * this.strikeDuration,
+                attackerHp: options.attacker.hp,
+                defenderHp: Math.max(0, defenderHp),
+                defenderDamage: this.defenderHp0 - Math.max(0, defenderHp),
+            });
+        }
+        this.frames = frames;
+    }
+    /** how long the animation runs, in seconds */
+    get duration() {
+        return this.strikeDuration * (this.frames.length - 1);
+    }
+    /** whether the defender would be at 0 hp once every landing strike has been shown */
+    get defenderKilled() {
+        return this.frames[this.frames.length - 1].defenderHp === 0;
+    }
+    /** the frame the animation shows at `time`, clamped to its own start and end */
+    sampleAt(time) {
+        const last = this.frames.length - 1;
+        if (this.strikeDuration <= 0)
+            return this.frames[last];
+        //compare frame times rather than dividing, so a float strike duration does not land on the
+        //frame before the one its time names (0.4 / 0.2 can read just under 2)
+        let index = 0;
+        for (let frame = 0; frame <= last; frame++) {
+            if (this.frames[frame].time <= time + 1e-9)
+                index = frame;
+            else
+                break;
+        }
+        return this.frames[index];
+    }
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+//# sourceMappingURL=AttackPreview.js.map

package/dist/battle/AttackPreview.js.map

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

package/dist/battle/BattleStats.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A per-run battle statistics breakdown by category and unit type - recruits, recalls,
+ * advances, kills, deaths, damage dealt, damage taken - the shape Wesnoth's own
+ * statistics dialog shows and a bare `core.PlayerStats<T>` cannot give a game for free,
+ * since `T` there is an opaque summary the game must already know how to combine. Here
+ * the categories and the per-unit-type breakdown are the primitive: a game records one
+ * event at a time as it happens and reads either a category's total or its breakdown by
+ * unit type, then folds `toJSON()` into a `core.RunHistory` entry or a `core.PlayerStats`
+ * total the way any other run summary would.
+ *
+ * @example
+ * ```ts
+ * import { BattleStats } from '@datamoc/mw_games/battle';
+ *
+ * const stats = new BattleStats();
+ * stats.record('kills', 'orc-grunt');
+ * stats.record('kills', 'orc-grunt');
+ * stats.record('damageDealt', 'elvish-archer', 12);
+ *
+ * console.log(stats.total('kills')); // 2
+ * console.log(stats.breakdown('kills')); // [{ unitType: 'orc-grunt', count: 2 }]
+ * ```
+ */
+export type BattleStatCategory = 'recruits' | 'recalls' | 'advances' | 'kills' | 'deaths' | 'damageDealt' | 'damageTaken';
+export declare class BattleStats {
+    private counts;
+    /** adds `amount` (default 1) to a category's count for one unit type */
+    record(category: BattleStatCategory, unitType: string, amount?: number): void;
+    /** one category's count for one unit type; 0 for a combination nothing has recorded yet */
+    forType(category: BattleStatCategory, unitType: string): number;
+    /** a category's total across every unit type */
+    total(category: BattleStatCategory): number;
+    /** every unit type a category has recorded, with its count - the rows a stats screen breaks a category into */
+    breakdown(category: BattleStatCategory): readonly {
+        unitType: string;
+        count: number;
+    }[];
+    toJSON(): {
+        counts: [BattleStatCategory, [string, number][]][];
+    };
+    static fromJSON(data: {
+        counts: [BattleStatCategory, [string, number][]][];
+    }): BattleStats;
+}
+//# sourceMappingURL=BattleStats.d.ts.map

package/dist/battle/BattleStats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BattleStats.d.ts","sourceRoot":"","sources":["../../src/battle/BattleStats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,kBAAkB,GAC7B,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,aAAa,GAAG,aAAa,CAAC;AAE1F,qBAAa,WAAW;IACvB,OAAO,CAAC,MAAM,CAAsD;IAEpE,wEAAwE;IACxE,MAAM,CAAC,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,IAAI,CAIvE;IAED,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;IAED,gDAAgD;IAChD,KAAK,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAM1C;IAED,+GAA+G;IAC/G,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAGtF;IAED,MAAM,IAAI;QAAE,MAAM,EAAE,CAAC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;KAAE,CAE/D;IAED,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,CAAC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;KAAE,GAAG,WAAW,CAIzF;CACD"}