@futdevpro/fsm-dynamo 1.20.9 → 1.20.12

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

@@ -1,53 +0,0 @@
-
-
-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;
-
-  /**
-   * Szoljon-e a hang alapbol akkor is, ha a tab/ablak nem aktiv. **Default: `false`**
-   * (owner-direktiva — a hatter-hang opt-in, sosem opt-out).
-   *
-   * Csak nagyon indokolt esetben allitsd `true`-ra (pl. tisztan audio-jatek).
-   */
-  defaultPlayWhenUnfocused?: boolean;
-}

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

@@ -1,38 +0,0 @@
-
-
-/**
- * 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;
-
-  /**
-   * Szoljon-e a hang, ha a tab/ablak nem aktiv. **Default: `false`.**
-   *
-   * **OPCIONALIS** — szandekosan, hogy a mezo bevezetese ne legyen torо valtozas a round-1
-   * alakot mar hasznalo projekteknek. A letezese viszont azt biztositja, hogy a klasszikus
-   * oda-vissza konverzio (`toClassicSettings` -> `fromClassicSettings`) NE veszitse el a
-   * kapcsolot.
-   */
-  playWhenUnfocused?: boolean;
-}

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

@@ -1,36 +0,0 @@
-
-
-/**
- * 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;
-
-  /**
-   * Szoljon-e a hang akkor is, ha a **tab / ablak NEM aktiv** (hattervben van).
-   *
-   * **Alapertelmezes: `false`** — owner-direktiva. Egy hattervbe tett jatek alapbol NE szoljon
-   * bele a felhasznalo mas munkajaba; aki ezt akarja, az kapcsolja be. Ez a mezo CSAK a
-   * szandekot hordozza — a tenyleges szuneteltetest a lejatszo-reteg vegzi (bongeszo-fuggo
-   * `visibilitychange` / `blur`), mert a modell-reteg szandekosan DOM-fuggetlen.
-   *
-   * **Migracio:** a mezo nelkuli (regi) mentesek a `merge()`-ben a config alapertelmezeset
-   * kapjak, tehat egy regi save betoltese nem kapcsolja be veletlenul a hatter-hangot.
-   */
-  playWhenUnfocused: boolean;
-}

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

@@ -1,376 +0,0 @@
-
-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,
-        playWhenUnfocused: 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,
-        playWhenUnfocused: 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);
-    });
-  });
-
-  describe('playWhenUnfocused (hatter-hang kapcsolo)', (): void => {
-
-    it('ALAPBOL kikapcsolt — a hatter-hang opt-in, sosem opt-out', (): void => {
-      expect(createHeroCoordinatorMixer().getDefaults().playWhenUnfocused).toBe(false);
-      expect(DyFM_AudioMixer_ControlModel.createClassic().getDefaults().playWhenUnfocused).toBe(false);
-    });
-
-    it('a config explicit `true`-ra allithatja (pl. tisztan audio-jatek)', (): void => {
-      const mixer: DyFM_AudioMixer_ControlModel = new DyFM_AudioMixer_ControlModel({
-        channels: ['music'],
-        scale: { max: 1, integer: false },
-        defaultPlayWhenUnfocused: true,
-      });
-
-      expect(mixer.getDefaults().playWhenUnfocused).toBe(true);
-    });
-
-    it('REGI mentes (mezo nelkul) a CONFIG defaultjat kapja, nem vakon false-t', (): void => {
-      const optIn: DyFM_AudioMixer_ControlModel = new DyFM_AudioMixer_ControlModel({
-        channels: ['music'],
-        scale: { max: 1, integer: false },
-        defaultPlayWhenUnfocused: true,
-      });
-      // A regi payloadban meg NINCS `playWhenUnfocused` — pont ez a migracios eset.
-      const legacy: Partial<DyFM_AudioMixer_State> = { master: 0.5, channels: { music: 0.5 } };
-
-      expect(optIn.merge(legacy).playWhenUnfocused).toBe(true);
-      expect(createHeroCoordinatorMixer().merge({ master: 50 }).playWhenUnfocused).toBe(false);
-    });
-
-    it('az explicit `false` felulirja a `true` config-defaultot', (): void => {
-      const optIn: DyFM_AudioMixer_ControlModel = new DyFM_AudioMixer_ControlModel({
-        channels: ['music'],
-        scale: { max: 1, integer: false },
-        defaultPlayWhenUnfocused: true,
-      });
-
-      expect(optIn.merge({ playWhenUnfocused: false }).playWhenUnfocused).toBe(false);
-    });
-
-    it('a withPlayWhenUnfocused UJ objektumot ad (immutable update)', (): void => {
-      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
-      const before: DyFM_AudioMixer_State = mixer.getDefaults();
-      const after: DyFM_AudioMixer_State = mixer.withPlayWhenUnfocused(before, true);
-
-      expect(after).not.toBe(before);
-      expect(before.playWhenUnfocused).toBe(false);
-      expect(after.playWhenUnfocused).toBe(true);
-    });
-
-    it('az isEqual KULONBSEGET lat a kapcsolon (kulonben nem mentodne el)', (): void => {
-      const mixer: DyFM_AudioMixer_ControlModel = createHeroCoordinatorMixer();
-      const off: DyFM_AudioMixer_State = mixer.getDefaults();
-
-      expect(mixer.isEqual(off, mixer.withPlayWhenUnfocused(off, true))).toBe(false);
-      expect(mixer.isEqual(off, mixer.withPlayWhenUnfocused(off, false))).toBe(true);
-    });
-
-    it('a klasszikus oda-vissza konverzio NEM veszti el a kapcsolot', (): void => {
-      const mixer: DyFM_AudioMixer_ControlModel = DyFM_AudioMixer_ControlModel.createClassic();
-      const on: DyFM_AudioMixer_State = mixer.withPlayWhenUnfocused(mixer.getDefaults(), true);
-      const classic: DyFM_AudioMixer_Settings = mixer.toClassicSettings(on);
-
-      expect(classic.playWhenUnfocused).toBe(true);
-      expect(DyFM_AudioMixer_ControlModel.fromClassicSettings(classic).playWhenUnfocused).toBe(true);
-    });
-  });
-});