@futdevpro/fsm-dynamo 1.16.38 → 1.16.40

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

@@ -1,143 +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;
-  }
-}
+
+
+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

@@ -1,140 +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);
-    });
-  });
-});
+
+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);
+    });
+  });
+});