@futdevpro/fsm-dynamo 1.16.31 → 1.16.33

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

@@ -0,0 +1,129 @@
+
+
+import { DyFM_AudioScale } from '../_models/audio-scale.interface';
+
+
+/**
+ * Skala-konverziok az audio-mixerhez: a projekt sajat szamabrazolasa (pl. `0-100` egesz)
+ * es a lejatszo API-k altal vart `0..1` kozott.
+ *
+ * **Miert statikus util:** nincs allapota — tiszta fuggvenyek, a `DyFM_Math` mintajara.
+ *
+ * **Hasznalat:**
+ * ```typescript
+ * const percent = DyFM_AudioScale_Util.getPercentScale();
+ * DyFM_AudioScale_Util.toUnit(72, percent);      // 0.72  -> ezt varja a HTMLAudio / GainNode
+ * DyFM_AudioScale_Util.fromUnit(0.725, percent); // 73    -> ezt tarolja / mutatja a projekt
+ * ```
+ */
+export class DyFM_AudioScale_Util {
+
+  /** Alapertelmezett hangero-arany (a skala maximumanak hanyada), ha nincs jobb ertek. */
+  static readonly defaultRatio: number = 0.8;
+
+  /**
+   * A `0..1` lebegopontos skala — a Prototyper prototipusai (es a round-1
+   * `DyFM_AudioMixer_Settings`) ezt hasznaljak. Minden hivas UJ objektumot ad vissza, hogy a
+   * hivo szabadon mutalhassa.
+   */
+  static getUnitScale(): DyFM_AudioScale {
+    return {
+      max: 1,
+      integer: false,
+    };
+  }
+
+  /**
+   * A `0-100` egesz skala — a Hero Coordinator ezt tarolja a localStorage-ban
+   * (`clampVolume` = `Math.round`). Minden hivas UJ objektumot ad vissza.
+   */
+  static getPercentScale(): DyFM_AudioScale {
+    return {
+      max: 100,
+      integer: true,
+    };
+  }
+
+  /**
+   * Sajat skalan levo erteket `0..1`-re normalizal, es a tartomanyba szorit.
+   * Ervenytelen bemenet (NaN, nem-szam, null/undefined) eseten a `fallbackUnit`-ot adja —
+   * igy egy serult save-payload sem tud NaN-t juttatni a lejatszoba
+   * (`HTMLAudioElement.volume = NaN` dobna, a `GainNode.gain.value = NaN` elnemitana).
+   */
+  static toUnit(
+    value: number,
+    scale: DyFM_AudioScale,
+    fallbackUnit: number = DyFM_AudioScale_Util.defaultRatio,
+  ): number {
+    const max: number = this.getSafeMax(scale);
+
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+      return this.clampUnit(fallbackUnit);
+    }
+
+    return this.clampUnit(value / max);
+  }
+
+  /**
+   * `0..1` erteket a sajat skalara alakit vissza. Egesz skalanal (`integer: true`) kerekit,
+   * igy a `0-100`-as UI-nak nem kell tortszamokkal dolgoznia.
+   */
+  static fromUnit(unit: number, scale: DyFM_AudioScale): number {
+    const max: number = this.getSafeMax(scale);
+    const safeUnit: number = typeof unit !== 'number' || Number.isNaN(unit)
+      ? 0
+      : this.clampUnit(unit);
+    const scaled: number = safeUnit * max;
+
+    return scale && scale.integer === true ? Math.round(scaled) : scaled;
+  }
+
+  /**
+   * Egy erteket a sajat skala `0..max` tartomanyaba szorit (egesz skalanal kerekit is).
+   *
+   * Ervenytelen bemenetre (NaN, nem-szam) a `fallbackScaleValue`-t adja — **a sajat skalan**.
+   * Alapertelmezesben `0`; a mixer viszont a csatorna DEFAULT-jat adja at, mert egy serult
+   * mentesbol jobb a hallhato alapertek, mint a nema 0 (a felhasznalo eszre sem venne).
+   */
+  static clampToScale(
+    value: number,
+    scale: DyFM_AudioScale,
+    fallbackScaleValue: number = 0,
+  ): number {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+      const safeFallback: number = typeof fallbackScaleValue === 'number'
+        && !Number.isNaN(fallbackScaleValue)
+        ? fallbackScaleValue
+        : 0;
+
+      return this.fromUnit(this.toUnit(safeFallback, scale, 0), scale);
+    }
+
+    return this.fromUnit(this.toUnit(value, scale, 0), scale);
+  }
+
+  /** Egy `0..1` erteket a tartomanyba szorit. */
+  static clampUnit(value: number): number {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+      return 0;
+    }
+
+    if (value < 0) {
+      return 0;
+    }
+
+    return 1 < value ? 1 : value;
+  }
+
+  /**
+   * A skala maximuma vedve: a hianyzo / nem-pozitiv / NaN maximumot `1`-re cseréli, hogy a
+   * nullaval valo osztas es a NaN-terjedes kizart legyen.
+   */
+  private static getSafeMax(scale: DyFM_AudioScale): number {
+    if (!scale || typeof scale.max !== 'number' || Number.isNaN(scale.max) || scale.max <= 0) {
+      return 1;
+    }
+
+    return scale.max;
+  }
+}

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

@@ -1,11 +1,15 @@
 
 
 /**
- * A jatek-audio mixer csatornai.
+ * A jatek-audio mixer **klasszikus** csatorna-keszlete.
  *
- * 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 Prototyper HAROM prototipusa (Room Cats / Cell Stage / Portalhold) egymastol fuggetlenul
+ * ugyanezt a negy csatornat vezette be — ez az enum az o kanonikus nevezektanuk.
+ *
+ * **FIGYELEM (2026-08-06 helyesbites):** ez NEM flotta-univerzalis. A **Hero Coordinator**
+ * csatornai `master` / `music` / **`dialog`** / **`interface`**, es `0-100` egeszet tarol.
+ * Ha a projekted csatorna-keszlete elter, NE ezt az enumot hasznald, hanem a
+ * `DyFM_AudioMixer_ControlModel`-t sajat config-gal (csatorna- es skala-agnosztikus).
  *
  * A `master` NEM onallo hangsav: minden csatorna effektiv hangereje a sajat erteke
  * SZOROZVA a master-rel (lasd `DyFM_AudioMixer_Util.getEffectiveVolume`).

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

@@ -0,0 +1,45 @@
+
+
+import { DyFM_AudioScale } from './audio-scale.interface';
+
+
+/**
+ * Egy jatek audio-mixerenek **deklaracioja**: milyen csatornai vannak, milyen skalan, es mik
+ * az alapertelmezesek.
+ *
+ * **Miert nem fix csatorna-keszlet:** a `DyFM_AudioMixer_Settings` (round-1) negy fix mezot ad
+ * (`music` / `ambience` / `effects`), ami a Prototyper harom prototipusara igaz — de a Hero
+ * Coordinator csatornai `music` / `dialog` / `interface`. Egy fix alak ott csatorna-vesztessel
+ * jarna. A config-alapu modell mindkettot kiszolgalja, es a projekt sajat csatorna-enumja
+ * marad a nevek forrasa.
+ *
+ * **A `master` nem szerepel a `channels` listaban** — kulon kezelt, mert minden csatornara
+ * szorzodik.
+ *
+ * **Hasznalat:**
+ * ```typescript
+ * const mixer = new DyFM_AudioMixer_ControlModel({
+ *   channels: ['music', 'dialog', 'interface'],
+ *   scale: DyFM_AudioScale_Util.getPercentScale(),
+ *   defaults: { music: 36, dialog: 84, interface: 68 },
+ *   defaultMaster: 72,
+ * });
+ * ```
+ */
+export interface DyFM_AudioMixer_Config {
+
+  /** A projekt sajat csatorna-nevei. A `master` NEM tartozik ide (kulon kezelt). */
+  channels: string[];
+
+  /** A csatorna-ertekek skalaja (`unit` = 0..1, `percent` = 0-100 egesz). */
+  scale: DyFM_AudioScale;
+
+  /** Alapertelmezett csatorna-ertekek a **sajat skalan**. A fel nem soroltak a `defaultChannelVolume`-ot kapjak. */
+  defaults?: Record<string, number>;
+
+  /** Alapertelmezett master-ertek a **sajat skalan**. Default: a skala maximumanak 80%-a. */
+  defaultMaster?: number;
+
+  /** Alapertelmezes a `defaults`-ban fel nem sorolt csatornakra (**sajat skala**). Default: a maximum 80%-a. */
+  defaultChannelVolume?: number;
+}

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

@@ -0,0 +1,23 @@
+
+
+/**
+ * Egy audio-mixer **allapota** — a projekt sajat skalajan tarolva, JSON-serializalhatoan.
+ *
+ * A `channels` nyitott rekord: a kulcsok a `DyFM_AudioMixer_Config.channels` nevei. Igy egy
+ * jatek annyi es olyan nevu csatornat hasznalhat, amennyit akar, a bedrock-modell valtoztatasa
+ * nelkul.
+ *
+ * **Mentheto:** ez az alak kerulhet kozvetlenul a save-payloadba vagy a localStorage-ba.
+ * Hianyos/regi payloadbol a `DyFM_AudioMixer_ControlModel.merge()` allit elo teljes allapotot.
+ */
+export interface DyFM_AudioMixer_State {
+
+  /** Fo-hangero a **sajat skalan** — minden csatornara szorzodik. */
+  master: number;
+
+  /** Csatorna-nev -> hangero a **sajat skalan**. */
+  channels: Record<string, number>;
+
+  /** Globalis nemitas — ha `true`, minden effektiv hangero 0. */
+  muted: boolean;
+}

package/src/_modules/game/_models/audio-mixer.control-model.spec.ts

@@ -0,0 +1,306 @@
+
+import { DyFM_AudioMixer_Settings } from './audio-mixer-settings.interface';
+import { DyFM_AudioMixer_State } from './audio-mixer-state.interface';
+import { DyFM_AudioMixer_ControlModel } from './audio-mixer.control-model';
+
+
+/** A Hero Coordinator VALODI mixer-alakja (0-100 egesz, dialog + interface csatorna). */
+function createHeroCoordinatorMixer(): DyFM_AudioMixer_ControlModel {
+  return DyFM_AudioMixer_ControlModel.createPercent(
+    ['music', 'dialog', 'interface'],
+    { music: 36, dialog: 84, interface: 68 },
+    72,
+  );
+}
+
+
+describe('DyFM_AudioMixer_ControlModel', (): void => {
+
+  describe('konstruktor-validacio', (): void => {
+
+    it('ures csatorna-listara dob', (): void => {
+      expect((): void => {
+        new DyFM_AudioMixer_ControlModel({ channels: [], scale: { max: 1, integer: false } });
+      }).toThrow();
+    });
+
+    it('a fenntartott "master" csatorna-nevre dob', (): void => {
+      expect((): void => {
+        DyFM_AudioMixer_ControlModel.createPercent(['master', 'music']);
+      }).toThrow();
+    });
+
+    it('duplikalt csatorna-nevre dob', (): void => {
+      expect((): void => {
+        DyFM_AudioMixer_ControlModel.createPercent(['music', 'music']);
+      }).toThrow();
+    });
+
+    it('a config masolatat tarolja (a kesobbi mutacio nem hat vissza)', (): void => {
+      const channels: string[] = ['music', 'dialog'];
+      const mixer: DyFM_AudioMixer_ControlModel = DyFM_AudioMixer_ControlModel.createPercent(channels);
+
+      channels.push('interface');
+
+      expect(mixer.getChannels()).toEqual(['music', 'dialog']);
+    });
+  });
+
+  describe('getDefaults', (): void => {
+
+    it('a config szerinti alapertekeket adja a SAJAT skalan', (): void => {
+      const state: DyFM_AudioMixer_State = createHeroCoordinatorMixer().getDefaults();
+
+      expect(state.master).toBe(72);
+      expect(state.channels['music']).toBe(36);
+      expect(state.channels['dialog']).toBe(84);
+      expect(state.channels['interface']).toBe(68);
+      expect(state.muted).toBe(false);
+    });
+
+    it('a fel nem sorolt csatornanak kozos default jut', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = DyFM_AudioMixer_ControlModel.createPercent(
+        ['music', 'ui'],
+        { music: 20 },
+        90,
+      );
+      const state: DyFM_AudioMixer_State = mixer.getDefaults();
+
+      expect(state.channels['music']).toBe(20);
+      expect(state.channels['ui']).toBe(80);
+    });
+
+    it('minden hivas UJ objektumot ad (nincs megosztott referencia)', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const first: DyFM_AudioMixer_State = mixer.getDefaults();
+      const second: DyFM_AudioMixer_State = mixer.getDefaults();
+
+      first.channels['music'] = 1;
+
+      expect(second.channels['music']).toBe(36);
+    });
+  });
+
+  describe('merge', (): void => {
+
+    it('hianyzo allapotbol a defaultot adja', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+
+      expect(mixer.merge(null)).toEqual(mixer.getDefaults());
+      expect(mixer.merge(undefined)).toEqual(mixer.getDefaults());
+    });
+
+    it('reszleges payloadot kiegeszit, a meglevot megtartja', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const merged: DyFM_AudioMixer_State = mixer.merge({ channels: { dialog: 10 } });
+
+      expect(merged.channels['dialog']).toBe(10);
+      expect(merged.channels['music']).toBe(36);
+      expect(merged.master).toBe(72);
+    });
+
+    it('a NEM deklaralt csatornat eldobja (eltavolitott csatorna nem szivarog vissza)', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const merged: DyFM_AudioMixer_State = mixer.merge({
+        channels: { music: 50, legacyAmbience: 99 } as Record<string, number>,
+      });
+
+      expect(merged.channels['music']).toBe(50);
+      expect(merged.channels['legacyAmbience']).toBeUndefined();
+    });
+
+    it('a tartomanyon kivuli erteket beszoritja', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const merged: DyFM_AudioMixer_State = mixer.merge({
+        master: 500,
+        channels: { music: -20 },
+      });
+
+      expect(merged.master).toBe(100);
+      expect(merged.channels['music']).toBe(0);
+    });
+
+    it('a SERULT (NaN) erteket a csatorna DEFAULT-jara viszi, nem 0-ra (nem nemit el csendben)', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const merged: DyFM_AudioMixer_State = mixer.merge({
+        master: NaN,
+        channels: { dialog: NaN, interface: 'loud' as unknown as number },
+      });
+
+      expect(merged.master).toBe(72);
+      expect(merged.channels['dialog']).toBe(84);
+      expect(merged.channels['interface']).toBe(68);
+    });
+  });
+
+  describe('getEffectiveVolume', (): void => {
+
+    it('MINDIG 0..1-et ad, fuggetlenul a 0-100 tarolastol', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const state: DyFM_AudioMixer_State = mixer.getDefaults();
+
+      expect(mixer.getEffectiveVolume(state, 'interface')).toBeCloseTo(0.68 * 0.72, 10);
+      expect(mixer.getEffectiveVolume(state, 'dialog')).toBeCloseTo(0.84 * 0.72, 10);
+    });
+
+    it('a "master" nevre a master sajat erteket adja (nem negyzetre emelve)', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const state: DyFM_AudioMixer_State = mixer.getDefaults();
+
+      expect(mixer.getEffectiveVolume(state, 'master')).toBeCloseTo(0.72, 10);
+    });
+
+    it('nemitva minden csatorna 0', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const state: DyFM_AudioMixer_State = mixer.withMuted(mixer.getDefaults(), true);
+
+      expect(mixer.getEffectiveVolume(state, 'music')).toBe(0);
+      expect(mixer.getEffectiveVolume(state, 'master')).toBe(0);
+    });
+
+    it('ismeretlen csatornara DOB (elgepeles nem nemul el csendben)', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const state: DyFM_AudioMixer_State = mixer.getDefaults();
+
+      expect((): void => {
+        mixer.getEffectiveVolume(state, 'ambience');
+      }).toThrow();
+    });
+
+    it('serult allapotbol sem ad NaN-t', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const broken: DyFM_AudioMixer_State = {
+        master: NaN,
+        channels: { music: NaN, dialog: NaN, interface: NaN },
+        muted: false,
+      };
+
+      expect(Number.isNaN(mixer.getEffectiveVolume(broken, 'music'))).toBe(false);
+    });
+  });
+
+  describe('immutable update-ek', (): void => {
+
+    it('withChannelVolume UJ objektumot ad, az eredetit nem valtoztatja', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const state: DyFM_AudioMixer_State = mixer.getDefaults();
+      const next: DyFM_AudioMixer_State = mixer.withChannelVolume(state, 'music', 40);
+
+      expect(next.channels['music']).toBe(40);
+      expect(state.channels['music']).toBe(36);
+      expect(next).not.toBe(state);
+    });
+
+    it('withChannelVolume ismeretlen csatornara dob', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+
+      expect((): void => {
+        mixer.withChannelVolume(mixer.getDefaults(), 'effects', 10);
+      }).toThrow();
+    });
+
+    it('withMasterVolume a sajat skalan szorit es kerekit', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const next: DyFM_AudioMixer_State = mixer.withMasterVolume(mixer.getDefaults(), 120);
+
+      expect(next.master).toBe(100);
+    });
+
+    it('withMuted UJ objektumot ad', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const state: DyFM_AudioMixer_State = mixer.getDefaults();
+      const next: DyFM_AudioMixer_State = mixer.withMuted(state, true);
+
+      expect(next.muted).toBe(true);
+      expect(state.muted).toBe(false);
+    });
+  });
+
+  describe('isEqual', (): void => {
+
+    it('ertek szerint hasonlit, nem referencia szerint', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+
+      expect(mixer.isEqual(mixer.getDefaults(), mixer.getDefaults())).toBe(true);
+    });
+
+    it('egy csatorna elteresere is false', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const changed: DyFM_AudioMixer_State = mixer.withChannelVolume(mixer.getDefaults(), 'dialog', 1);
+
+      expect(mixer.isEqual(mixer.getDefaults(), changed)).toBe(false);
+    });
+  });
+
+  describe('round-1 kompatibilitas (createClassic + hidak)', (): void => {
+
+    it('a classic preset a round-1 csatornakat adja', (): void => {
+      expect(DyFM_AudioMixer_ControlModel.createClassic().getChannels())
+        .toEqual(['music', 'ambience', 'effects']);
+    });
+
+    it('fromClassicSettings atveszi a fix alakot', (): void => {
+      const legacy: DyFM_AudioMixer_Settings = {
+        master: 0.5, music: 0.4, ambience: 0.3, effects: 0.2, muted: true,
+      };
+      const state: DyFM_AudioMixer_State = DyFM_AudioMixer_ControlModel.fromClassicSettings(legacy);
+
+      expect(state.master).toBeCloseTo(0.5, 10);
+      expect(state.channels['ambience']).toBeCloseTo(0.3, 10);
+      expect(state.muted).toBe(true);
+    });
+
+    it('oda-vissza konverzio ertekhu (classic -> state -> classic)', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = DyFM_AudioMixer_ControlModel.createClassic();
+      const legacy: DyFM_AudioMixer_Settings = {
+        master: 0.65, music: 0.4, ambience: 0.3, effects: 0.9, muted: false,
+      };
+      const roundTrip: DyFM_AudioMixer_Settings = mixer.toClassicSettings(
+        DyFM_AudioMixer_ControlModel.fromClassicSettings(legacy),
+      );
+
+      expect(roundTrip).toEqual(legacy);
+    });
+
+    it('a peldany-metodus a SAJAT skalarol normalizal (0-100 -> 0..1)', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = DyFM_AudioMixer_ControlModel.createPercent(
+        ['music', 'ambience', 'effects'],
+        { music: 40, ambience: 30, effects: 90 },
+        65,
+      );
+      const classic: DyFM_AudioMixer_Settings = mixer.toClassicSettings(mixer.getDefaults());
+
+      expect(classic.master).toBeCloseTo(0.65, 10);
+      expect(classic.music).toBeCloseTo(0.4, 10);
+      expect(classic.effects).toBeCloseTo(0.9, 10);
+    });
+
+    it('a classic mixer effektiv hangereje egyezik a round-1 szamitassal (csatorna * master)', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = DyFM_AudioMixer_ControlModel.createClassic();
+      const state: DyFM_AudioMixer_State = DyFM_AudioMixer_ControlModel.fromClassicSettings({
+        master: 0.5, music: 0.4, ambience: 0.3, effects: 0.2, muted: false,
+      });
+
+      expect(mixer.getEffectiveVolume(state, 'music')).toBeCloseTo(0.2, 10);
+    });
+  });
+
+  describe('Hero Coordinator regresszio-vedelem', (): void => {
+
+    it('a 0-100 tarolas ertekhuen tulel egy merge-ciklust (NINCS adat-migracio)', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+      const persisted: DyFM_AudioMixer_State = {
+        master: 72, channels: { music: 36, dialog: 84, interface: 68 }, muted: false,
+      };
+
+      expect(mixer.merge(JSON.parse(JSON.stringify(persisted)))).toEqual(persisted);
+    });
+
+    it('a dialog es interface csatorna NEM vesz el (a round-1 fix alak hibaja)', (): void => {
+      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
+
+      expect(mixer.hasChannel('dialog')).toBe(true);
+      expect(mixer.hasChannel('interface')).toBe(true);
+    });
+  });
+});