@futdevpro/fsm-dynamo 1.16.31 → 1.16.33

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

@@ -0,0 +1,378 @@
+
+
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+
+import { DyFM_AudioScale_Util } from '../_collections/audio-scale.util';
+
+import { DyFM_AudioMixer_Config } from './audio-mixer-config.interface';
+import { DyFM_AudioMixer_Settings } from './audio-mixer-settings.interface';
+import { DyFM_AudioMixer_State } from './audio-mixer-state.interface';
+import { DyFM_AudioScale } from './audio-scale.interface';
+
+
+/**
+ * **Csatorna- es skala-agnosztikus** jatek-audio mixer: a projekt deklaralja a sajat
+ * csatornait es szamabrazolasat, a modell pedig kezeli az allapotot es kiszamolja az
+ * effektiv hangerot.
+ *
+ * **Miert letezik a `DyFM_AudioMixer_Util` (round-1) mellett:** az a util negy FIX csatornara
+ * (`music` / `ambience` / `effects`) es `0..1` skalara epul. Ez a Prototyper harom prototipusara
+ * igaz, de a **Hero Coordinator** csatornai `music` / `dialog` / `interface`, az ertekei pedig
+ * `0-100` egeszek. A fix alak ott csatorna-vesztessel es kotelezo adat-migracioval jarna.
+ * Ez a modell mindkettot kiszolgalja; a round-1 alak `createClassic()` presetkent tovabb el.
+ *
+ * **Rendereles-agnosztikus:** NINCS DOM, Web Audio, Angular vagy Node fuggese. A tenyleges
+ * lejatszas (HTMLAudioElement, Web Audio `GainNode`, vagy barmi mas) a fogyasztoe — ez a
+ * **modell + szamitas**.
+ *
+ * **Hasznalat (Hero Coordinator-stilus, 0-100 egesz):**
+ * ```typescript
+ * const mixer = DyFM_AudioMixer_ControlModel.createPercent(['music', 'dialog', 'interface'], {
+ *   music: 36, dialog: 84, interface: 68,
+ * }, 72);
+ *
+ * let state = mixer.merge(JSON.parse(localStorage.getItem('audio') ?? 'null'));
+ * gainNode.gain.value = mixer.getEffectiveVolume(state, 'interface'); // MINDIG 0..1
+ *
+ * state = mixer.withChannelVolume(state, 'music', 40); // a sajat skalajan adjuk meg
+ * localStorage.setItem('audio', JSON.stringify(state));
+ * ```
+ *
+ * **Hasznalat (Prototyper-stilus, 0..1):**
+ * ```typescript
+ * const mixer = DyFM_AudioMixer_ControlModel.createClassic();
+ * const state = DyFM_AudioMixer_ControlModel.fromClassicSettings(legacySettings);
+ * ```
+ */
+export class DyFM_AudioMixer_ControlModel {
+
+  /** A `master` fenntartott nev — nem lehet sima csatorna, mert minden csatornara szorzodik. */
+  static readonly masterChannel: string = 'master';
+
+  /** A validalt, sajat peldany-config (a hivo altal atadott objektumtol fuggetlen masolat). */
+  private readonly config: DyFM_AudioMixer_Config;
+
+  /**
+   * A config validalasa **konstruktor-idoben** tortenik: egy elgepelt csatorna-nev vagy hianyzo
+   * skala igy a jatek inditasakor derul ki, nem hangleajatszas kozben.
+   */
+  constructor(config: DyFM_AudioMixer_Config) {
+    if (!config || !Array.isArray(config.channels) || !config.channels.length) {
+      throw new DyFM_Error({
+        errorCode: 'DYFM-AUDIO-MIXER-001',
+        message: 'DyFM_AudioMixer_ControlModel: config.channels must be a non-empty string array',
+        additionalContent: { config: config },
+      });
+    }
+
+    const seen: string[] = [];
+
+    for (const channel of config.channels) {
+      if (typeof channel !== 'string' || !channel.length) {
+        throw new DyFM_Error({
+          errorCode: 'DYFM-AUDIO-MIXER-002',
+          message: 'DyFM_AudioMixer_ControlModel: every channel name must be a non-empty string',
+          additionalContent: { channels: config.channels },
+        });
+      }
+
+      if (channel === DyFM_AudioMixer_ControlModel.masterChannel) {
+        throw new DyFM_Error({
+          errorCode: 'DYFM-AUDIO-MIXER-003',
+          message: 'DyFM_AudioMixer_ControlModel: "master" is reserved and must not be listed in channels',
+          additionalContent: { channels: config.channels },
+        });
+      }
+
+      if (seen.includes(channel)) {
+        throw new DyFM_Error({
+          errorCode: 'DYFM-AUDIO-MIXER-004',
+          message: 'DyFM_AudioMixer_ControlModel: duplicate channel name',
+          additionalContent: { channel: channel, channels: config.channels },
+        });
+      }
+
+      seen.push(channel);
+    }
+
+    const scale: DyFM_AudioScale = config.scale && typeof config.scale.max === 'number'
+      ? { max: config.scale.max, integer: config.scale.integer === true }
+      : DyFM_AudioScale_Util.getUnitScale();
+
+    this.config = {
+      channels: [...config.channels],
+      scale: scale,
+      defaults: config.defaults ? { ...config.defaults } : {},
+      defaultMaster: config.defaultMaster,
+      defaultChannelVolume: config.defaultChannelVolume,
+    };
+  }
+
+  /**
+   * A round-1 `DyFM_AudioMixer_Settings` alakjaval egyenerteku mixer (`music` / `ambience` /
+   * `effects`, `0..1` skala, 0.8 default). A Prototyper-stilusu fogyasztoknak.
+   */
+  static createClassic(): DyFM_AudioMixer_ControlModel {
+    return new DyFM_AudioMixer_ControlModel({
+      channels: ['music', 'ambience', 'effects'],
+      scale: DyFM_AudioScale_Util.getUnitScale(),
+      defaultMaster: DyFM_AudioScale_Util.defaultRatio,
+      defaultChannelVolume: DyFM_AudioScale_Util.defaultRatio,
+    });
+  }
+
+  /**
+   * `0-100` egesz skalaju mixer tetszoleges csatorna-keszlettel — a Hero Coordinator-stilusu
+   * fogyasztoknak, akik igy **adat-migracio nelkul** vehetik hasznalatba a bedrock modellt.
+   */
+  static createPercent(
+    channels: string[],
+    defaults?: Record<string, number>,
+    defaultMaster?: number,
+  ): DyFM_AudioMixer_ControlModel {
+    return new DyFM_AudioMixer_ControlModel({
+      channels: channels,
+      scale: DyFM_AudioScale_Util.getPercentScale(),
+      defaults: defaults,
+      defaultMaster: defaultMaster,
+    });
+  }
+
+  /** A round-1 fix alakot atalakitja a nyitott allapot-alakra (migracios hid). */
+  static fromClassicSettings(settings: DyFM_AudioMixer_Settings): DyFM_AudioMixer_State {
+    const safe: DyFM_AudioMixer_Settings = settings ?? ({} as DyFM_AudioMixer_Settings);
+    const scale: DyFM_AudioScale = DyFM_AudioScale_Util.getUnitScale();
+
+    return {
+      master: DyFM_AudioScale_Util.toUnit(safe.master, scale),
+      channels: {
+        music: DyFM_AudioScale_Util.toUnit(safe.music, scale),
+        ambience: DyFM_AudioScale_Util.toUnit(safe.ambience, scale),
+        effects: DyFM_AudioScale_Util.toUnit(safe.effects, scale),
+      },
+      muted: safe.muted === true,
+    };
+  }
+
+  /**
+   * A nyitott allapot-alakot visszaalakitja a round-1 fix alakra (migracios hid visszafele).
+   *
+   * **Peldany-metodus**, mert a helyes konverziohoz ismerni kell a peldany skalajat: egy
+   * `0-100`-as allapotot igy is `0..1`-re normalizal, ahogy a round-1 alak varja. (Statikus
+   * valtozatban ez nemaan rossz erteket adna.)
+   *
+   * A klasszikus keszleten kivuli csatornak (pl. `dialog`) **elvesznek** — ez a round-1 alak
+   * korlatja, nem a konverzioe.
+   */
+  toClassicSettings(state: DyFM_AudioMixer_State): DyFM_AudioMixer_Settings {
+    const safe: DyFM_AudioMixer_State = this.merge(state);
+    const scale: DyFM_AudioScale = this.config.scale;
+
+    return {
+      master: DyFM_AudioScale_Util.toUnit(safe.master, scale),
+      music: DyFM_AudioScale_Util.toUnit(safe.channels['music'], scale),
+      ambience: DyFM_AudioScale_Util.toUnit(safe.channels['ambience'], scale),
+      effects: DyFM_AudioScale_Util.toUnit(safe.channels['effects'], scale),
+      muted: safe.muted === true,
+    };
+  }
+
+  /** A peldany configja (masolat — a mutalasa nem hat vissza a modellre). */
+  getConfig(): DyFM_AudioMixer_Config {
+    return {
+      channels: [...this.config.channels],
+      scale: { max: this.config.scale.max, integer: this.config.scale.integer },
+      defaults: { ...this.config.defaults },
+      defaultMaster: this.config.defaultMaster,
+      defaultChannelVolume: this.config.defaultChannelVolume,
+    };
+  }
+
+  /** A deklaralt csatorna-nevek (a `master` nelkul). */
+  getChannels(): string[] {
+    return [...this.config.channels];
+  }
+
+  /** Igaz, ha a nev a deklaralt csatornak kozott van (a `master` NEM az). */
+  hasChannel(channel: string): boolean {
+    return this.config.channels.includes(channel);
+  }
+
+  /**
+   * Alapertelmezett allapot a **sajat skalan**. Minden hivas UJ objektumot ad vissza, hogy a
+   * hivo szabadon mutalhassa.
+   */
+  getDefaults(): DyFM_AudioMixer_State {
+    const channels: Record<string, number> = {};
+
+    for (const channel of this.config.channels) {
+      channels[channel] = this.getDefaultChannelVolume(channel);
+    }
+
+    return {
+      master: this.getDefaultMaster(),
+      channels: channels,
+      muted: false,
+    };
+  }
+
+  /**
+   * Reszleges / hianyzo / serult allapotbol teljes, ervenyes allapotot allit elo: a hianyzo
+   * csatornak a defaultot kapjak, az ertekek a sajat skalara szorulnak.
+   *
+   * **Ez a migracios biztositek:** egy regi payload, ami meg nem ismert egy kesobb bevezetett
+   * csatornat, igy is betoltheto marad. A **nem deklaralt** csatornak kiesnek — igy egy
+   * eltavolitott csatorna nem szivarog vissza a mentesbol. Serult (NaN / nem-szam) ertek eseten
+   * a csatorna DEFAULT-jat kapja, nem 0-t — egy hibas mentes ne nemitson el csendben.
+   *
+   * **Figyelem:** ez a nyitott (`channels` rekord) alakot varja. A round-1 LAPOS alakot
+   * (`{ master, music, ambience, effects, muted }`) eloszor a `fromClassicSettings()`-szel
+   * kell atalakitani — kulonben a csatornak a defaultot kapjak.
+   */
+  merge(partial?: Partial<DyFM_AudioMixer_State> | null): DyFM_AudioMixer_State {
+    const defaults: DyFM_AudioMixer_State = this.getDefaults();
+
+    if (!partial) {
+      return defaults;
+    }
+
+    const source: Record<string, number> = partial.channels ?? {};
+    const channels: Record<string, number> = {};
+
+    for (const channel of this.config.channels) {
+      const raw: number = source[channel];
+
+      channels[channel] = raw === undefined || raw === null
+        ? defaults.channels[channel]
+        : DyFM_AudioScale_Util.clampToScale(raw, this.config.scale, defaults.channels[channel]);
+    }
+
+    const master: number = partial.master === undefined || partial.master === null
+      ? defaults.master
+      : DyFM_AudioScale_Util.clampToScale(partial.master, this.config.scale, defaults.master);
+
+    return {
+      master: master,
+      channels: channels,
+      muted: partial.muted === true,
+    };
+  }
+
+  /**
+   * Egy csatorna **effektiv** hangereje `0..1`-ben — ezt varja a `HTMLAudioElement.volume` es a
+   * Web Audio `GainNode.gain.value`, fuggetlenul attol, milyen skalan tarol a projekt.
+   *
+   * A csatorna sajat erteke szorozva a master-rel; nemitas eseten mindig 0. A `'master'` nevre
+   * a master sajat (normalizalt) erteket adja vissza, nem negyzetre emelve.
+   *
+   * **Dob**, ha a csatorna nincs deklaralva — egy elgepelt csatorna-nev igy nem nemul el
+   * csendben, hanem azonnal kiderul (`core-rich-error-handling`).
+   */
+  getEffectiveVolume(state: DyFM_AudioMixer_State, channel: string): number {
+    if (channel !== DyFM_AudioMixer_ControlModel.masterChannel && !this.hasChannel(channel)) {
+      throw new DyFM_Error({
+        errorCode: 'DYFM-AUDIO-MIXER-005',
+        message: 'DyFM_AudioMixer_ControlModel.getEffectiveVolume: unknown channel',
+        additionalContent: { channel: channel, declaredChannels: this.config.channels },
+      });
+    }
+
+    const safe: DyFM_AudioMixer_State = this.merge(state);
+
+    if (safe.muted) {
+      return 0;
+    }
+
+    const masterUnit: number = DyFM_AudioScale_Util.toUnit(safe.master, this.config.scale);
+
+    if (channel === DyFM_AudioMixer_ControlModel.masterChannel) {
+      return masterUnit;
+    }
+
+    const channelUnit: number = DyFM_AudioScale_Util.toUnit(safe.channels[channel], this.config.scale);
+
+    return DyFM_AudioScale_Util.clampUnit(channelUnit * masterUnit);
+  }
+
+  /**
+   * Egy csatorna hangerejenek beallitasa a **sajat skalan** — UJ allapot-objektumot ad vissza
+   * (immutable update), hogy signal-/state-alapu tarolokban is biztonsagos legyen.
+   */
+  withChannelVolume(
+    state: DyFM_AudioMixer_State,
+    channel: string,
+    volume: number,
+  ): DyFM_AudioMixer_State {
+    if (!this.hasChannel(channel)) {
+      throw new DyFM_Error({
+        errorCode: 'DYFM-AUDIO-MIXER-006',
+        message: 'DyFM_AudioMixer_ControlModel.withChannelVolume: unknown channel',
+        additionalContent: { channel: channel, declaredChannels: this.config.channels },
+      });
+    }
+
+    const next: DyFM_AudioMixer_State = this.merge(state);
+    next.channels[channel] = DyFM_AudioScale_Util.clampToScale(volume, this.config.scale);
+
+    return next;
+  }
+
+  /** A master beallitasa a **sajat skalan** — UJ allapot-objektumot ad vissza. */
+  withMasterVolume(state: DyFM_AudioMixer_State, volume: number): DyFM_AudioMixer_State {
+    const next: DyFM_AudioMixer_State = this.merge(state);
+    next.master = DyFM_AudioScale_Util.clampToScale(volume, this.config.scale);
+
+    return next;
+  }
+
+  /** Nemitas beallitasa — UJ allapot-objektumot ad vissza. */
+  withMuted(state: DyFM_AudioMixer_State, muted: boolean): DyFM_AudioMixer_State {
+    const next: DyFM_AudioMixer_State = this.merge(state);
+    next.muted = muted === true;
+
+    return next;
+  }
+
+  /** Ket allapot ertek szerinti egyezese (mentes-szukseg / change-detection dontesehez). */
+  isEqual(a: DyFM_AudioMixer_State, b: DyFM_AudioMixer_State): boolean {
+    const left: DyFM_AudioMixer_State = this.merge(a);
+    const right: DyFM_AudioMixer_State = this.merge(b);
+
+    if (left.master !== right.master || left.muted !== right.muted) {
+      return false;
+    }
+
+    for (const channel of this.config.channels) {
+      if (left.channels[channel] !== right.channels[channel]) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /** A master alapertelmezese a sajat skalan (config, kulonben a maximum 80%-a). */
+  private getDefaultMaster(): number {
+    if (typeof this.config.defaultMaster === 'number' && !Number.isNaN(this.config.defaultMaster)) {
+      return DyFM_AudioScale_Util.clampToScale(this.config.defaultMaster, this.config.scale);
+    }
+
+    return DyFM_AudioScale_Util.fromUnit(DyFM_AudioScale_Util.defaultRatio, this.config.scale);
+  }
+
+  /** Egy csatorna alapertelmezese a sajat skalan (per-csatorna, kulonben kozos, kulonben 80%). */
+  private getDefaultChannelVolume(channel: string): number {
+    const perChannel: number = (this.config.defaults ?? {})[channel];
+
+    if (typeof perChannel === 'number' && !Number.isNaN(perChannel)) {
+      return DyFM_AudioScale_Util.clampToScale(perChannel, this.config.scale);
+    }
+
+    if (typeof this.config.defaultChannelVolume === 'number'
+      && !Number.isNaN(this.config.defaultChannelVolume)) {
+      return DyFM_AudioScale_Util.clampToScale(this.config.defaultChannelVolume, this.config.scale);
+    }
+
+    return DyFM_AudioScale_Util.fromUnit(DyFM_AudioScale_Util.defaultRatio, this.config.scale);
+  }
+}

package/src/_modules/game/_models/audio-scale.interface.ts

@@ -0,0 +1,21 @@
+
+
+/**
+ * Egy audio-mixer csatorna-ertekeinek **skalaja** — a projekt sajat szamabrazolasa.
+ *
+ * **Miert kell:** a flotta ket kulonbozo skalat hasznal. A Prototyper prototipusai `0..1`
+ * lebegopontos erteket tarolnak, a Hero Coordinator viszont `0-100` egeszet (`Math.round`-dal
+ * clampelve, igy is van elmentve a localStorage-ban). Ha a bedrock egyetlen skalat kenyszeritene,
+ * az egyik oldalnak **adatot kellene migralnia** — ezt kerulik el ezek a leirok.
+ *
+ * A modell befele mindig `0..1`-re normalizal (a lejatszo API-k ezt varjak), kifele viszont a
+ * projekt sajat skalajan tarol es ad vissza.
+ */
+export interface DyFM_AudioScale {
+
+  /** A csatorna-ertek maximuma a projekt sajat skalajan (pl. `1` vagy `100`). */
+  max: number;
+
+  /** Ha `true`, a sajat skalara visszaalakitott ertek egeszre kerekitodik (0-100 UI-hoz). */
+  integer: boolean;
+}

package/src/_modules/game/index.ts

@@ -2,9 +2,14 @@
 export * from './_enums/audio-channel.enum';
 
 // MODELS
+export * from './_models/audio-mixer-config.interface';
 export * from './_models/audio-mixer-settings.interface';
+export * from './_models/audio-mixer-state.interface';
+export * from './_models/audio-mixer.control-model';
+export * from './_models/audio-scale.interface';
 export * from './_models/seeded-random-state.interface';
 export * from './_models/seeded-random.control-model';
 
 // COLLECTIONS
 export * from './_collections/audio-mixer.util';
+export * from './_collections/audio-scale.util';