namespace AcDream.UI.Abstractions.Panels.Settings;

/// <summary>
/// Audio mixer preferences persisted to <c>settings.json</c>. The host wires
/// these into <c>OpenAlAudioEngine.MasterVolume</c> / <c>SfxVolume</c> /
/// <c>AmbientVolume</c> on Save and on startup.
///
/// <para>
/// A <c>Music</c> field lived here until 2026-08-08 (Campaign A slice A6).
/// Retail has no music system to turn down — see the note on
/// <c>IAudioEngine</c> — so the knob moved nothing. Old <c>settings.json</c>
/// files carrying a <c>"music"</c> key still load: the reader simply ignores
/// keys it does not know, and the next save drops it.
/// </para>
///
/// <para>
/// Defaults match the engine's hard-coded starting values so a user
/// who never opens the Audio tab gets identical behaviour to the
/// previous env-var-only world.
/// </para>
/// </summary>
public sealed record AudioSettings(
    float Master,
    float Sfx,
    float Ambient)
{
    /// <summary>
    /// Values used on first launch. Retail's own defaults are 1.0 for every
    /// sound preference (<c>SoundManager::InitPrefs</c> @ <c>0x005503F0</c>),
    /// so ambient starts at unity rather than the invented 0.8.
    /// </summary>
    public static AudioSettings Default { get; } = new(
        Master:  1.0f,
        Sfx:     1.0f,
        Ambient: 1.0f);
}