@futdevpro/fsm-dynamo 1.16.30 → 1.16.33

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