@futdevpro/fsm-dynamo 1.16.30 → 1.16.31

package/src/_modules/game/_models/seeded-random.control-model.ts

@@ -0,0 +1,311 @@
+
+
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+import { DyFM_RandomWeight } from '../../../_models/interfaces/random-weight.interface';
+
+import { DyFM_SeededRandom_State } from './seeded-random-state.interface';
+
+
+/**
+ * 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.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.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 {
+
+  /** 2^32 — a 32 bites egeszek normalizalasahoz. */
+  private static readonly uint32Range: number = 4294967296;
+
+  /** sfc32 allapot-szo #1. */
+  private a: number;
+
+  /** sfc32 allapot-szo #2. */
+  private b: number;
+
+  /** sfc32 allapot-szo #3. */
+  private c: number;
+
+  /** sfc32 counter-szo. */
+  private d: number;
+
+  /**
+   * Kozvetlen allapotbol epit. A tipikus belepesi pont a `fromSeed()` / `fromState()`
+   * statikus factory.
+   */
+  constructor(state: DyFM_SeededRandom_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: 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: string | number): DyFM_SeededRandom {
+    if (typeof seed !== 'string' && typeof seed !== 'number') {
+      throw new DyFM_Error({
+        errorCode: 'DYFM-SEEDED-RANDOM-002',
+        message: 'DyFM_SeededRandom.fromSeed: seed must be a string or a number',
+        additionalContent: { seed: seed },
+      });
+    }
+
+    return new DyFM_SeededRandom(this.hashSeed(String(seed)));
+  }
+
+  /** Generator letrehozasa korabban elmentett allapotbol (save-betoltes). */
+  static fromState(state: DyFM_SeededRandom_State): DyFM_SeededRandom {
+    return new DyFM_SeededRandom(state);
+  }
+
+  /**
+   * String seed -> 4x32 bites allapot (cyrb128). Determinisztikus es jol szoro:
+   * a `'a'` es `'b'` seed teljesen kulonbozo sorozatot ad.
+   */
+  private static hashSeed(seed: string): DyFM_SeededRandom_State {
+    let h1: number = 1779033703;
+    let h2: number = 3144134277;
+    let h3: number = 1013904242;
+    let h4: number = 2773480762;
+
+    for (let i = 0; i < seed.length; i++) {
+      const k: number = 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(): DyFM_SeededRandom_State {
+    return { a: this.a, b: this.b, c: this.c, d: this.d };
+  }
+
+  /** Allapot visszatoltese — a sorozat innentol az elmentett ponton folytatodik. */
+  setState(state: DyFM_SeededRandom_State): void {
+    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.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(): DyFM_SeededRandom {
+    return new DyFM_SeededRandom(this.getState());
+  }
+
+  /**
+   * A kovetkezo veletlen lebegopontos szam a `[0, 1)` tartomanybol (sfc32 mag).
+   * Minden mas metodus erre epul.
+   */
+  nextFloat(): number {
+    this.a |= 0;
+    this.b |= 0;
+    this.c |= 0;
+    this.d |= 0;
+
+    const t: number = (((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.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: number, max: number): number {
+    const low: number = Math.min(min, max);
+    const high: number = Math.max(min, max);
+
+    return low + Math.floor(this.nextFloat() * (high - low + 1));
+  }
+
+  /** A `DyFM_Random.getRandomInt` API-paritas alias — l. `nextInt`. */
+  getRandomInt(min: number, max: number): number {
+    return this.nextInt(min, max);
+  }
+
+  /** Veletlen lebegopontos szam a `[min, max)` tartomanybol. */
+  nextRange(min: number, max: number): number {
+    const low: number = Math.min(min, max);
+    const high: number = 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: number = 0.5): boolean {
+    return this.nextFloat() < chance;
+  }
+
+  /**
+   * Veletlen elem a listabol (`null`, ha a lista ures) — a `DyFM_Random.getRandomListElement`
+   * seedelt parja.
+   */
+  getRandomListElement<T>(list: T[]): T | null {
+    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<T>(weights: DyFM_RandomWeight<T>[]): T | null {
+    if (!weights?.length) {
+      return null;
+    }
+
+    let chanceSum = 0;
+    weights.forEach((weight): void => { chanceSum += weight.chance; });
+
+    if (chanceSum <= 0) {
+      return this.getRandomListElement(weights.map((weight): T => weight.result));
+    }
+
+    const roll: number = 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: number, max: number, weights: DyFM_RandomWeight<number>[]): number {
+    const weighted: number | null = 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<T>(list: T[]): T[] {
+    if (!list?.length) {
+      return [];
+    }
+
+    const result: T[] = list.slice();
+
+    for (let i = result.length - 1; 0 < i; i--) {
+      const j: number = this.nextInt(0, i);
+      const swap: T = 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<T>(list: T[], count: number): T[] {
+    if (!list?.length || count <= 0) {
+      return [];
+    }
+
+    return this.shuffle(list).slice(0, Math.min(count, list.length));
+  }
+}

package/src/_modules/game/index.ts

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