@datamoc/mw_games 0.4.0 → 0.4.2

package/dist/roguelike/Scheduler.d.ts

@@ -8,11 +8,35 @@
  *
  * The queue is ordered by the time at which each actor next acts. `now` only ever moves
  * forward, so effects that expire can be timestamped against it.
+ *
+ * @example
+ * ```ts
+ * import { Scheduler, type Actor } from '@datamoc/mw_games/roguelike';
+ *
+ * interface Monster extends Actor { name: string }
+ *
+ * const scheduler = new Scheduler<Monster>();
+ * scheduler.add({ name: 'hero', speed: 1 });
+ * scheduler.add({ name: 'fast rat', speed: 2 }); // acts twice as often
+ *
+ * const acting = scheduler.peek(); // whoever's turn it is
+ * scheduler.spend(1); // charge them for a normal-speed action, hand the turn on
+ * ```
  */
 export interface Actor {
     /** actions per unit of time; 2 acts twice as often as 1 */
     speed?: number;
 }
+/** A serialisable record of a scheduler's queue, keyed by caller-supplied actor ids. */
+export interface SchedulerSnapshot {
+    now: number;
+    sequence: number;
+    entries: Array<{
+        id: string;
+        time: number;
+        sequence: number;
+    }>;
+}
 export declare class Scheduler<A extends Actor> {
     private entries;
     private sequence;
@@ -35,11 +59,34 @@ export declare class Scheduler<A extends Actor> {
     /**
      * Charges the current actor for what it did, and hands the turn on.
      *
-     * @param cost time the action took at speed 1; divided by the actor's speed
+     * @param cost time the action took at speed 1; divided by the actor's speed. A cost of 0
+     * is a free action: the actor keeps its place at `now` but still goes behind any other
+     * actor already tied with it, since its sequence number is refreshed like any other spend.
      */
     spend(cost: number): void;
+    /**
+     * Pushes a specific actor's next turn back, independent of whose turn it currently is -
+     * a stun or slow effect landing on someone other than the current actor, for instance.
+     *
+     * @param delay time added to that actor's next scheduled turn
+     */
+    postpone(actor: A, delay: number): void;
     /** the time at which an actor next acts, for a debug view or an interface */
     timeOf(actor: A): number | null;
+    /**
+     * Captures the queue as plain data, identifying each actor by whatever id the caller
+     * assigns it - the scheduler holds actor references, not ids, so it cannot invent one
+     * itself.
+     */
+    toJSON(actorId: (actor: A) => string): SchedulerSnapshot;
+    /**
+     * Rebuilds a scheduler from a snapshot taken by `toJSON`, restoring `now` and the
+     * sequence counter so that ties among actors added afterwards resolve exactly as they
+     * would have if the scheduler had never been serialised.
+     *
+     * @param actorOf resolves a snapshot id back to the live actor object it names
+     */
+    static restore<A extends Actor>(snapshot: SchedulerSnapshot, actorOf: (id: string) => A): Scheduler<A>;
     private sort;
 }
 //# sourceMappingURL=Scheduler.d.ts.map

package/dist/roguelike/Scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Scheduler.d.ts","sourceRoot":"","sources":["../../src/roguelike/Scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,KAAK;IACrB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAUD,qBAAa,SAAS,CAAC,CAAC,SAAS,KAAK;IACrC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAK;IAErB,qEAAqE;IACrE,GAAG,SAAK;IAER,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,MAAM,IAAI,CAAC,EAAE,CAEhB;IAED,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAErB;IAED;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,SAAI,GAAG,IAAI,CAG7B;IAED,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAGrB;IAED,KAAK,IAAI,IAAI,CAIZ;IAED,4EAA4E;IAC5E,IAAI,IAAI,CAAC,GAAG,IAAI,CAOf;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CASxB;IAED,6EAA6E;IAC7E,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,CAE9B;IAED,OAAO,CAAC,IAAI;CAKZ"}
+{"version":3,"file":"Scheduler.d.ts","sourceRoot":"","sources":["../../src/roguelike/Scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,KAAK;IACrB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/D;AAUD,qBAAa,SAAS,CAAC,CAAC,SAAS,KAAK;IACrC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAK;IAErB,qEAAqE;IACrE,GAAG,SAAK;IAER,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,MAAM,IAAI,CAAC,EAAE,CAEhB;IAED,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAErB;IAED;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,SAAI,GAAG,IAAI,CAG7B;IAED,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAGrB;IAED,KAAK,IAAI,IAAI,CAIZ;IAED,4EAA4E;IAC5E,IAAI,IAAI,CAAC,GAAG,IAAI,CAOf;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CASxB;IAED;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOtC;IAED,6EAA6E;IAC7E,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,CAE9B;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,iBAAiB,CAMvD;IAED;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAOrG;IAED,OAAO,CAAC,IAAI;CAKZ"}

package/dist/roguelike/Scheduler.js

@@ -8,6 +8,20 @@
  *
  * The queue is ordered by the time at which each actor next acts. `now` only ever moves
  * forward, so effects that expire can be timestamped against it.
+ *
+ * @example
+ * ```ts
+ * import { Scheduler, type Actor } from '@datamoc/mw_games/roguelike';
+ *
+ * interface Monster extends Actor { name: string }
+ *
+ * const scheduler = new Scheduler<Monster>();
+ * scheduler.add({ name: 'hero', speed: 1 });
+ * scheduler.add({ name: 'fast rat', speed: 2 }); // acts twice as often
+ *
+ * const acting = scheduler.peek(); // whoever's turn it is
+ * scheduler.spend(1); // charge them for a normal-speed action, hand the turn on
+ * ```
  */
 export class Scheduler {
     constructor() {
@@ -57,7 +71,9 @@ export class Scheduler {
     /**
      * Charges the current actor for what it did, and hands the turn on.
      *
-     * @param cost time the action took at speed 1; divided by the actor's speed
+     * @param cost time the action took at speed 1; divided by the actor's speed. A cost of 0
+     * is a free action: the actor keeps its place at `now` but still goes behind any other
+     * actor already tied with it, since its sequence number is refreshed like any other spend.
      */
     spend(cost) {
         const entry = this.entries[0];
@@ -69,10 +85,51 @@ export class Scheduler {
         entry.sequence = this.sequence++;
         this.sort();
     }
+    /**
+     * Pushes a specific actor's next turn back, independent of whose turn it currently is -
+     * a stun or slow effect landing on someone other than the current actor, for instance.
+     *
+     * @param delay time added to that actor's next scheduled turn
+     */
+    postpone(actor, delay) {
+        const entry = this.entries.find((entry) => entry.actor === actor);
+        if (!entry)
+            return;
+        entry.time += delay;
+        entry.sequence = this.sequence++;
+        this.sort();
+    }
     /** the time at which an actor next acts, for a debug view or an interface */
     timeOf(actor) {
         return this.entries.find((entry) => entry.actor === actor)?.time ?? null;
     }
+    /**
+     * Captures the queue as plain data, identifying each actor by whatever id the caller
+     * assigns it - the scheduler holds actor references, not ids, so it cannot invent one
+     * itself.
+     */
+    toJSON(actorId) {
+        return {
+            now: this.now,
+            sequence: this.sequence,
+            entries: this.entries.map((entry) => ({ id: actorId(entry.actor), time: entry.time, sequence: entry.sequence })),
+        };
+    }
+    /**
+     * Rebuilds a scheduler from a snapshot taken by `toJSON`, restoring `now` and the
+     * sequence counter so that ties among actors added afterwards resolve exactly as they
+     * would have if the scheduler had never been serialised.
+     *
+     * @param actorOf resolves a snapshot id back to the live actor object it names
+     */
+    static restore(snapshot, actorOf) {
+        const scheduler = new Scheduler();
+        scheduler.now = snapshot.now;
+        scheduler.sequence = snapshot.sequence;
+        scheduler.entries = snapshot.entries.map((entry) => ({ actor: actorOf(entry.id), time: entry.time, sequence: entry.sequence }));
+        scheduler.sort();
+        return scheduler;
+    }
     sort() {
         //few actors are ever queued, so a sort per action is cheaper than a heap and far
         //easier to reason about; swap it out if a level ever holds thousands

package/dist/roguelike/Scheduler.js.map

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

package/dist/roguelike/Secrets.d.ts

@@ -13,6 +13,19 @@ import type { Level } from './Level.ts';
  * Discovery itself is a game's call, not this class's: a search action rolling against a
  * distance, a trap firing the moment a creature steps onto it, a wand of revealing. This
  * only does the bookkeeping once that decision has been made.
+ *
+ * @example
+ * ```ts
+ * import { Secrets, Level, WALL, FLOOR } from '@datamoc/mw_games/roguelike';
+ *
+ * const level = new Level(20, 20, [WALL, FLOOR], 1);
+ * const secrets = new Secrets(level);
+ *
+ * secrets.conceal(5, 5, 0, 1); // disguised as WALL (0), reveals as FLOOR (1) once found
+ * console.log(secrets.isSecret(5, 5)); // true - the cell reads as solid rock until found
+ *
+ * secrets.discover(5, 5); // a search action succeeded
+ * ```
  */
 export declare class Secrets {
     private level;

package/dist/roguelike/Secrets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Secrets.d.ts","sourceRoot":"","sources":["../../src/roguelike/Secrets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;;;;;GAcG;AACH,qBAAa,OAAO;IACnB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,UAAU,CAAqB;IAEvC,YAAY,KAAK,EAAE,KAAK,EAEvB;IAED,yFAAyF;IACzF,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKtE;IAED,0FAA0F;IAC1F,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAGtC;IAED,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAE1C;IAED;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAOtC;IAED,MAAM,IAAI;QAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAE/D;IAED,yEAAyE;IACzE,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAKnG;CACD"}
+{"version":3,"file":"Secrets.d.ts","sourceRoot":"","sources":["../../src/roguelike/Secrets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,OAAO;IACnB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,UAAU,CAAqB;IAEvC,YAAY,KAAK,EAAE,KAAK,EAEvB;IAED,yFAAyF;IACzF,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKtE;IAED,0FAA0F;IAC1F,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAGtC;IAED,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAE1C;IAED;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAOtC;IAED,MAAM,IAAI;QAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAE/D;IAED,yEAAyE;IACzE,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAKnG;CACD"}

package/dist/roguelike/Secrets.js

@@ -12,6 +12,19 @@
  * Discovery itself is a game's call, not this class's: a search action rolling against a
  * distance, a trap firing the moment a creature steps onto it, a wand of revealing. This
  * only does the bookkeeping once that decision has been made.
+ *
+ * @example
+ * ```ts
+ * import { Secrets, Level, WALL, FLOOR } from '@datamoc/mw_games/roguelike';
+ *
+ * const level = new Level(20, 20, [WALL, FLOOR], 1);
+ * const secrets = new Secrets(level);
+ *
+ * secrets.conceal(5, 5, 0, 1); // disguised as WALL (0), reveals as FLOOR (1) once found
+ * console.log(secrets.isSecret(5, 5)); // true - the cell reads as solid rock until found
+ *
+ * secrets.discover(5, 5); // a search action succeeded
+ * ```
  */
 export class Secrets {
     constructor(level) {

package/dist/roguelike/Secrets.js.map

@@ -1 +1 @@
-{"version":3,"file":"Secrets.js","sourceRoot":"","sources":["../../src/roguelike/Secrets.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,OAAO;IAKnB,YAAY,KAAY;QAHhB,iBAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,eAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QAGtC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,yFAAyF;IACzF,OAAO,CAAC,CAAS,EAAE,CAAS,EAAE,QAAgB,EAAE,QAAgB;QAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED,0FAA0F;IAC1F,QAAQ,CAAC,CAAS,EAAE,CAAS;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClE,CAAC;IAED,YAAY,CAAC,CAAS,EAAE,CAAS;QAChC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,CAAS,EAAE,CAAS;QAC5B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAEvC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM;QACL,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;IAC/E,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,QAAQ,CAAC,KAAY,EAAE,IAA4D;QACzF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACvF,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjE,OAAO,OAAO,CAAC;IAChB,CAAC;CACD"}
+{"version":3,"file":"Secrets.js","sourceRoot":"","sources":["../../src/roguelike/Secrets.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,OAAO;IAKnB,YAAY,KAAY;QAHhB,iBAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,eAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QAGtC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,yFAAyF;IACzF,OAAO,CAAC,CAAS,EAAE,CAAS,EAAE,QAAgB,EAAE,QAAgB;QAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED,0FAA0F;IAC1F,QAAQ,CAAC,CAAS,EAAE,CAAS;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClE,CAAC;IAED,YAAY,CAAC,CAAS,EAAE,CAAS;QAChC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,CAAS,EAAE,CAAS;QAC5B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAEvC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM;QACL,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;IAC/E,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,QAAQ,CAAC,KAAY,EAAE,IAA4D;QACzF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACvF,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjE,OAAO,OAAO,CAAC;IAChB,CAAC;CACD"}

package/dist/roguelike/Stealth.d.ts

@@ -14,6 +14,19 @@ export interface StealthOptions {
  * Tracks one hidden unit's detection state. Detection is one-way and sticky: once found, a
  * unit stays found until something explicitly re-hides it (`reset`), the same way a real
  * ambush does not un-happen because the enemy that spotted you wandered off again.
+ *
+ * @example
+ * ```ts
+ * import { Stealth } from '@datamoc/mw_games/roguelike';
+ *
+ * const assassin = new Stealth({ radius: 2 });
+ * const guards = [{ x: 10, y: 10 }, { x: 5, y: 5 }];
+ *
+ * if (assassin.checkDetection({ x: 4, y: 5 }, guards)) {
+ *   console.log('spotted! that guard spends its move noticing');
+ * }
+ * console.log(assassin.isDetected);
+ * ```
  */
 export declare class Stealth {
     private detected;

package/dist/roguelike/Stealth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Stealth.d.ts","sourceRoot":"","sources":["../../src/roguelike/Stealth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,OAAO;IACnB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IAEvB,YAAY,OAAO,EAAE,cAAc,EAElC;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,IAAI,EAAE,GAAG,OAAO,CAKhE;IAED,+FAA+F;IAC/F,KAAK,IAAI,IAAI,CAEZ;CACD"}
+{"version":3,"file":"Stealth.d.ts","sourceRoot":"","sources":["../../src/roguelike/Stealth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,OAAO;IACnB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IAEvB,YAAY,OAAO,EAAE,cAAc,EAElC;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,IAAI,EAAE,GAAG,OAAO,CAKhE;IAED,+FAA+F;IAC/F,KAAK,IAAI,IAAI,CAEZ;CACD"}

package/dist/roguelike/Stealth.js

@@ -3,6 +3,19 @@ import { chebyshevDistance } from './Targeting.js';
  * Tracks one hidden unit's detection state. Detection is one-way and sticky: once found, a
  * unit stays found until something explicitly re-hides it (`reset`), the same way a real
  * ambush does not un-happen because the enemy that spotted you wandered off again.
+ *
+ * @example
+ * ```ts
+ * import { Stealth } from '@datamoc/mw_games/roguelike';
+ *
+ * const assassin = new Stealth({ radius: 2 });
+ * const guards = [{ x: 10, y: 10 }, { x: 5, y: 5 }];
+ *
+ * if (assassin.checkDetection({ x: 4, y: 5 }, guards)) {
+ *   console.log('spotted! that guard spends its move noticing');
+ * }
+ * console.log(assassin.isDetected);
+ * ```
  */
 export class Stealth {
     constructor(options) {

package/dist/roguelike/Stealth.js.map

@@ -1 +1 @@
-{"version":3,"file":"Stealth.js","sourceRoot":"","sources":["../../src/roguelike/Stealth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAenD;;;;GAIG;AACH,MAAM,OAAO,OAAO;IAInB,YAAY,OAAuB;QAH3B,aAAQ,GAAG,KAAK,CAAC;QAIxB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,cAAc,CAAC,MAAY,EAAE,SAA0B;QACtD,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAChC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/F,IAAI,KAAK;YAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QAChC,OAAO,KAAK,CAAC;IACd,CAAC;IAED,+FAA+F;IAC/F,KAAK;QACJ,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACvB,CAAC;CACD"}
+{"version":3,"file":"Stealth.js","sourceRoot":"","sources":["../../src/roguelike/Stealth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAenD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,OAAO;IAInB,YAAY,OAAuB;QAH3B,aAAQ,GAAG,KAAK,CAAC;QAIxB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,cAAc,CAAC,MAAY,EAAE,SAA0B;QACtD,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAChC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/F,IAAI,KAAK;YAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QAChC,OAAO,KAAK,CAAC;IACd,CAAC;IAED,+FAA+F;IAC/F,KAAK;QACJ,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACvB,CAAC;CACD"}

package/dist/roguelike/Targeting.d.ts

@@ -26,7 +26,26 @@ export interface TargetingOptions {
     /** whether a wall in the way blocks the shot; on by default, since most things do not arc */
     requireLineOfSight?: boolean;
 }
-/** the straight-line ruler distance a roguelike uses: diagonals cost the same as a step */
+/**
+ * The straight-line ruler distance a roguelike uses: diagonals cost the same as a step.
+ *
+ * @example
+ * ```ts
+ * import { chebyshevDistance, traceLine, hasLineOfSight, canTarget, resolveArea, Level, WALL, FLOOR } from '@datamoc/mw_games/roguelike';
+ *
+ * const level = new Level(20, 20, [WALL, FLOOR], 1); // an open floor
+ * const origin = { x: 2, y: 2 };
+ * const target = { x: 8, y: 5 };
+ *
+ * chebyshevDistance(origin, target); // 6
+ * traceLine(origin, target); // every cell the shot crosses
+ * hasLineOfSight(level, origin, target); // true - nothing blocks it
+ *
+ * if (canTarget(level, origin, target, { range: 10 })) {
+ *   const hit = resolveArea(origin, target, { kind: 'burst', radius: 2 });
+ * }
+ * ```
+ */
 export declare function chebyshevDistance(a: Step, b: Step): number;
 /**
  * Every cell a straight line crosses from `from` to `to`, `from` included and `to` included.
@@ -47,6 +66,19 @@ export declare function resolveArea(origin: Step, target: Step, shape: AreaShape
  * nearest of the 8 directions, the length is the distance aimed, and step `i` of `length`
  * spans `round(i / length * width)` cells to each side of the centre line. A width of 0
  * is a single-file beam, the same cells `line` would trace along that snapped direction.
+ *
+ * @example
+ * ```ts
+ * import { coneCells, chainTargets, knockbackPath, Level, WALL, FLOOR } from '@datamoc/mw_games/roguelike';
+ *
+ * const breath = coneCells({ x: 5, y: 5 }, { x: 5, y: 0 }, 3); // a dragon's breath, aimed north
+ *
+ * const monsters = [{ x: 5, y: 4 }, { x: 5, y: 3 }, { x: 6, y: 2 }];
+ * const arc = chainTargets(monsters, { x: 5, y: 5 }, 3, 2); // a lightning bolt hopping between them
+ *
+ * const level = new Level(20, 20, [WALL, FLOOR], 1);
+ * const shovedTo = knockbackPath(level, { x: 5, y: 5 }, { x: 1, y: 0 }, 3); // shoved 3 cells east
+ * ```
  */
 export declare function coneCells(origin: Step, target: Step, width: number): Step[];
 /**
@@ -62,6 +94,18 @@ export declare function chainTargets(candidates: readonly Step[], origin: Step,
  * once its distance is known. `mwg` supplies no default bands or multipliers, only the lookup:
  * bands are checked in order, the first whose `max` is at or above `distance` applies, and a
  * distance past every band's `max` falls back to `beyond`.
+ *
+ * @example
+ * ```ts
+ * import { rangeMultiplier, areaFalloffMultiplier, type RangeBand } from '@datamoc/mw_games/roguelike';
+ *
+ * const bands: RangeBand[] = [{ max: 2, multiplier: 1.5 }, { max: 6, multiplier: 1 }];
+ * rangeMultiplier(1, bands); // 1.5 - point-blank bonus
+ * rangeMultiplier(10, bands, 0.5); // 0.5 - past every band, falls back to `beyond`
+ *
+ * areaFalloffMultiplier(0, [1, 0.5]); // 1 - first target hit, full damage
+ * areaFalloffMultiplier(1, [1, 0.5]); // 0.5 - second target
+ * ```
  */
 export interface RangeBand {
     /** the greatest distance this band covers */

package/dist/roguelike/Targeting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Targeting.d.ts","sourceRoot":"","sources":["../../src/roguelike/Targeting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAChC,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAC;IAEd,6FAA6F;IAC7F,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,2FAA2F;AAC3F,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,IAAI,EAAE,CA2BtD;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAM1E;AAED,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAItG;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,EAAE,CAuBhF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAoB3E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,SAAS,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAsB5G;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACzB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,MAAM,SAAI,GAAG,MAAM,CAKjG;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAGrF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,CAQjG"}
+{"version":3,"file":"Targeting.d.ts","sourceRoot":"","sources":["../../src/roguelike/Targeting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAChC,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAC;IAEd,6FAA6F;IAC7F,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,IAAI,EAAE,CA2BtD;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAM1E;AAED,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAItG;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,EAAE,CAuBhF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAoB3E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,SAAS,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAsB5G;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,SAAS;IACzB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,MAAM,SAAI,GAAG,MAAM,CAKjG;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAGrF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,CAQjG"}

package/dist/roguelike/Targeting.js

@@ -1,4 +1,23 @@
-/** the straight-line ruler distance a roguelike uses: diagonals cost the same as a step */
+/**
+ * The straight-line ruler distance a roguelike uses: diagonals cost the same as a step.
+ *
+ * @example
+ * ```ts
+ * import { chebyshevDistance, traceLine, hasLineOfSight, canTarget, resolveArea, Level, WALL, FLOOR } from '@datamoc/mw_games/roguelike';
+ *
+ * const level = new Level(20, 20, [WALL, FLOOR], 1); // an open floor
+ * const origin = { x: 2, y: 2 };
+ * const target = { x: 8, y: 5 };
+ *
+ * chebyshevDistance(origin, target); // 6
+ * traceLine(origin, target); // every cell the shot crosses
+ * hasLineOfSight(level, origin, target); // true - nothing blocks it
+ *
+ * if (canTarget(level, origin, target, { range: 10 })) {
+ *   const hit = resolveArea(origin, target, { kind: 'burst', radius: 2 });
+ * }
+ * ```
+ */
 export function chebyshevDistance(a, b) {
     return Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y));
 }
@@ -79,6 +98,19 @@ export function resolveArea(origin, target, shape) {
  * nearest of the 8 directions, the length is the distance aimed, and step `i` of `length`
  * spans `round(i / length * width)` cells to each side of the centre line. A width of 0
  * is a single-file beam, the same cells `line` would trace along that snapped direction.
+ *
+ * @example
+ * ```ts
+ * import { coneCells, chainTargets, knockbackPath, Level, WALL, FLOOR } from '@datamoc/mw_games/roguelike';
+ *
+ * const breath = coneCells({ x: 5, y: 5 }, { x: 5, y: 0 }, 3); // a dragon's breath, aimed north
+ *
+ * const monsters = [{ x: 5, y: 4 }, { x: 5, y: 3 }, { x: 6, y: 2 }];
+ * const arc = chainTargets(monsters, { x: 5, y: 5 }, 3, 2); // a lightning bolt hopping between them
+ *
+ * const level = new Level(20, 20, [WALL, FLOOR], 1);
+ * const shovedTo = knockbackPath(level, { x: 5, y: 5 }, { x: 1, y: 0 }, 3); // shoved 3 cells east
+ * ```
  */
 export function coneCells(origin, target, width) {
     const dx = target.x - origin.x;

package/dist/roguelike/Targeting.js.map

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

package/dist/roguelike/TriggerTracker.d.ts

@@ -5,6 +5,16 @@
  * proc shares. `mwg` tracks only the streak and its turn-window; what counts as a qualifying
  * event, and what a streak length unlocks, stay the game's own rule, fired from `trigger`'s
  * own returned count.
+ *
+ * @example
+ * ```ts
+ * import { TriggerTracker } from '@datamoc/mw_games/roguelike';
+ *
+ * const combo = new TriggerTracker(2); // a hit must land within 2 turns of the last
+ * combo.trigger(1); // streak: 1
+ * combo.trigger(2); // streak: 2 - within the window
+ * combo.trigger(10); // streak restarts at 1 - the window lapsed
+ * ```
  */
 export declare class TriggerTracker {
     private readonly window;

package/dist/roguelike/TriggerTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TriggerTracker.d.ts","sourceRoot":"","sources":["../../src/roguelike/TriggerTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAa;IAE7B,YAAY,MAAM,EAAE,MAAM,EAEzB;IAED,oFAAoF;IACpF,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI5B;IAED,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9B;IAED,uGAAuG;IACvG,KAAK,IAAI,IAAI,CAGZ;IAED,MAAM,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAE7C;IAED,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAK1F;CACD"}
+{"version":3,"file":"TriggerTracker.d.ts","sourceRoot":"","sources":["../../src/roguelike/TriggerTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAa;IAE7B,YAAY,MAAM,EAAE,MAAM,EAEzB;IAED,oFAAoF;IACpF,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI5B;IAED,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9B;IAED,uGAAuG;IACvG,KAAK,IAAI,IAAI,CAGZ;IAED,MAAM,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAE7C;IAED,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAK1F;CACD"}

package/dist/roguelike/TriggerTracker.js

@@ -5,6 +5,16 @@
  * proc shares. `mwg` tracks only the streak and its turn-window; what counts as a qualifying
  * event, and what a streak length unlocks, stay the game's own rule, fired from `trigger`'s
  * own returned count.
+ *
+ * @example
+ * ```ts
+ * import { TriggerTracker } from '@datamoc/mw_games/roguelike';
+ *
+ * const combo = new TriggerTracker(2); // a hit must land within 2 turns of the last
+ * combo.trigger(1); // streak: 1
+ * combo.trigger(2); // streak: 2 - within the window
+ * combo.trigger(10); // streak restarts at 1 - the window lapsed
+ * ```
  */
 export class TriggerTracker {
     constructor(window) {

package/dist/roguelike/TriggerTracker.js.map

@@ -1 +1 @@
-{"version":3,"file":"TriggerTracker.js","sourceRoot":"","sources":["../../src/roguelike/TriggerTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,cAAc;IAK1B,YAAY,MAAc;QAHlB,WAAM,GAAG,CAAC,CAAC;QACX,aAAQ,GAAG,CAAC,QAAQ,CAAC;QAG5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;IAED,oFAAoF;IACpF,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,IAAY;QACnB,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IAED,4FAA4F;IAC5F,QAAQ,CAAC,IAAY;QACpB,OAAO,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC;IAC5C,CAAC;IAED,uGAAuG;IACvG,KAAK;QACJ,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAChB,IAAI,CAAC,QAAQ,GAAG,CAAC,QAAQ,CAAC;IAC3B,CAAC;IAED,MAAM;QACL,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,MAAc,EAAE,IAA0C;QACzE,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QAC3C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC7B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QACjC,OAAO,OAAO,CAAC;IAChB,CAAC;CACD"}
+{"version":3,"file":"TriggerTracker.js","sourceRoot":"","sources":["../../src/roguelike/TriggerTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,cAAc;IAK1B,YAAY,MAAc;QAHlB,WAAM,GAAG,CAAC,CAAC;QACX,aAAQ,GAAG,CAAC,QAAQ,CAAC;QAG5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;IAED,oFAAoF;IACpF,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,IAAY;QACnB,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IAED,4FAA4F;IAC5F,QAAQ,CAAC,IAAY;QACpB,OAAO,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC;IAC5C,CAAC;IAED,uGAAuG;IACvG,KAAK;QACJ,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAChB,IAAI,CAAC,QAAQ,GAAG,CAAC,QAAQ,CAAC;IAC3B,CAAC;IAED,MAAM;QACL,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,MAAc,EAAE,IAA0C;QACzE,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QAC3C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC7B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QACjC,OAAO,OAAO,CAAC;IAChB,CAAC;CACD"}

package/dist/roguelike/generate.d.ts

@@ -75,6 +75,17 @@ export interface DungeonResult {
      */
     roomBuilders: string[];
 }
+/**
+ * The two terrain kinds every dungeon needs: wall (index 0) and floor (index 1). A game
+ * appends its own kinds (traps, doors) after these via `DungeonOptions.kinds`.
+ *
+ * @example
+ * ```ts
+ * import { DUNGEON_KINDS } from '@datamoc/mw_games/roguelike';
+ *
+ * const kinds = [...DUNGEON_KINDS, { passable: false, transparent: true }]; // + a window
+ * ```
+ */
 export declare const DUNGEON_KINDS: TerrainKind[];
 /**
  * The full pipeline result: the level, its room graph, and how many placement attempts were
@@ -82,8 +93,37 @@ export declare const DUNGEON_KINDS: TerrainKind[];
  * for a caller that has no use for the graph or retry count.
  */
 export declare function generateDungeonGraph(options: DungeonOptions): DungeonResult;
+/**
+ * Rooms joined by corridors, seeded and reproducible.
+ *
+ * @example
+ * ```ts
+ * import { generateDungeon, generateDungeonGraph } from '@datamoc/mw_games/roguelike';
+ * import { Random } from '@datamoc/mw_games/core';
+ *
+ * Random.push(12345); // the same seed always produces the same floor
+ * const level = generateDungeon({ width: 60, height: 40, rooms: 12 });
+ * Random.pop();
+ *
+ * // generateDungeonGraph is the same pipeline, also returning the room graph and retries
+ * const { level: level2, graph, retries, roomBuilders } = generateDungeonGraph({ width: 60, height: 40 });
+ * ```
+ */
 export declare function generateDungeon(options: DungeonOptions): Level;
-/** a random passable cell, avoiding any listed as taken */
+/**
+ * A random passable cell, avoiding any listed as taken.
+ *
+ * @example
+ * ```ts
+ * import { generateDungeon, findFreeCell, furthestRoom, rectCenter } from '@datamoc/mw_games/roguelike';
+ *
+ * const level = generateDungeon({ width: 40, height: 30 });
+ * const start = rectCenter(level.rooms[0]);
+ *
+ * const stairsRoom = furthestRoom(level, start); // put the exit far from the entrance
+ * const monsterCell = findFreeCell(level, new Set([level.index(start.x, start.y)]));
+ * ```
+ */
 export declare function findFreeCell(level: Level, taken?: ReadonlySet<number>): number | null;
 /** the room furthest from `from`, by straight-line distance between centres */
 export declare function furthestRoom(level: Level, from: {

package/dist/roguelike/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/roguelike/generate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAA4B,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE/E;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IAEf,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,iGAAiG;IACjG,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IAEtB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAE/B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACtC,6EAA6E;IAC7E,YAAY,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/C,yDAAyD;IACzD,gBAAgB,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC;CAC9D;AAED,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,wFAAwF;IACxF,KAAK,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,KAAK,CAAC;IAEb,uEAAuE;IACvE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAElB,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EAGtC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CA4E3E;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,KAAK,CAE9D;AA0CD,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,GAAE,WAAW,CAAC,MAAM,CAAa,GAAG,MAAM,GAAG,IAAI,CAGhG;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,IAAI,CActF"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/roguelike/generate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAA4B,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE/E;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IAEf,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,iGAAiG;IACjG,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IAEtB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAE/B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACtC,6EAA6E;IAC7E,YAAY,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/C,yDAAyD;IACzD,gBAAgB,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC;CAC9D;AAED,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,wFAAwF;IACxF,KAAK,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,KAAK,CAAC;IAEb,uEAAuE;IACvE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAElB,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,EAGtC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CA4E3E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,KAAK,CAE9D;AA0CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,GAAE,WAAW,CAAC,MAAM,CAAa,GAAG,MAAM,GAAG,IAAI,CAGhG;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,IAAI,CActF"}

package/dist/roguelike/generate.js

@@ -1,6 +1,17 @@
 import * as Random from '../core/Random.js';
 import { Level, rectCenter, rectsOverlap } from './Level.js';
 import { hallBuilder, pickBuilder } from './RoomBuilders.js';
+/**
+ * The two terrain kinds every dungeon needs: wall (index 0) and floor (index 1). A game
+ * appends its own kinds (traps, doors) after these via `DungeonOptions.kinds`.
+ *
+ * @example
+ * ```ts
+ * import { DUNGEON_KINDS } from '@datamoc/mw_games/roguelike';
+ *
+ * const kinds = [...DUNGEON_KINDS, { passable: false, transparent: true }]; // + a window
+ * ```
+ */
 export const DUNGEON_KINDS = [
     { passable: false, transparent: false }, //0 wall
     { passable: true, transparent: true }, //1 floor
@@ -64,6 +75,22 @@ export function generateDungeonGraph(options) {
     level.rooms = placed;
     return { level, graph, retries, roomBuilders };
 }
+/**
+ * Rooms joined by corridors, seeded and reproducible.
+ *
+ * @example
+ * ```ts
+ * import { generateDungeon, generateDungeonGraph } from '@datamoc/mw_games/roguelike';
+ * import { Random } from '@datamoc/mw_games/core';
+ *
+ * Random.push(12345); // the same seed always produces the same floor
+ * const level = generateDungeon({ width: 60, height: 40, rooms: 12 });
+ * Random.pop();
+ *
+ * // generateDungeonGraph is the same pipeline, also returning the room graph and retries
+ * const { level: level2, graph, retries, roomBuilders } = generateDungeonGraph({ width: 60, height: 40 });
+ * ```
+ */
 export function generateDungeon(options) {
     return generateDungeonGraph(options).level;
 }
@@ -94,7 +121,20 @@ function carveLine(level, fromCoord, toCoord, fixed, horizontal, floor) {
             level.set(x, y, floor);
     }
 }
-/** a random passable cell, avoiding any listed as taken */
+/**
+ * A random passable cell, avoiding any listed as taken.
+ *
+ * @example
+ * ```ts
+ * import { generateDungeon, findFreeCell, furthestRoom, rectCenter } from '@datamoc/mw_games/roguelike';
+ *
+ * const level = generateDungeon({ width: 40, height: 30 });
+ * const start = rectCenter(level.rooms[0]);
+ *
+ * const stairsRoom = furthestRoom(level, start); // put the exit far from the entrance
+ * const monsterCell = findFreeCell(level, new Set([level.index(start.x, start.y)]));
+ * ```
+ */
 export function findFreeCell(level, taken = new Set()) {
     const free = level.passableCells().filter((cell) => !taken.has(cell));
     return free.length > 0 ? free[Random.int(free.length)] : null;