@futdevpro/fsm-dynamo 1.16.29 → 1.16.31

package/src/_modules/game/_collections/audio-mixer.util.ts

@@ -0,0 +1,143 @@
+
+
+import { DyFM_AudioChannel } from '../_enums/audio-channel.enum';
+import { DyFM_AudioMixer_Settings } from '../_models/audio-mixer-settings.interface';
+
+
+/**
+ * Statikus util a jatek-audio mixer beallitasaihoz.
+ *
+ * Rendereles-agnosztikus es platform-fuggetlen: NINCS benne DOM, Web Audio, Angular vagy Node
+ * fuggoseg — a tenyleges lejatszast az `@futdevpro/ngx-dynamo` game-modulja (vagy a projekt sajat
+ * motorja) vegzi, ez csak a **modell + szamitas**.
+ *
+ * **Hasznalat:**
+ * ```typescript
+ * const settings: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.merge(loadedFromSave);
+ * const volume: number = DyFM_AudioMixer_Util.getEffectiveVolume(settings, DyFM_AudioChannel.music);
+ * audioElement.volume = volume;
+ * ```
+ */
+export class DyFM_AudioMixer_Util {
+
+  /** Alapertelmezett hangero minden csatornara (0..1). */
+  private static readonly defaultVolume: number = 0.8;
+
+  /**
+   * Az alapertelmezett mixer-beallitas. Minden hivas UJ objektumot ad vissza, hogy a
+   * hivo szabadon mutalhassa (nincs megosztott referencia).
+   */
+  static getDefaults(): DyFM_AudioMixer_Settings {
+    return {
+      master: this.defaultVolume,
+      music: this.defaultVolume,
+      ambience: this.defaultVolume,
+      effects: this.defaultVolume,
+      muted: false,
+    };
+  }
+
+  /**
+   * Egy hangero-erteket a 0..1 tartomanyba szorit. A nem-szamokat (NaN, undefined, null,
+   * nem-szam tipus) a `fallback`-re cseréli — igy egy serult save-payload sem tud NaN-t
+   * juttatni a lejatszoba (a `HTMLAudioElement.volume = NaN` dobna).
+   */
+  static clamp(value: number, fallback: number = DyFM_AudioMixer_Util.defaultVolume): number {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+      return fallback;
+    }
+
+    if (value < 0) {
+      return 0;
+    }
+
+    if (1 < value) {
+      return 1;
+    }
+
+    return value;
+  }
+
+  /**
+   * Reszleges (vagy hianyzo) beallitas-objektumbol teljes, ervenyes settingset allit elo:
+   * a hianyzo mezoket a defaultbol veszi, a meglevoket 0..1-re szoritja.
+   *
+   * **Ez a migracios biztositek:** egy regi save-payload, ami meg nem ismerte az `ambience`
+   * csatornat, igy is betoltheto marad.
+   */
+  static merge(partial?: Partial<DyFM_AudioMixer_Settings> | null): DyFM_AudioMixer_Settings {
+    const defaults: DyFM_AudioMixer_Settings = this.getDefaults();
+
+    if (!partial) {
+      return defaults;
+    }
+
+    return {
+      master: this.clamp(partial.master ?? defaults.master, defaults.master),
+      music: this.clamp(partial.music ?? defaults.music, defaults.music),
+      ambience: this.clamp(partial.ambience ?? defaults.ambience, defaults.ambience),
+      effects: this.clamp(partial.effects ?? defaults.effects, defaults.effects),
+      muted: partial.muted === true,
+    };
+  }
+
+  /**
+   * Egy csatorna EFFEKTIV hangereje: a csatorna sajat erteke szorozva a master-rel.
+   * Nemitas (`muted`) eseten mindig 0. A `master` csatornara a sajat erteket adja vissza
+   * (nem negyzetre emelve).
+   */
+  static getEffectiveVolume(
+    settings: DyFM_AudioMixer_Settings,
+    channel: DyFM_AudioChannel,
+  ): number {
+    const safe: DyFM_AudioMixer_Settings = this.merge(settings);
+
+    if (safe.muted) {
+      return 0;
+    }
+
+    if (channel === DyFM_AudioChannel.master) {
+      return safe.master;
+    }
+
+    return this.clamp(safe[channel] * safe.master);
+  }
+
+  /**
+   * Egy csatorna hangerejenek beallitasa — UJ settings-objektumot ad vissza (immutable update),
+   * hogy signal-/state-alapu tarolokban is biztonsagos legyen.
+   */
+  static withChannelVolume(
+    settings: DyFM_AudioMixer_Settings,
+    channel: DyFM_AudioChannel,
+    volume: number,
+  ): DyFM_AudioMixer_Settings {
+    const next: DyFM_AudioMixer_Settings = this.merge(settings);
+    next[channel] = this.clamp(volume);
+
+    return next;
+  }
+
+  /** Nemitas beallitasa — UJ settings-objektumot ad vissza (immutable update). */
+  static withMuted(
+    settings: DyFM_AudioMixer_Settings,
+    muted: boolean,
+  ): DyFM_AudioMixer_Settings {
+    const next: DyFM_AudioMixer_Settings = this.merge(settings);
+    next.muted = muted === true;
+
+    return next;
+  }
+
+  /** Ket beallitas ertek szerinti egyezese (mentes-szukseg / change-detection dontesehez). */
+  static isEqual(a: DyFM_AudioMixer_Settings, b: DyFM_AudioMixer_Settings): boolean {
+    const left: DyFM_AudioMixer_Settings = this.merge(a);
+    const right: DyFM_AudioMixer_Settings = this.merge(b);
+
+    return left.master === right.master
+      && left.music === right.music
+      && left.ambience === right.ambience
+      && left.effects === right.effects
+      && left.muted === right.muted;
+  }
+}

package/src/_modules/game/_enums/audio-channel.enum.ts

@@ -0,0 +1,18 @@
+
+
+/**
+ * A jatek-audio mixer csatornai.
+ *
+ * A flotta NEGY jateka egymastol fuggetlenul ugyanezt a negy csatornat vezette be
+ * (Prototyper: Room Cats / Cell Stage / Portalhold, plusz a Hero Coordinator) — ez az
+ * enum a kanonikus nevezektan, amire mindegyik ratert.
+ *
+ * A `master` NEM onallo hangsav: minden csatorna effektiv hangereje a sajat erteke
+ * SZOROZVA a master-rel (lasd `DyFM_AudioMixer_Util.getEffectiveVolume`).
+ */
+export enum DyFM_AudioChannel {
+  master = 'master',
+  music = 'music',
+  ambience = 'ambience',
+  effects = 'effects',
+}

package/src/_modules/game/_models/audio-mixer-settings.interface.ts

@@ -0,0 +1,28 @@
+
+
+/**
+ * A jatek-audio mixer beallitasai — csatornankent 0..1 hangero + globalis nemitas.
+ *
+ * **Miert bedrock:** ez az interfesz a flottaban NEGY helyen elt egymastol fuggetlenul,
+ * karakterre azonos alakban (`pcr-audio-settings.interface.ts`, `pcs-audio-settings.interface.ts`,
+ * `pg-audio-settings.interface.ts` + a Hero Coordinator sajat audio-service-e). Ez a kanonikus alak.
+ *
+ * **Mentheto:** tisztan JSON-serializalhato, tehat a jatek save-payload resze lehet.
+ * Reszleges/legacy payload-bol a `DyFM_AudioMixer_Util.merge()` allit elo teljes settingset.
+ */
+export interface DyFM_AudioMixer_Settings {
+  /** Fo-hangero (0..1) — minden csatornara szorzodik. */
+  master: number;
+
+  /** Zene-csatorna hangereje (0..1). */
+  music: number;
+
+  /** Kornyezeti hangok (ambience) csatorna hangereje (0..1). */
+  ambience: number;
+
+  /** Effekt-hangok csatorna hangereje (0..1). */
+  effects: number;
+
+  /** Globalis nemitas — ha true, minden effektiv hangero 0. */
+  muted: boolean;
+}

package/src/_modules/game/_models/seeded-random-state.interface.ts

@@ -0,0 +1,21 @@
+
+
+/**
+ * A `DyFM_SeededRandom` teljes belso allapota — 4 db 32-bites egesz (sfc32).
+ *
+ * Tisztan JSON-serializalhato, tehat **a jatek save-payload resze lehet**: a mentes utan
+ * visszatoltve a veletlen-sorozat PONTOSAN ott folytatodik, ahol abbamaradt.
+ */
+export interface DyFM_SeededRandom_State {
+  /** sfc32 allapot-szo #1. */
+  a: number;
+
+  /** sfc32 allapot-szo #2. */
+  b: number;
+
+  /** sfc32 allapot-szo #3. */
+  c: number;
+
+  /** sfc32 counter-szo. */
+  d: number;
+}

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

@@ -0,0 +1,290 @@
+
+import { DyFM_SeededRandom } from './seeded-random.control-model';
+import { DyFM_SeededRandom_State } from './seeded-random-state.interface';
+
+
+describe('DyFM_SeededRandom', (): void => {
+
+  describe('determinizmus', (): void => {
+
+    it('ugyanaz a string-seed ugyanazt a sorozatot adja', (): void => {
+      const first: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('world-42');
+      const second: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('world-42');
+
+      const firstRun: number[] = [];
+      const secondRun: number[] = [];
+
+      for (let i = 0; i < 50; i++) {
+        firstRun.push(first.nextFloat());
+        secondRun.push(second.nextFloat());
+      }
+
+      expect(firstRun).toEqual(secondRun);
+    });
+
+    it('ugyanaz a szam-seed ugyanazt a sorozatot adja', (): void => {
+      const first: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed(1234);
+      const second: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed(1234);
+
+      expect(first.nextInt(0, 1000000)).toBe(second.nextInt(0, 1000000));
+    });
+
+    it('kulonbozo seed kulonbozo sorozatot ad', (): void => {
+      const first: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('a');
+      const second: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('b');
+
+      const firstRun: number[] = [];
+      const secondRun: number[] = [];
+
+      for (let i = 0; i < 20; i++) {
+        firstRun.push(first.nextFloat());
+        secondRun.push(second.nextFloat());
+      }
+
+      expect(firstRun).not.toEqual(secondRun);
+    });
+
+    it('ket fuggetlen instance nem befolyasolja egymast', (): void => {
+      const first: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('shared');
+      const second: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('shared');
+
+      first.nextFloat();
+      first.nextFloat();
+      first.nextFloat();
+
+      const untouched: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('shared');
+
+      expect(second.nextFloat()).toBe(untouched.nextFloat());
+    });
+  });
+
+  describe('allapot mentese es visszatoltese', (): void => {
+
+    it('setState(getState()) utan a sorozat FOLYTATODIK, nem ujraindul', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('save-test');
+
+      rng.nextFloat();
+      rng.nextFloat();
+
+      const snapshot: DyFM_SeededRandom_State = rng.getState();
+      const expected: number[] = [rng.nextFloat(), rng.nextFloat(), rng.nextFloat()];
+
+      const restored: DyFM_SeededRandom = DyFM_SeededRandom.fromState(snapshot);
+      const actual: number[] = [restored.nextFloat(), restored.nextFloat(), restored.nextFloat()];
+
+      expect(actual).toEqual(expected);
+    });
+
+    it('a getState() masolatot ad — a kesobbi huzasok nem irjak at', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('copy-test');
+      const snapshot: DyFM_SeededRandom_State = rng.getState();
+      const before: DyFM_SeededRandom_State = { a: snapshot.a, b: snapshot.b, c: snapshot.c, d: snapshot.d };
+
+      rng.nextFloat();
+      rng.nextFloat();
+
+      expect(snapshot).toEqual(before);
+    });
+
+    it('az allapot JSON-korutjat tuleli (save-payload szimulacio)', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('json-test');
+      rng.nextFloat();
+
+      const serialized: string = JSON.stringify(rng.getState());
+      const parsed: DyFM_SeededRandom_State = JSON.parse(serialized);
+      const restored: DyFM_SeededRandom = DyFM_SeededRandom.fromState(parsed);
+
+      expect(restored.nextFloat()).toBe(DyFM_SeededRandom.fromState(rng.getState()).nextFloat());
+    });
+
+    it('a clone() ugyanonnan folytatja, de fuggetlenne valik', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('clone-test');
+      rng.nextFloat();
+
+      const clone: DyFM_SeededRandom = rng.clone();
+      const fromClone: number = clone.nextFloat();
+      const fromOriginal: number = rng.nextFloat();
+
+      expect(fromClone).toBe(fromOriginal);
+
+      clone.nextFloat();
+      clone.nextFloat();
+
+      expect(rng.nextFloat()).not.toBe(clone.nextFloat());
+    });
+
+    it('ervenytelen allapotra DyFM_Error-t dob', (): void => {
+      expect((): DyFM_SeededRandom => DyFM_SeededRandom.fromState(null)).toThrow();
+      expect((): DyFM_SeededRandom => DyFM_SeededRandom.fromState({ a: 1, b: 2, c: 3, d: undefined })).toThrow();
+    });
+
+    it('ervenytelen seed-tipusra DyFM_Error-t dob', (): void => {
+      expect((): DyFM_SeededRandom => DyFM_SeededRandom.fromSeed(undefined)).toThrow();
+    });
+  });
+
+  describe('tartomanyok es eloszlas', (): void => {
+
+    it('nextFloat mindig [0, 1) kozott van', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('range-test');
+
+      for (let i = 0; i < 10000; i++) {
+        const value: number = rng.nextFloat();
+        expect(value).toBeGreaterThanOrEqual(0);
+        expect(value).toBeLessThan(1);
+      }
+    });
+
+    it('nextInt a zart [min, max] tartomanyban marad es minden erteket eltalal', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('int-test');
+      const seen: Set<number> = new Set<number>();
+
+      for (let i = 0; i < 10000; i++) {
+        const value: number = rng.nextInt(1, 6);
+        expect(value).toBeGreaterThanOrEqual(1);
+        expect(value).toBeLessThanOrEqual(6);
+        seen.add(value);
+      }
+
+      expect(seen.size).toBe(6);
+    });
+
+    it('nextInt felcserelt hatarokat is kezel', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('swap-test');
+      const value: number = rng.nextInt(10, 2);
+
+      expect(value).toBeGreaterThanOrEqual(2);
+      expect(value).toBeLessThanOrEqual(10);
+    });
+
+    it('nextRange a [min, max) tartomanyban marad', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('float-range');
+
+      for (let i = 0; i < 1000; i++) {
+        const value: number = rng.nextRange(-5, 5);
+        expect(value).toBeGreaterThanOrEqual(-5);
+        expect(value).toBeLessThan(5);
+      }
+    });
+
+    it('nextBool(0) mindig false, nextBool(1) mindig true', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('bool-test');
+
+      for (let i = 0; i < 100; i++) {
+        expect(rng.nextBool(0)).toBe(false);
+        expect(rng.nextBool(1)).toBe(true);
+      }
+    });
+  });
+
+  describe('DyFM_Random API-paritas', (): void => {
+
+    it('getRandomInt a nextInt aliasa', (): void => {
+      const first: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('alias-test');
+      const second: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('alias-test');
+
+      expect(first.getRandomInt(1, 100)).toBe(second.nextInt(1, 100));
+    });
+
+    it('getRandomListElement ures listara null-t ad', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('empty-test');
+
+      expect(rng.getRandomListElement([])).toBeNull();
+      expect(rng.getRandomListElement(null)).toBeNull();
+    });
+
+    it('getRandomListElement mindig a listabol valaszt', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('list-test');
+      const list: string[] = ['a', 'b', 'c'];
+
+      for (let i = 0; i < 500; i++) {
+        expect(list).toContain(rng.getRandomListElement(list));
+      }
+    });
+
+    it('getRandomWeighted NEM mutalja a bemeneti tombot', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('weight-mutate');
+      const weights = [
+        { chance: 0.2, result: 'low' },
+        { chance: 0.8, result: 'high' },
+      ];
+      const before: string = JSON.stringify(weights);
+
+      rng.getRandomWeighted(weights);
+
+      expect(JSON.stringify(weights)).toBe(before);
+    });
+
+    it('getRandomWeighted a sulyoknak megfeleloen oszlik el', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('weight-dist');
+      let highCount = 0;
+
+      for (let i = 0; i < 10000; i++) {
+        if (rng.getRandomWeighted([
+          { chance: 0.1, result: 'low' },
+          { chance: 0.9, result: 'high' },
+        ]) === 'high') {
+          highCount++;
+        }
+      }
+
+      expect(highCount).toBeGreaterThan(8500);
+      expect(highCount).toBeLessThan(9500);
+    });
+
+    it('getRandomWeighted ures listara null-t ad', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('weight-empty');
+
+      expect(rng.getRandomWeighted([])).toBeNull();
+    });
+
+    it('getRandomWeightedInt visszaesik nextInt-re, ha nincs suly', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('weight-int');
+      const value: number = rng.getRandomWeightedInt(5, 10, []);
+
+      expect(value).toBeGreaterThanOrEqual(5);
+      expect(value).toBeLessThanOrEqual(10);
+    });
+  });
+
+  describe('shuffle es pick', (): void => {
+
+    it('a shuffle NEM mutalja a bemenetet es megorzi az elemeket', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('shuffle-test');
+      const source: number[] = [1, 2, 3, 4, 5, 6, 7, 8];
+      const shuffled: number[] = rng.shuffle(source);
+
+      expect(source).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+      expect(shuffled.slice().sort((a: number, b: number): number => a - b)).toEqual(source);
+    });
+
+    it('a shuffle determinisztikus azonos seeddel', (): void => {
+      const first: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('shuffle-det');
+      const second: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('shuffle-det');
+      const source: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+      expect(first.shuffle(source)).toEqual(second.shuffle(source));
+    });
+
+    it('a pick kulonbozo elemeket ad, a keresnel nem tobbet', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('pick-test');
+      const picked: number[] = rng.pick([1, 2, 3, 4, 5], 3);
+
+      expect(picked.length).toBe(3);
+      expect(new Set<number>(picked).size).toBe(3);
+    });
+
+    it('a pick a teljes listat adja, ha count nagyobb a hossznal', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('pick-over');
+
+      expect(rng.pick([1, 2], 10).length).toBe(2);
+    });
+
+    it('a pick ures listara / nem-pozitiv count-ra ures tombot ad', (): void => {
+      const rng: DyFM_SeededRandom = DyFM_SeededRandom.fromSeed('pick-empty');
+
+      expect(rng.pick([], 3)).toEqual([]);
+      expect(rng.pick([1, 2, 3], 0)).toEqual([]);
+    });
+  });
+});