@futdevpro/fsm-dynamo 1.16.30 → 1.16.33

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

@@ -0,0 +1,198 @@
+
+import { DyFM_AudioChannel } from '../_enums/audio-channel.enum';
+import { DyFM_AudioMixer_Settings } from '../_models/audio-mixer-settings.interface';
+
+import { DyFM_AudioMixer_Util } from './audio-mixer.util';
+
+
+describe('DyFM_AudioMixer_Util', (): void => {
+
+  describe('getDefaults', (): void => {
+
+    it('minden csatornara ervenyes 0..1 erteket ad, nem nemitva', (): void => {
+      const defaults: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.getDefaults();
+
+      expect(defaults.master).toBeGreaterThan(0);
+      expect(defaults.master).toBeLessThanOrEqual(1);
+      expect(defaults.music).toBeGreaterThan(0);
+      expect(defaults.ambience).toBeGreaterThan(0);
+      expect(defaults.effects).toBeGreaterThan(0);
+      expect(defaults.muted).toBe(false);
+    });
+
+    it('minden hivas UJ objektumot ad (nincs megosztott referencia)', (): void => {
+      const first: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.getDefaults();
+      const second: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.getDefaults();
+
+      first.master = 0.1;
+
+      expect(second.master).not.toBe(0.1);
+    });
+  });
+
+  describe('clamp', (): void => {
+
+    it('a 0..1 tartomanyba szorit', (): void => {
+      expect(DyFM_AudioMixer_Util.clamp(-3)).toBe(0);
+      expect(DyFM_AudioMixer_Util.clamp(7)).toBe(1);
+      expect(DyFM_AudioMixer_Util.clamp(0.35)).toBe(0.35);
+      expect(DyFM_AudioMixer_Util.clamp(0)).toBe(0);
+      expect(DyFM_AudioMixer_Util.clamp(1)).toBe(1);
+    });
+
+    it('NaN / undefined / nem-szam eseten a fallback-et adja', (): void => {
+      expect(DyFM_AudioMixer_Util.clamp(Number.NaN, 0.5)).toBe(0.5);
+      expect(DyFM_AudioMixer_Util.clamp(undefined, 0.5)).toBe(0.5);
+      expect(DyFM_AudioMixer_Util.clamp(null, 0.5)).toBe(0.5);
+    });
+  });
+
+  describe('merge — a migracios biztositek', (): void => {
+
+    it('hianyzo bemenetre a defaultot adja', (): void => {
+      expect(DyFM_AudioMixer_Util.merge(null)).toEqual(DyFM_AudioMixer_Util.getDefaults());
+      expect(DyFM_AudioMixer_Util.merge(undefined)).toEqual(DyFM_AudioMixer_Util.getDefaults());
+    });
+
+    it('reszleges (legacy) payloadot teljesse egeszit ki', (): void => {
+      const legacy: Partial<DyFM_AudioMixer_Settings> = { master: 0.4, music: 0.2 };
+      const merged: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.merge(legacy);
+
+      expect(merged.master).toBe(0.4);
+      expect(merged.music).toBe(0.2);
+      expect(merged.ambience).toBe(DyFM_AudioMixer_Util.getDefaults().ambience);
+      expect(merged.effects).toBe(DyFM_AudioMixer_Util.getDefaults().effects);
+      expect(merged.muted).toBe(false);
+    });
+
+    it('a tartomanyon kivuli mentett erteket beszoritja', (): void => {
+      const corrupted: Partial<DyFM_AudioMixer_Settings> = { master: 42, effects: -1 };
+      const merged: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.merge(corrupted);
+
+      expect(merged.master).toBe(1);
+      expect(merged.effects).toBe(0);
+    });
+
+    it('a muted-ot szigoruan boolean-na alakitja', (): void => {
+      expect(DyFM_AudioMixer_Util.merge({ muted: true }).muted).toBe(true);
+      expect(DyFM_AudioMixer_Util.merge({}).muted).toBe(false);
+    });
+  });
+
+  describe('getEffectiveVolume', (): void => {
+
+    const settings: DyFM_AudioMixer_Settings = {
+      master: 0.5,
+      music: 0.4,
+      ambience: 0.6,
+      effects: 1,
+      muted: false,
+    };
+
+    it('a csatorna erteket a master-rel szorozza', (): void => {
+      expect(DyFM_AudioMixer_Util.getEffectiveVolume(settings, DyFM_AudioChannel.music))
+        .toBeCloseTo(0.2, 10);
+      expect(DyFM_AudioMixer_Util.getEffectiveVolume(settings, DyFM_AudioChannel.ambience))
+        .toBeCloseTo(0.3, 10);
+      expect(DyFM_AudioMixer_Util.getEffectiveVolume(settings, DyFM_AudioChannel.effects))
+        .toBeCloseTo(0.5, 10);
+    });
+
+    it('a master csatornara a sajat erteket adja (nem negyzetre emelve)', (): void => {
+      expect(DyFM_AudioMixer_Util.getEffectiveVolume(settings, DyFM_AudioChannel.master)).toBe(0.5);
+    });
+
+    it('nemitas eseten minden csatorna 0', (): void => {
+      const muted: DyFM_AudioMixer_Settings = { ...settings, muted: true };
+
+      expect(DyFM_AudioMixer_Util.getEffectiveVolume(muted, DyFM_AudioChannel.master)).toBe(0);
+      expect(DyFM_AudioMixer_Util.getEffectiveVolume(muted, DyFM_AudioChannel.music)).toBe(0);
+      expect(DyFM_AudioMixer_Util.getEffectiveVolume(muted, DyFM_AudioChannel.ambience)).toBe(0);
+      expect(DyFM_AudioMixer_Util.getEffectiveVolume(muted, DyFM_AudioChannel.effects)).toBe(0);
+    });
+
+    it('serult settingsbol sem ad NaN-t', (): void => {
+      const corrupted: DyFM_AudioMixer_Settings = {
+        master: Number.NaN,
+        music: undefined,
+        ambience: -5,
+        effects: 99,
+        muted: false,
+      };
+
+      [
+        DyFM_AudioChannel.master,
+        DyFM_AudioChannel.music,
+        DyFM_AudioChannel.ambience,
+        DyFM_AudioChannel.effects,
+      ].forEach((channel: DyFM_AudioChannel): void => {
+        const volume: number = DyFM_AudioMixer_Util.getEffectiveVolume(corrupted, channel);
+
+        expect(Number.isNaN(volume)).toBe(false);
+        expect(volume).toBeGreaterThanOrEqual(0);
+        expect(volume).toBeLessThanOrEqual(1);
+      });
+    });
+  });
+
+  describe('immutable update-ek', (): void => {
+
+    it('a withChannelVolume UJ objektumot ad, az eredetit nem mutalja', (): void => {
+      const original: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.getDefaults();
+      const updated: DyFM_AudioMixer_Settings =
+        DyFM_AudioMixer_Util.withChannelVolume(original, DyFM_AudioChannel.music, 0.25);
+
+      expect(updated.music).toBe(0.25);
+      expect(original.music).not.toBe(0.25);
+      expect(updated).not.toBe(original);
+    });
+
+    it('a withChannelVolume beszoritja a tartomanyon kivuli erteket', (): void => {
+      const updated: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util
+        .withChannelVolume(DyFM_AudioMixer_Util.getDefaults(), DyFM_AudioChannel.effects, 5);
+
+      expect(updated.effects).toBe(1);
+    });
+
+    it('a withMuted UJ objektumot ad, az eredetit nem mutalja', (): void => {
+      const original: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.getDefaults();
+      const updated: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.withMuted(original, true);
+
+      expect(updated.muted).toBe(true);
+      expect(original.muted).toBe(false);
+    });
+  });
+
+  describe('isEqual', (): void => {
+
+    it('ertek szerint hasonlit, nem referencia szerint', (): void => {
+      expect(DyFM_AudioMixer_Util.isEqual(
+        DyFM_AudioMixer_Util.getDefaults(),
+        DyFM_AudioMixer_Util.getDefaults(),
+      )).toBe(true);
+    });
+
+    it('elteres eseten false', (): void => {
+      const changed: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util
+        .withChannelVolume(DyFM_AudioMixer_Util.getDefaults(), DyFM_AudioChannel.music, 0.1);
+
+      expect(DyFM_AudioMixer_Util.isEqual(DyFM_AudioMixer_Util.getDefaults(), changed)).toBe(false);
+    });
+  });
+
+  describe('kompatibilitas a flotta 4 meglevo interfeszevel', (): void => {
+
+    it('a PCR / PCS / PG / HC alak mezoi hianytalanul lefedve', (): void => {
+      const fromLegacyProject: DyFM_AudioMixer_Settings = {
+        master: 0.9,
+        music: 0.7,
+        ambience: 0.5,
+        effects: 0.3,
+        muted: false,
+      };
+      const merged: DyFM_AudioMixer_Settings = DyFM_AudioMixer_Util.merge(fromLegacyProject);
+
+      expect(merged).toEqual(fromLegacyProject);
+    });
+  });
+});

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/_collections/audio-scale.util.spec.ts

@@ -0,0 +1,140 @@
+
+import { DyFM_AudioScale } from '../_models/audio-scale.interface';
+
+import { DyFM_AudioScale_Util } from './audio-scale.util';
+
+
+describe('DyFM_AudioScale_Util', (): void => {
+
+  describe('getUnitScale / getPercentScale', (): void => {
+
+    it('a unit-skala 0..1, nem egesz', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getUnitScale();
+
+      expect(scale.max).toBe(1);
+      expect(scale.integer).toBe(false);
+    });
+
+    it('a percent-skala 0-100, egesz', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+
+      expect(scale.max).toBe(100);
+      expect(scale.integer).toBe(true);
+    });
+
+    it('minden hivas UJ objektumot ad (nincs megosztott referencia)', (): void => {
+      const first: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+      const second: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+
+      first.max = 7;
+
+      expect(second.max).toBe(100);
+    });
+  });
+
+  describe('toUnit', (): void => {
+
+    it('percent skalarol 0..1-re normalizal', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+
+      expect(DyFM_AudioScale_Util.toUnit(0, scale)).toBe(0);
+      expect(DyFM_AudioScale_Util.toUnit(72, scale)).toBeCloseTo(0.72, 10);
+      expect(DyFM_AudioScale_Util.toUnit(100, scale)).toBe(1);
+    });
+
+    it('unit skalan valtozatlanul hagy', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getUnitScale();
+
+      expect(DyFM_AudioScale_Util.toUnit(0.35, scale)).toBeCloseTo(0.35, 10);
+    });
+
+    it('a tartomanyon kivuli erteket beszoritja', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+
+      expect(DyFM_AudioScale_Util.toUnit(-40, scale)).toBe(0);
+      expect(DyFM_AudioScale_Util.toUnit(400, scale)).toBe(1);
+    });
+
+    it('ervenytelen bemenetre a fallback-et adja (NaN nem szivaroghat a lejatszoba)', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+
+      expect(DyFM_AudioScale_Util.toUnit(NaN, scale, 0.5)).toBe(0.5);
+      expect(DyFM_AudioScale_Util.toUnit(undefined as unknown as number, scale, 0.5)).toBe(0.5);
+      expect(DyFM_AudioScale_Util.toUnit('80' as unknown as number, scale, 0.5)).toBe(0.5);
+    });
+
+    it('serult skalaval sem oszt nullaval es nem ad NaN-t', (): void => {
+      const broken: DyFM_AudioScale = { max: 0, integer: false };
+
+      expect(DyFM_AudioScale_Util.toUnit(0.5, broken)).toBe(0.5);
+      expect(Number.isNaN(DyFM_AudioScale_Util.toUnit(1, broken))).toBe(false);
+    });
+  });
+
+  describe('fromUnit', (): void => {
+
+    it('percent skalara egeszre kerekit', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+
+      expect(DyFM_AudioScale_Util.fromUnit(0.725, scale)).toBe(73);
+      expect(DyFM_AudioScale_Util.fromUnit(0, scale)).toBe(0);
+      expect(DyFM_AudioScale_Util.fromUnit(1, scale)).toBe(100);
+    });
+
+    it('unit skalan NEM kerekit', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getUnitScale();
+
+      expect(DyFM_AudioScale_Util.fromUnit(0.725, scale)).toBeCloseTo(0.725, 10);
+    });
+
+    it('ervenytelen bemenetre 0-t ad', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+
+      expect(DyFM_AudioScale_Util.fromUnit(NaN, scale)).toBe(0);
+    });
+  });
+
+  describe('oda-vissza konverzio', (): void => {
+
+    it('percent egesz erteket VALTOZATLANUL ad vissza (nincs adat-drift a HC mentesen)', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+      const values: number[] = [0, 1, 36, 68, 72, 84, 99, 100];
+
+      for (const value of values) {
+        const roundTrip: number = DyFM_AudioScale_Util.fromUnit(
+          DyFM_AudioScale_Util.toUnit(value, scale),
+          scale,
+        );
+
+        expect(roundTrip).toBe(value);
+      }
+    });
+  });
+
+  describe('clampToScale', (): void => {
+
+    it('a sajat skala tartomanyaba szorit es egesz skalan kerekit', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+
+      expect(DyFM_AudioScale_Util.clampToScale(-5, scale)).toBe(0);
+      expect(DyFM_AudioScale_Util.clampToScale(150, scale)).toBe(100);
+      expect(DyFM_AudioScale_Util.clampToScale(72.4, scale)).toBe(72);
+    });
+
+    it('ervenytelen erteket 0-ra visz (nem a fallback-re)', (): void => {
+      const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getPercentScale();
+
+      expect(DyFM_AudioScale_Util.clampToScale(NaN, scale)).toBe(0);
+    });
+  });
+
+  describe('clampUnit', (): void => {
+
+    it('0..1 koze szorit, NaN-ra 0', (): void => {
+      expect(DyFM_AudioScale_Util.clampUnit(-1)).toBe(0);
+      expect(DyFM_AudioScale_Util.clampUnit(2)).toBe(1);
+      expect(DyFM_AudioScale_Util.clampUnit(0.42)).toBe(0.42);
+      expect(DyFM_AudioScale_Util.clampUnit(NaN)).toBe(0);
+    });
+  });
+});

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

@@ -0,0 +1,22 @@
+
+
+/**
+ * A jatek-audio mixer **klasszikus** csatorna-keszlete.
+ *
+ * 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`).
+ */
+export enum DyFM_AudioChannel {
+  master = 'master',
+  music = 'music',
+  ambience = 'ambience',
+  effects = 'effects',
+}

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;
+}