@datamoc/mw_games 0.1.1 → 0.2.0

package/dist/core/Save.js

@@ -5,6 +5,8 @@
  * constructor pair), not to be serialised by reference with cycles preserved; that is a
  * different, much larger problem than a save system needs to solve.
  */
+import { scramble, unscramble } from './Scramble.js';
+import { checkSize, sanitizeInboundText } from './Sanitize.js';
 /** an in-memory fallback, so saving still works where `localStorage` is unavailable */
 class MemoryStorage {
     constructor() {
@@ -60,9 +62,63 @@ export class SaveSystem {
         }
         return { meta: { ...data.meta, version: this.version }, state: state };
     }
+    /**
+     * Adopts a save this `SaveSystem` never wrote: `normalize` runs once on `externalBytes`,
+     * producing state at version 0, which is then carried up through the same `migrations`
+     * chain an ordinary `load` already uses to reach the current version - a game supplies
+     * one `normalize` per external format it wants to accept (an `rpg.decodeMarshal`-based
+     * one for a `Game.rxdata`, say), rather than hand-rolling "decode, then call `save`"
+     * outside the versioned pipeline every migration otherwise goes through.
+     *
+     * `externalBytes` is size-checked before `normalize` ever sees it - a cheap, structural
+     * guard against a truncated or hostile file, ahead of and distinct from validating
+     * whatever shape `normalize` itself produces.
+     */
+    importExternal(slot, externalBytes, normalize, preview) {
+        checkSize(externalBytes);
+        let state = normalize(externalBytes);
+        for (let v = 0; v < this.version; v++) {
+            state = (this.migrations[v] ?? ((s) => s))(state);
+        }
+        const data = { meta: { version: this.version, savedAt: Date.now(), preview }, state: state };
+        this.storage.write(this.key(slot), JSON.stringify(data));
+    }
     delete(slot) {
         this.storage.remove(this.key(slot));
     }
+    /**
+     * Reads a slot back out as a portable string a player can carry to another browser or
+     * device, or hand to their own server - the counterpart to `importSlot`, for `mwg`'s own
+     * save shape rather than a foreign one (`importExternal` covers that side). `scrambleKey`,
+     * when given, runs the payload through `scramble` first: not encryption, only enough to
+     * stop a save being hand-edited in a text editor. Returns null for a slot with no save.
+     */
+    exportSlot(slot, scrambleKey) {
+        const raw = this.storage.read(this.key(slot));
+        if (raw === null)
+            return null;
+        return scrambleKey ? scramble(raw, scrambleKey) : raw;
+    }
+    /**
+     * Writes a payload from this `SaveSystem`'s own `exportSlot` back as an ordinary save,
+     * migrated up to the current version the same way `load` migrates an older save found
+     * locally. `scrambleKey` must match whatever `exportSlot` scrambled it with, if any.
+     *
+     * `payload` is size- and control-character-checked before it is unscrambled or parsed -
+     * this crossed a device or a server, unlike `load`'s own `localStorage`, which this same
+     * `SaveSystem` wrote itself and has no reason to distrust.
+     */
+    importSlot(slot, payload, scrambleKey) {
+        checkSize(payload);
+        const raw = scrambleKey ? unscramble(payload, scrambleKey) : payload;
+        const data = JSON.parse(sanitizeInboundText(raw));
+        let state = data.state;
+        for (let v = data.meta.version; v < this.version; v++) {
+            state = (this.migrations[v] ?? ((s) => s))(state);
+        }
+        const normalized = { meta: { ...data.meta, version: this.version }, state: state };
+        this.storage.write(this.key(slot), JSON.stringify(normalized));
+    }
     /** every slot with a save, and its metadata - for a save-select screen */
     list() {
         const prefix = `mwg-save:${this.namespace}:`;

package/dist/core/Save.js.map

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

package/dist/core/SaveSync.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Uploads/downloads one `SaveSystem.exportSlot` payload to a game's own HTTPS endpoint - the
+ * server half of item 124's save export/import, following `FeedbackClient`'s own shape
+ * (an injectable transport a game points at its own endpoint) rather than a second pattern:
+ * `mwg` ships no backend and assumes none here either.
+ */
+export interface SaveSyncOptions {
+    endpoint: string;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+export interface SaveSyncResponse {
+    ok: boolean;
+    status: number;
+}
+export declare class SaveSyncClient {
+    private readonly endpoint;
+    private readonly timeoutMs;
+    private readonly fetchFn;
+    constructor(options: SaveSyncOptions);
+    /** sends an `exportSlot` payload to the endpoint, replacing whatever it held before */
+    upload(payload: string): Promise<SaveSyncResponse>;
+    /** fetches whatever payload the endpoint currently holds, ready for `SaveSystem.importSlot` */
+    download(): Promise<string>;
+}
+//# sourceMappingURL=SaveSync.d.ts.map

package/dist/core/SaveSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SaveSync.d.ts","sourceRoot":"","sources":["../../src/core/SaveSync.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD,YAAY,OAAO,EAAE,eAAe,EAOnC;IAED,uFAAuF;IACjF,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgBvD;IAED,+FAA+F;IACzF,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAYhC;CACD"}

package/dist/core/SaveSync.js

@@ -0,0 +1,52 @@
+export class SaveSyncClient {
+    constructor(options) {
+        if (!options.endpoint)
+            throw new Error('save sync endpoint is required');
+        this.endpoint = options.endpoint;
+        this.timeoutMs = options.timeoutMs ?? 10000;
+        if (!(this.timeoutMs > 0))
+            throw new Error('save sync timeout must be positive');
+        this.fetchFn = options.fetch ?? globalThis.fetch;
+        if (!this.fetchFn)
+            throw new Error('fetch is unavailable; provide SaveSyncOptions.fetch');
+    }
+    /** sends an `exportSlot` payload to the endpoint, replacing whatever it held before */
+    async upload(payload) {
+        if (!payload)
+            throw new Error('save sync payload cannot be empty');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchFn(this.endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ payload }),
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                throw new Error(`save upload failed with HTTP ${response.status}`);
+            return { ok: true, status: response.status };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** fetches whatever payload the endpoint currently holds, ready for `SaveSystem.importSlot` */
+    async download() {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchFn(this.endpoint, { signal: controller.signal });
+            if (!response.ok)
+                throw new Error(`save download failed with HTTP ${response.status}`);
+            const data = (await response.json());
+            if (typeof data.payload !== 'string')
+                throw new Error('save download response missing a string payload');
+            return data.payload;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=SaveSync.js.map

package/dist/core/SaveSync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SaveSync.js","sourceRoot":"","sources":["../../src/core/SaveSync.ts"],"names":[],"mappings":"AAiBA,MAAM,OAAO,cAAc;IAK1B,YAAY,OAAwB;QACnC,IAAI,CAAC,OAAO,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACzE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;QAC5C,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACjF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;QACjD,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IAC3F,CAAC;IAED,uFAAuF;IACvF,KAAK,CAAC,MAAM,CAAC,OAAe;QAC3B,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACnE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,CAAC;YACJ,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE;gBAClD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;gBACjC,MAAM,EAAE,UAAU,CAAC,MAAM;aACzB,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YACrF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC9C,CAAC;gBAAS,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACF,CAAC;IAED,+FAA+F;IAC/F,KAAK,CAAC,QAAQ;QACb,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,CAAC;YACJ,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;YAClF,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YACvF,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA0B,CAAC;YAC9D,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;YACzG,OAAO,IAAI,CAAC,OAAO,CAAC;QACrB,CAAC;gBAAS,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACF,CAAC;CACD"}

package/dist/core/Scramble.d.ts

@@ -0,0 +1,13 @@
+/**
+ * XOR-with-a-key text scrambling. This is explicitly **not encryption** and must never be
+ * presented to a player or a game's own documentation as one: it stops a save being
+ * hand-edited by someone opening it in a text editor, and deliberately nothing stronger -
+ * the key is recoverable from the scrambled text plus any known plaintext fragment, the
+ * classic XOR weakness, accepted on purpose rather than overlooked. Reach for this only
+ * where "not trivially editable" is the actual requirement, per `SaveSystem.exportSlot`'s
+ * own use of it.
+ */
+export declare function scramble(text: string, key: string): string;
+/** reverses `scramble`; throws if `key` does not match the one it was scrambled with (garbled UTF-8 rather than a silent wrong answer) */
+export declare function unscramble(payload: string, key: string): string;
+//# sourceMappingURL=Scramble.d.ts.map

package/dist/core/Scramble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scramble.d.ts","sourceRoot":"","sources":["../../src/core/Scramble.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAO1D;AAED,0IAA0I;AAC1I,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAO/D"}

package/dist/core/Scramble.js

@@ -0,0 +1,44 @@
+/**
+ * XOR-with-a-key text scrambling. This is explicitly **not encryption** and must never be
+ * presented to a player or a game's own documentation as one: it stops a save being
+ * hand-edited by someone opening it in a text editor, and deliberately nothing stronger -
+ * the key is recoverable from the scrambled text plus any known plaintext fragment, the
+ * classic XOR weakness, accepted on purpose rather than overlooked. Reach for this only
+ * where "not trivially editable" is the actual requirement, per `SaveSystem.exportSlot`'s
+ * own use of it.
+ */
+export function scramble(text, key) {
+    if (!key)
+        throw new Error('scramble needs a non-empty key');
+    const bytes = new TextEncoder().encode(text);
+    const keyBytes = new TextEncoder().encode(key);
+    const out = new Uint8Array(bytes.length);
+    for (let i = 0; i < bytes.length; i++)
+        out[i] = bytes[i] ^ keyBytes[i % keyBytes.length];
+    return toBase64(out);
+}
+/** reverses `scramble`; throws if `key` does not match the one it was scrambled with (garbled UTF-8 rather than a silent wrong answer) */
+export function unscramble(payload, key) {
+    if (!key)
+        throw new Error('scramble needs a non-empty key');
+    const bytes = fromBase64(payload);
+    const keyBytes = new TextEncoder().encode(key);
+    const out = new Uint8Array(bytes.length);
+    for (let i = 0; i < bytes.length; i++)
+        out[i] = bytes[i] ^ keyBytes[i % keyBytes.length];
+    return new TextDecoder('utf-8', { fatal: true }).decode(out);
+}
+function toBase64(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function fromBase64(text) {
+    const binary = atob(text);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+//# sourceMappingURL=Scramble.js.map

package/dist/core/Scramble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scramble.js","sourceRoot":"","sources":["../../src/core/Scramble.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,GAAW;IACjD,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzF,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED,0IAA0I;AAC1I,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,GAAW;IACtD,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzF,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,QAAQ,CAAC,KAAiB;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACrB,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACxE,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/core/Session.d.ts

@@ -0,0 +1,21 @@
+import { type SaveStorage } from './Save.ts';
+/**
+ * Counts how many times a game has been launched, persisted across page loads.
+ *
+ * Not an achievement, a quest counter, or anything a game reads to change its own
+ * behaviour: the one thing this exists for is the signal a native wrapper (Capacitor,
+ * Tauri, whatever a game ships through) needs to decide whether a player has used the
+ * game enough to plausibly be worth asking for a rating. `mwg` only counts; it never
+ * prompts, and has no opinion on what "enough" means.
+ */
+export interface SessionOptions {
+    /** namespaces the count, so two games sharing an origin never collide */
+    namespace?: string;
+    storage?: SaveStorage;
+}
+export declare class Session {
+    /** how many times this game has been launched, including this one */
+    readonly launches: number;
+    constructor(options?: SessionOptions);
+}
+//# sourceMappingURL=Session.d.ts.map

package/dist/core/Session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Session.d.ts","sourceRoot":"","sources":["../../src/core/Session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7D;;;;;;;;GAQG;AAEH,MAAM,WAAW,cAAc;IAC9B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,qBAAa,OAAO;IACnB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,YAAY,OAAO,GAAE,cAAmB,EAOvC;CACD"}

package/dist/core/Session.js

@@ -0,0 +1,11 @@
+import { defaultStorage } from './Save.js';
+export class Session {
+    constructor(options = {}) {
+        const storage = options.storage ?? defaultStorage();
+        const key = `mwg-session:${options.namespace ?? 'default'}`;
+        const previous = Number(storage.read(key) ?? '0');
+        this.launches = (Number.isFinite(previous) ? previous : 0) + 1;
+        storage.write(key, String(this.launches));
+    }
+}
+//# sourceMappingURL=Session.js.map

package/dist/core/Session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Session.js","sourceRoot":"","sources":["../../src/core/Session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAoB,MAAM,WAAW,CAAC;AAkB7D,MAAM,OAAO,OAAO;IAInB,YAAY,OAAO,GAAmB,EAAE;QACvC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,cAAc,EAAE,CAAC;QACpD,MAAM,GAAG,GAAG,eAAe,OAAO,CAAC,SAAS,IAAI,SAAS,EAAE,CAAC;QAE5D,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;QAClD,IAAI,CAAC,QAAQ,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC/D,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3C,CAAC;CACD"}

package/dist/core/Spawner.d.ts

@@ -0,0 +1,48 @@
+/**
+ * One wave: `entries` spawn spread evenly across `duration` seconds, starting `delay`
+ * seconds after the spawner itself starts (not after the previous wave ends - waves may
+ * overlap, which is exactly what a game escalating toward a boss often wants).
+ */
+export interface Wave<T> {
+    delay: number;
+    entries: readonly {
+        kind: T;
+        count: number;
+    }[];
+    /** spread `entries` across this many seconds; 0 (the default) spawns them all at once */
+    duration?: number;
+}
+export interface SpawnerOptions<T> {
+    waves: readonly Wave<T>[];
+    onSpawn: (kind: T) => void;
+    /** fires once, the moment the first entry of a wave actually spawns */
+    onWaveStart?: (waveIndex: number) => void;
+    /** fires once every scheduled spawn across every wave has happened */
+    onComplete?: () => void;
+}
+/**
+ * A `dt`-driven timer for escalating, timed spawning - "wave 3 starts at t+45s, spawns 8 of
+ * kind A and 2 of kind B over the next 10s" - distinct in shape from `roguelike.Scheduler`,
+ * which orders whose turn it is by energy cost and has no concept of real time at all. Not
+ * specific to tower defense: any game with escalating timed spawns (a horde mode, a survival
+ * minigame) wants the same primitive.
+ *
+ * The whole schedule is flattened and sorted once, at construction, rather than tracked wave
+ * by wave - simpler to get right, and cheap enough that a spawner is not something a game
+ * expects to have thousands of.
+ */
+export declare class Spawner<T> {
+    private schedule;
+    private cursor;
+    private elapsed;
+    private startedWaves;
+    private completed;
+    private onSpawn;
+    private onWaveStart?;
+    private onComplete?;
+    constructor(options: SpawnerOptions<T>);
+    update(dt: number): void;
+    /** true once every scheduled spawn has happened */
+    get isComplete(): boolean;
+}
+//# sourceMappingURL=Spawner.d.ts.map

package/dist/core/Spawner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Spawner.d.ts","sourceRoot":"","sources":["../../src/core/Spawner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAE/C,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAChC,KAAK,EAAE,SAAS,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAE3B,uEAAuE;IACvE,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAE1C,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAQD;;;;;;;;;;GAUG;AACH,qBAAa,OAAO,CAAC,CAAC;IACrB,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAK;IAIpB,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,WAAW,CAAC,CAA8B;IAClD,OAAO,CAAC,UAAU,CAAC,CAAa;IAEhC,YAAY,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAuBrC;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAkBvB;IAED,mDAAmD;IACnD,IAAI,UAAU,IAAI,OAAO,CAExB;CACD"}

package/dist/core/Spawner.js

@@ -0,0 +1,65 @@
+/**
+ * A `dt`-driven timer for escalating, timed spawning - "wave 3 starts at t+45s, spawns 8 of
+ * kind A and 2 of kind B over the next 10s" - distinct in shape from `roguelike.Scheduler`,
+ * which orders whose turn it is by energy cost and has no concept of real time at all. Not
+ * specific to tower defense: any game with escalating timed spawns (a horde mode, a survival
+ * minigame) wants the same primitive.
+ *
+ * The whole schedule is flattened and sorted once, at construction, rather than tracked wave
+ * by wave - simpler to get right, and cheap enough that a spawner is not something a game
+ * expects to have thousands of.
+ */
+export class Spawner {
+    constructor(options) {
+        this.schedule = [];
+        this.cursor = 0;
+        this.elapsed = 0;
+        //a Set, not a single "last" index - overlapping waves (see the Wave doc) interleave in
+        //the time-sorted schedule, so a wave already started can recur after a different one's
+        //entry sorts between two of its own
+        this.startedWaves = new Set();
+        this.completed = false;
+        this.onSpawn = options.onSpawn;
+        this.onWaveStart = options.onWaveStart;
+        this.onComplete = options.onComplete;
+        options.waves.forEach((wave, waveIndex) => {
+            const total = wave.entries.reduce((sum, entry) => sum + entry.count, 0);
+            const duration = wave.duration ?? 0;
+            let i = 0;
+            for (const entry of wave.entries) {
+                for (let n = 0; n < entry.count; n++, i++) {
+                    const spread = total > 1 && duration > 0 ? (i / (total - 1)) * duration : 0;
+                    this.schedule.push({ time: wave.delay + spread, kind: entry.kind, waveIndex });
+                }
+            }
+        });
+        this.schedule.sort((a, b) => a.time - b.time);
+        if (this.schedule.length === 0) {
+            this.completed = true;
+            this.onComplete?.();
+        }
+    }
+    update(dt) {
+        if (this.completed)
+            return;
+        this.elapsed += dt;
+        while (this.cursor < this.schedule.length && this.schedule[this.cursor].time <= this.elapsed) {
+            const spawn = this.schedule[this.cursor];
+            if (!this.startedWaves.has(spawn.waveIndex)) {
+                this.startedWaves.add(spawn.waveIndex);
+                this.onWaveStart?.(spawn.waveIndex);
+            }
+            this.onSpawn(spawn.kind);
+            this.cursor++;
+        }
+        if (this.cursor >= this.schedule.length) {
+            this.completed = true;
+            this.onComplete?.();
+        }
+    }
+    /** true once every scheduled spawn has happened */
+    get isComplete() {
+        return this.completed;
+    }
+}
+//# sourceMappingURL=Spawner.js.map

package/dist/core/Spawner.js.map

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

package/dist/core/Tween.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The one interpolation primitive every dt-driven feature wants: given a duration and a
+ * function of progress, run it from 0 to 1 and resolve. `DialogueStage`'s fades and
+ * `render.Camera`'s shake decay each used to hand-roll this same shape under a different
+ * name; this is that shape, pulled out once.
+ */
+export type Easing = (t: number) => number;
+/** a small standard set, named the way CSS and most engines already do */
+export declare const Easing: Record<'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic', Easing>;
+/** Runs any number of concurrent tweens; a game or a widget drives it from its own `update(dt)`. */
+export declare class Tweener {
+    private tweens;
+    /**
+     * Runs `apply` with progress eased from 0 to 1 over `duration` seconds, resolving once it
+     * reaches 1. A non-positive duration applies the end state at once rather than waiting a
+     * frame for it.
+     */
+    tween(duration: number, apply: (t: number) => void, ease?: Easing): Promise<void>;
+    update(dt: number): void;
+    /** true while any tween is still running */
+    get isBusy(): boolean;
+    /** drops every running tween without applying its end state or resolving it - a teardown, not a completion */
+    clear(): void;
+}
+//# sourceMappingURL=Tween.d.ts.map

package/dist/core/Tween.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tween.d.ts","sourceRoot":"","sources":["../../src/core/Tween.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AAE3C,0EAA0E;AAC1E,eAAO,MAAM,MAAM,EAAE,MAAM,CAC1B,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,eAAe,GAAG,aAAa,GAAG,cAAc,GAAG,gBAAgB,EAC7G,MAAM,CASN,CAAC;AAUF,oGAAoG;AACpG,qBAAa,OAAO;IACnB,OAAO,CAAC,MAAM,CAAqB;IAEnC;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,EAAE,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/F;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAevB;IAED,4CAA4C;IAC5C,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,8GAA8G;IAC9G,KAAK,IAAI,IAAI,CAEZ;CACD"}

package/dist/core/Tween.js

@@ -0,0 +1,60 @@
+/**
+ * The one interpolation primitive every dt-driven feature wants: given a duration and a
+ * function of progress, run it from 0 to 1 and resolve. `DialogueStage`'s fades and
+ * `render.Camera`'s shake decay each used to hand-roll this same shape under a different
+ * name; this is that shape, pulled out once.
+ */
+/** a small standard set, named the way CSS and most engines already do */
+export const Easing = {
+    linear: (t) => t,
+    easeInQuad: (t) => t * t,
+    easeOutQuad: (t) => t * (2 - t),
+    easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : 1 - ((-2 * t + 2) ** 2) / 2),
+    easeInCubic: (t) => t * t * t,
+    easeOutCubic: (t) => 1 - (1 - t) ** 3,
+    easeInOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : 1 - ((-2 * t + 2) ** 3) / 2),
+};
+/** Runs any number of concurrent tweens; a game or a widget drives it from its own `update(dt)`. */
+export class Tweener {
+    constructor() {
+        this.tweens = [];
+    }
+    /**
+     * Runs `apply` with progress eased from 0 to 1 over `duration` seconds, resolving once it
+     * reaches 1. A non-positive duration applies the end state at once rather than waiting a
+     * frame for it.
+     */
+    tween(duration, apply, ease = Easing.linear) {
+        if (!(duration > 0)) {
+            apply(1);
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.tweens.push({ elapsed: 0, duration, apply, ease, resolve });
+        });
+    }
+    update(dt) {
+        if (this.tweens.length === 0)
+            return;
+        //iterate a copy: a tween's resolve may start another, which must not be advanced
+        //again within this same update
+        for (const tween of [...this.tweens]) {
+            tween.elapsed += dt;
+            const t = Math.min(1, tween.elapsed / tween.duration);
+            tween.apply(tween.ease(t));
+            if (t >= 1) {
+                this.tweens.splice(this.tweens.indexOf(tween), 1);
+                tween.resolve();
+            }
+        }
+    }
+    /** true while any tween is still running */
+    get isBusy() {
+        return this.tweens.length > 0;
+    }
+    /** drops every running tween without applying its end state or resolving it - a teardown, not a completion */
+    clear() {
+        this.tweens = [];
+    }
+}
+//# sourceMappingURL=Tween.js.map

package/dist/core/Tween.js.map

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

package/dist/core/UndoHistory.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A bounded, generic back/forward step through recent turns - a mode a game opts into
+ * (useless in a permadeath roguelike, useful elsewhere), agnostic about what "a turn's
+ * state" actually contains the same way `SaveSystem` is agnostic about what "the save"
+ * contains: a game serializes its own turn-scoped state (a `Level`, a `BoardGrid`, whatever
+ * it has) and this only ever stores and replays snapshots of it, never interprets them.
+ *
+ * Distinct from `Recorder`/`Player` (item 42), which replay a whole `Input.onAction` log
+ * deterministically for testing, not a bounded, player-facing "undo my last move".
+ */
+export interface UndoHistoryOptions {
+    /** states retained before the oldest is dropped; defaults to 50 */
+    limit?: number;
+}
+export declare class UndoHistory<T> {
+    private history;
+    private cursor;
+    private readonly limit;
+    constructor(options?: UndoHistoryOptions);
+    /**
+     * Records `state` as the new current point - the normal "a turn was taken" case. Any
+     * redo history beyond the current point is discarded, the same rule undo/redo everywhere
+     * follows: taking a new turn after undoing invalidates whatever future it undid away from.
+     */
+    push(state: T): void;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /** steps back one state and returns it; null when already at the oldest retained state */
+    undo(): T | null;
+    /** steps forward one state and returns it; null when already at the newest state */
+    redo(): T | null;
+    /** the state at the current point, or null before anything has ever been pushed */
+    get current(): T | null;
+    /** drops everything - a new game, a floor transition, anywhere undoing across the boundary makes no sense */
+    clear(): void;
+}
+//# sourceMappingURL=UndoHistory.d.ts.map

package/dist/core/UndoHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UndoHistory.d.ts","sourceRoot":"","sources":["../../src/core/UndoHistory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IAClC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,WAAW,CAAC,CAAC;IACzB,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,YAAY,OAAO,GAAE,kBAAuB,EAE3C;IAED;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAKnB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,0FAA0F;IAC1F,IAAI,IAAI,CAAC,GAAG,IAAI,CAIf;IAED,oFAAoF;IACpF,IAAI,IAAI,CAAC,GAAG,IAAI,CAIf;IAED,mFAAmF;IACnF,IAAI,OAAO,IAAI,CAAC,GAAG,IAAI,CAEtB;IAED,6GAA6G;IAC7G,KAAK,IAAI,IAAI,CAGZ;CACD"}

package/dist/core/UndoHistory.js

@@ -0,0 +1,49 @@
+export class UndoHistory {
+    constructor(options = {}) {
+        this.history = [];
+        this.cursor = -1;
+        this.limit = Math.max(1, options.limit ?? 50);
+    }
+    /**
+     * Records `state` as the new current point - the normal "a turn was taken" case. Any
+     * redo history beyond the current point is discarded, the same rule undo/redo everywhere
+     * follows: taking a new turn after undoing invalidates whatever future it undid away from.
+     */
+    push(state) {
+        this.history.length = this.cursor + 1;
+        this.history.push(state);
+        if (this.history.length > this.limit)
+            this.history.shift();
+        this.cursor = this.history.length - 1;
+    }
+    get canUndo() {
+        return this.cursor > 0;
+    }
+    get canRedo() {
+        return this.cursor < this.history.length - 1;
+    }
+    /** steps back one state and returns it; null when already at the oldest retained state */
+    undo() {
+        if (!this.canUndo)
+            return null;
+        this.cursor--;
+        return this.history[this.cursor];
+    }
+    /** steps forward one state and returns it; null when already at the newest state */
+    redo() {
+        if (!this.canRedo)
+            return null;
+        this.cursor++;
+        return this.history[this.cursor];
+    }
+    /** the state at the current point, or null before anything has ever been pushed */
+    get current() {
+        return this.cursor >= 0 ? this.history[this.cursor] : null;
+    }
+    /** drops everything - a new game, a floor transition, anywhere undoing across the boundary makes no sense */
+    clear() {
+        this.history = [];
+        this.cursor = -1;
+    }
+}
+//# sourceMappingURL=UndoHistory.js.map

package/dist/core/UndoHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UndoHistory.js","sourceRoot":"","sources":["../../src/core/UndoHistory.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,WAAW;IAKvB,YAAY,OAAO,GAAuB,EAAE;QAJpC,YAAO,GAAQ,EAAE,CAAC;QAClB,WAAM,GAAG,CAAC,CAAC,CAAC;QAInB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,KAAQ;QACZ,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC3D,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED,0FAA0F;IAC1F,IAAI;QACH,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,oFAAoF;IACpF,IAAI;QACH,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,mFAAmF;IACnF,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,CAAC;IAED,6GAA6G;IAC7G,KAAK;QACJ,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAClB,CAAC;CACD"}