@futdevpro/fsm-dynamo 1.20.92 → 1.20.93

package/build-esm/_modules/game/_models/seeded-random.control-model.js

@@ -0,0 +1,261 @@
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+/**
+ * Determinisztikus, **seed-elt** veletlenszam-generator mentheto allapottal.
+ *
+ * **Miert letezik:** a `DyFM_Random` `Math.random()`-ra epul — gyors es kenyelmes, de
+ * NEM reprodukalhato es nincs allapota. A flotta harom jateka ezert epitett maganak sajat
+ * PRNG-t (`sm-random.service.ts`, `random-seed.service.ts`, Portalhold `worldSeed`).
+ * Ez az osztaly az egysegesitett valtozat.
+ *
+ * **Algoritmus:** sfc32 (Small Fast Counting) — 128 bites allapot (4x32 bit), kivalo
+ * statisztikai minoseg, gyors, es az allapota trivialisan serializalhato. A string-seedet
+ * cyrb128 hash-eli 4x32 bitre, tehat `'my-world-seed'` es `42` egyarant ervenyes seed.
+ *
+ * **Mire jo (a jatekon tul):**
+ * - reprodukalhato vilag-generalas es mentheto RNG-allapot,
+ * - **determinisztikus e2e/QA** — ugyanaz a seed ugyanazt a jatekmenetet adja,
+ * - perf-osszemeres azonos bemeneten,
+ * - mock-adat es teszt-fixture stabil generalasa.
+ *
+ * **Hasznalat:**
+ * ```typescript
+ * const rng = DyFM_SeededRandom_ControlModel.fromSeed('world-42');
+ * const damage: number = rng.nextInt(5, 15);
+ * const loot = rng.getRandomWeighted([
+ *   { chance: 0.7, result: 'common' },
+ *   { chance: 0.3, result: 'rare' },
+ * ]);
+ *
+ * // mentes
+ * save.rngState = rng.getState();
+ *
+ * // betoltes — a sorozat ott folytatodik, ahol abbamaradt
+ * const restored = DyFM_SeededRandom_ControlModel.fromState(save.rngState);
+ * ```
+ *
+ * **Fontos:** ket kulon instance NEM befolyasolja egymast; ha determinisztikus alrendszereket
+ * akarsz (pl. vilag-generalas kulon a harci dobasoktol), adj mindegyiknek sajat instance-ot.
+ */
+export class DyFM_SeededRandom_ControlModel {
+    /** 2^32 — a 32 bites egeszek normalizalasahoz. */
+    static uint32Range = 4294967296;
+    /** sfc32 allapot-szo #1. */
+    a;
+    /** sfc32 allapot-szo #2. */
+    b;
+    /** sfc32 allapot-szo #3. */
+    c;
+    /** sfc32 counter-szo. */
+    d;
+    /**
+     * Kozvetlen allapotbol epit. A tipikus belepesi pont a `fromSeed()` / `fromState()`
+     * statikus factory.
+     */
+    constructor(state) {
+        if (!state || typeof state.a !== 'number' || typeof state.b !== 'number'
+            || typeof state.c !== 'number' || typeof state.d !== 'number') {
+            throw new DyFM_Error({
+                errorCode: 'DYFM-SEEDED-RANDOM-001',
+                message: 'DyFM_SeededRandom_ControlModel: invalid state — all four state words must be numbers',
+                additionalContent: { state: state },
+            });
+        }
+        this.a = state.a | 0;
+        this.b = state.b | 0;
+        this.c = state.c | 0;
+        this.d = state.d | 0;
+    }
+    /**
+     * Generator letrehozasa seed-bol. A seed lehet string (pl. mentett `worldSeed`) vagy szam.
+     * Ugyanaz a seed MINDIG ugyanazt a sorozatot adja.
+     */
+    static fromSeed(seed) {
+        if (typeof seed !== 'string' && typeof seed !== 'number') {
+            throw new DyFM_Error({
+                errorCode: 'DYFM-SEEDED-RANDOM-002',
+                message: 'DyFM_SeededRandom_ControlModel.fromSeed: seed must be a string or a number',
+                additionalContent: { seed: seed },
+            });
+        }
+        return new DyFM_SeededRandom_ControlModel(this.hashSeed(String(seed)));
+    }
+    /** Generator letrehozasa korabban elmentett allapotbol (save-betoltes). */
+    static fromState(state) {
+        return new DyFM_SeededRandom_ControlModel(state);
+    }
+    /**
+     * String seed -> 4x32 bites allapot (cyrb128). Determinisztikus es jol szoro:
+     * a `'a'` es `'b'` seed teljesen kulonbozo sorozatot ad.
+     */
+    static hashSeed(seed) {
+        let h1 = 1779033703;
+        let h2 = 3144134277;
+        let h3 = 1013904242;
+        let h4 = 2773480762;
+        for (let i = 0; i < seed.length; i++) {
+            const k = seed.charCodeAt(i);
+            h1 = h2 ^ Math.imul(h1 ^ k, 597399067);
+            h2 = h3 ^ Math.imul(h2 ^ k, 2869860233);
+            h3 = h4 ^ Math.imul(h3 ^ k, 951274213);
+            h4 = h1 ^ Math.imul(h4 ^ k, 2716044179);
+        }
+        h1 = Math.imul(h3 ^ (h1 >>> 18), 597399067);
+        h2 = Math.imul(h4 ^ (h2 >>> 22), 2869860233);
+        h3 = Math.imul(h1 ^ (h3 >>> 17), 951274213);
+        h4 = Math.imul(h2 ^ (h4 >>> 19), 2716044179);
+        // a 0-allapot degeneralt lenne (az sfc32 megallna) — ezert biztositjuk hogy ne legyen csupa 0
+        return {
+            a: ((h1 ^ h2 ^ h3 ^ h4) >>> 0) || 1,
+            b: ((h2 ^ h1) >>> 0) || 2,
+            c: ((h3 ^ h1) >>> 0) || 3,
+            d: ((h4 ^ h1) >>> 0) || 4,
+        };
+    }
+    /** A generator teljes allapotanak masolata — ezt kell a save-payloadba tenni. */
+    getState() {
+        return { a: this.a, b: this.b, c: this.c, d: this.d };
+    }
+    /** Allapot visszatoltese — a sorozat innentol az elmentett ponton folytatodik. */
+    setState(state) {
+        if (!state || typeof state.a !== 'number' || typeof state.b !== 'number'
+            || typeof state.c !== 'number' || typeof state.d !== 'number') {
+            throw new DyFM_Error({
+                errorCode: 'DYFM-SEEDED-RANDOM-003',
+                message: 'DyFM_SeededRandom_ControlModel.setState: invalid state — all four state words must be numbers',
+                additionalContent: { state: state },
+            });
+        }
+        this.a = state.a | 0;
+        this.b = state.b | 0;
+        this.c = state.c | 0;
+        this.d = state.d | 0;
+    }
+    /**
+     * Fuggetlen masolat az AKTUALIS allapotrol — a klon ugyanazt a sorozatot folytatja,
+     * de a ket instance tovabbiakban nem befolyasolja egymast.
+     *
+     * Tipikus hasznalat: „mi lenne, ha" elore-szimulacio a fo-jatekmenet elrontasa nelkul.
+     */
+    clone() {
+        return new DyFM_SeededRandom_ControlModel(this.getState());
+    }
+    /**
+     * A kovetkezo veletlen lebegopontos szam a `[0, 1)` tartomanybol (sfc32 mag).
+     * Minden mas metodus erre epul.
+     */
+    nextFloat() {
+        this.a |= 0;
+        this.b |= 0;
+        this.c |= 0;
+        this.d |= 0;
+        const t = (((this.a + this.b) | 0) + this.d) | 0;
+        this.d = (this.d + 1) | 0;
+        this.a = this.b ^ (this.b >>> 9);
+        this.b = (this.c + (this.c << 3)) | 0;
+        this.c = (this.c << 21) | (this.c >>> 11);
+        this.c = (this.c + t) | 0;
+        return (t >>> 0) / DyFM_SeededRandom_ControlModel.uint32Range;
+    }
+    /**
+     * Veletlen egesz a `[min, max]` tartomanybol (mindket veg ZART) — a `DyFM_Random.getRandomInt`
+     * seedelt parja. Ha `max < min`, a ket erteket felcsereli.
+     */
+    nextInt(min, max) {
+        const low = Math.min(min, max);
+        const high = Math.max(min, max);
+        return low + Math.floor(this.nextFloat() * (high - low + 1));
+    }
+    /** A `DyFM_Random.getRandomInt` API-paritas alias — l. `nextInt`. */
+    getRandomInt(min, max) {
+        return this.nextInt(min, max);
+    }
+    /** Veletlen lebegopontos szam a `[min, max)` tartomanybol. */
+    nextRange(min, max) {
+        const low = Math.min(min, max);
+        const high = Math.max(min, max);
+        return low + this.nextFloat() * (high - low);
+    }
+    /**
+     * Veletlen logikai ertek. A `chance` a `true` valoszinusege (0..1; default 0.5).
+     */
+    nextBool(chance = 0.5) {
+        return this.nextFloat() < chance;
+    }
+    /**
+     * Veletlen elem a listabol (`null`, ha a lista ures) — a `DyFM_Random.getRandomListElement`
+     * seedelt parja.
+     */
+    getRandomListElement(list) {
+        if (!list?.length) {
+            return null;
+        }
+        return list[this.nextInt(0, list.length - 1)];
+    }
+    /**
+     * Sulyozott veletlen elem (`null`, ha a lista ures) — a `DyFM_Random.getRandomWeighted`
+     * seedelt parja.
+     *
+     * **Elteres a `DyFM_Random`-tol:** ez a valtozat NEM mutalja a bemeneti tombot
+     * (a statikus verzio helyben rendez es atirja a `chance` ertekeket).
+     */
+    getRandomWeighted(weights) {
+        if (!weights?.length) {
+            return null;
+        }
+        let chanceSum = 0;
+        weights.forEach((weight) => { chanceSum += weight.chance; });
+        if (chanceSum <= 0) {
+            return this.getRandomListElement(weights.map((weight) => weight.result));
+        }
+        const roll = this.nextFloat() * chanceSum;
+        let cumulated = 0;
+        for (let i = 0; i < weights.length; i++) {
+            cumulated += weights[i].chance;
+            if (roll < cumulated) {
+                return weights[i].result;
+            }
+        }
+        // lebegopontos kerekitesi maradek eseten az utolso elem a nyertes
+        return weights[weights.length - 1].result;
+    }
+    /**
+     * Sulyozott veletlen egesz — a `DyFM_Random.getRandomWeightedInt` seedelt parja.
+     * Ha a sulyozas nem ad talalatot, `nextInt(min, max)`-ra esik vissza.
+     */
+    getRandomWeightedInt(min, max, weights) {
+        const weighted = this.getRandomWeighted(weights);
+        if (weighted === null) {
+            return this.nextInt(min, max);
+        }
+        return weighted;
+    }
+    /**
+     * Fisher-Yates keveres — UJ tombot ad vissza, a bemenetet nem mutalja.
+     */
+    shuffle(list) {
+        if (!list?.length) {
+            return [];
+        }
+        const result = list.slice();
+        for (let i = result.length - 1; 0 < i; i--) {
+            const j = this.nextInt(0, i);
+            const swap = result[i];
+            result[i] = result[j];
+            result[j] = swap;
+        }
+        return result;
+    }
+    /**
+     * `count` darab KULONBOZO elem kivalasztasa a listabol (sorrendje veletlen).
+     * Ha `count` nagyobb a lista hosszanal, a teljes (megkevert) listat adja vissza.
+     */
+    pick(list, count) {
+        if (!list?.length || count <= 0) {
+            return [];
+        }
+        return this.shuffle(list).slice(0, Math.min(count, list.length));
+    }
+}
+Object.defineProperty(DyFM_SeededRandom_ControlModel, 'name', { value: 'DyFM_SeededRandom' });
+/** @deprecated Use DyFM_SeededRandom_ControlModel. Same constructor; no API removal. */
+export { DyFM_SeededRandom_ControlModel as DyFM_SeededRandom };

package/build-esm/_modules/game/index.js

@@ -0,0 +1,17 @@
+// ENUMS
+export * from './_enums/audio-channel.enum';
+// MODELS
+export * from './_models/audio-mixer-config.interface';
+export * from './_models/audio-mixer-settings.interface';
+export * from './_models/audio-mixer-state.interface';
+export * from './_models/audio-mixer.control-model';
+export * from './_models/audio-scale.interface';
+export * from './_models/seeded-random-state.interface';
+export * from './_models/seeded-random.control-model';
+export * from './_models/seeded-random-registry.interface';
+export * from './_models/seeded-random-registry.control-model';
+export * from './_models/flying-effect.interface';
+export * from './_models/flying-effect.control-model';
+// COLLECTIONS
+export * from './_collections/audio-mixer.util';
+export * from './_collections/audio-scale.util';