acdream/src/AcDream.Core/Audio/AmbientSoundModel.cs

using System;
using System.Collections.Generic;
using System.Numerics;

namespace AcDream.Core.Audio;

/// <summary>
/// Retail's <c>LandDefs::Direction</c> — where a contributing land cell sits
/// relative to the viewer's landblock. The jump table at <c>0x5A9A7C</c> gives
/// each one a compass heading in radians.
/// </summary>
public enum AmbientDirection
{
    InViewerBlock = 0,
    North = 1,
    South = 2,
    East = 3,
    West = 4,
    Northwest = 5,
    Southwest = 6,
    Northeast = 7,
    Southeast = 8,
}

/// <summary>
/// One authored ambient entry — retail's <c>AmbientSoundDesc</c> (0x14 packed).
/// <c>IsContinuous</c> is DERIVED at unpack from <c>BaseChance == 0</c>, not
/// stored; Binary Ninja renders that compare inverted, and porting its version
/// yields silence rather than a wrong sound.
/// </summary>
/// <param name="Sound">The <see cref="SoundId"/> slot in the referenced SoundTable.</param>
/// <param name="Volume">Authored linear gain.</param>
/// <param name="BaseChance">0 ⇒ continuous; otherwise the per-fire probability base.</param>
/// <param name="MinRate">Re-fire interval floor, seconds.</param>
/// <param name="MaxRate">Re-fire interval ceiling, seconds (continuous ignores it).</param>
public readonly record struct AmbientSoundDescriptor(
    SoundId Sound,
    float Volume,
    float BaseChance,
    float MinRate,
    float MaxRate)
{
    /// <summary>
    /// <c>base_chance == 0</c> ⇒ <c>ConstantSound</c> (a crossfaded,
    /// non-positional bed re-fired every <see cref="MinRate"/> seconds);
    /// non-zero ⇒ <c>IntermitSound</c>.
    /// </summary>
    public bool IsContinuous => BaseChance == 0f;
}

/// <summary>
/// Retail's ambient constants, byte-read from the PDB-paired binary. Every one
/// of these is elided or mis-rendered somewhere in the pseudo-C.
/// </summary>
public static class AmbientSoundConstants
{
    /// <summary>Full-weight radius, metres (<c>0x81F148</c>).</summary>
    public const float MinDistance = 20.0f;

    /// <summary><see cref="MinDistance"/> squared (<c>0x81F14C</c>).</summary>
    public const float MinDistanceSq = 400.0f;

    /// <summary>Cull radius, metres (<c>0x81F150</c>).</summary>
    public const float MaxDistance = 120.0f;

    /// <summary><see cref="MaxDistance"/> squared (<c>0x81F154</c>).</summary>
    public const float MaxDistanceSq = 14400.0f;

    /// <summary>
    /// Audibility floor for a continuous bed's crossfaded volume
    /// (<c>0x81F158</c>) — about −30.5 dB.
    /// </summary>
    public const float MinVolume = 0.03f;

    /// <summary>
    /// Total jitter cone applied to an intermittent sound's bearing
    /// (<c>0x81F1B0</c>): π/8 radians = 22.5°, so ±11.25°.
    /// </summary>
    public const float HeadingSpread = 0.392699093f;

    /// <summary>
    /// The "close enough to be anywhere around you" threshold in
    /// <c>Ambient::CalcDir</c>: <see cref="MinDistanceSq"/> × 0.5 = 200 m²,
    /// i.e. 14.142 m. This is the ONLY place the squared value is halved —
    /// reading it as <see cref="MinDistance"/> would widen the omnidirectional
    /// zone from 14 m to 20 m.
    /// </summary>
    public const float InViewerBlockDistanceSq = MinDistanceSq * 0.5f;

    /// <summary>Half of <see cref="MinDistance"/> — the shell half-thickness, metres.</summary>
    public const float ShellHalfThickness = MinDistance * 0.5f;

    /// <summary>Near bound used for the omnidirectional spread, metres (<c>5.0f − 1.0f</c>).</summary>
    public const float InBlockNearDistance = 4.0f;

    /// <summary>Metres per land cell (<c>LandDefs::square_length</c>, <c>0x799128</c>).</summary>
    public const float LandCellLength = 24.0f;

    /// <summary>Retail's per-direction compass heading, radians (jump table <c>0x5A9A7C</c>).</summary>
    public static float Heading(AmbientDirection direction) => direction switch
    {
        AmbientDirection.North => 0.0f,
        AmbientDirection.South => 3.14159274f,
        AmbientDirection.East => 1.57079637f,
        AmbientDirection.West => 4.71238899f,
        AmbientDirection.Northwest => 5.49778700f,
        AmbientDirection.Southwest => 3.92699075f,
        AmbientDirection.Northeast => 0.78539819f,
        AmbientDirection.Southeast => 2.35619450f,
        // IN_VIEWER_BLOCK and anything out of range fall to 0.0.
        _ => 0.0f,
    };

    /// <summary>
    /// <c>Ambient::CalcWeight</c> @ <c>0x550DD0</c>: full weight inside 20 m,
    /// inverse-square out to 120 m, nothing beyond. Binary Ninja dropped the
    /// arithmetic entirely.
    /// </summary>
    public static float CalcWeight(Vector3 offset)
    {
        float distanceSq = offset.LengthSquared();
        if (distanceSq > MaxDistanceSq) return 0f;
        if (distanceSq < MinDistanceSq) return 1f;
        return MinDistanceSq / distanceSq;
    }

    /// <summary>
    /// <c>Ambient::CalcDir</c> @ <c>0x550E40</c>: which compass sector a
    /// contributing cell falls in, or <see cref="AmbientDirection.InViewerBlock"/>
    /// when it is inside <see cref="InViewerBlockDistanceSq"/>. A sector counts as
    /// diagonal when neither axis dominates the other by more than 2×
    /// (<c>0x7C5E24</c>).
    /// </summary>
    public static AmbientDirection CalcDirection(Vector3 offset)
    {
        float x = offset.X;
        float y = offset.Y;

        // CalcDir squares X and Y only — Z is deliberately absent here, where
        // CalcWeight deliberately includes it. The two functions differ on
        // purpose; collapsing them would widen or narrow the omnidirectional
        // zone by the height difference.
        if (((x * x) + (y * y)) < InViewerBlockDistanceSq)
            return AmbientDirection.InViewerBlock;
        float ax = MathF.Abs(x);
        float ay = MathF.Abs(y);

        const float diagonalRatio = 2.0f;
        const float epsilon = 0.0002f;   // F_EPSILON @ 0x7CB0A0

        bool diagonal =
            ax > epsilon && ay > epsilon
            && ay / ax <= diagonalRatio
            && ax / ay <= diagonalRatio;

        if (diagonal)
        {
            return y >= 0f
                ? (x >= 0f ? AmbientDirection.Northeast : AmbientDirection.Northwest)
                : (x >= 0f ? AmbientDirection.Southeast : AmbientDirection.Southwest);
        }

        if (ay >= ax)
            return y >= 0f ? AmbientDirection.North : AmbientDirection.South;
        return x >= 0f ? AmbientDirection.East : AmbientDirection.West;
    }
}

/// <summary>
/// One live ambient instance — retail's <c>ConstantSound</c> or
/// <c>IntermitSound</c>. Accumulates weight (and, for the intermittent kind,
/// bearings) during a rebuild, then answers the four questions the scheduler
/// asks: can it be heard, should it fire now, how loud, and when again.
/// </summary>
public sealed class AmbientSoundInstance
{
    private readonly List<AmbientDirectionShell> _directions = [];

    public AmbientSoundInstance(AmbientSoundDescriptor descriptor, uint soundTableDid)
    {
        Descriptor = descriptor;
        SoundTableDid = soundTableDid;
    }

    public AmbientSoundDescriptor Descriptor { get; }

    /// <summary>The SoundTable the descriptor's slot is looked up in.</summary>
    public uint SoundTableDid { get; }

    /// <summary>Accumulated weight from every contributing land cell.</summary>
    public float SoundCount { get; private set; }

    /// <summary>Crossfaded volume — continuous instances only.</summary>
    public float CurrentVolume { get; private set; }

    /// <summary>Per-fire probability — intermittent instances only.</summary>
    public float PlayChance { get; private set; }

    /// <summary>True while this instance holds a slot in the deadline queue.</summary>
    public bool OnQueue { get; set; }

    public IReadOnlyList<AmbientDirectionShell> Directions => _directions;

    /// <summary>
    /// <c>ResetCount</c> (<c>0x550CD0</c> intermittent, <c>0x550D70</c>
    /// continuous). Must run for EVERY instance before a rebuild accumulates:
    /// <c>IntermitSound::UpdateSound</c> never clears <see cref="PlayChance"/>,
    /// so a skipped reset leaves a stale bearing and probability alive forever.
    /// Note retail does NOT reset a continuous instance's
    /// <see cref="CurrentVolume"/> here.
    /// </summary>
    public void ResetCount()
    {
        SoundCount = 0f;
        _directions.Clear();
        if (!Descriptor.IsContinuous)
            PlayChance = 0f;
    }

    /// <summary>
    /// <c>AddTo</c> @ <c>0x551450</c>. A cell outside the viewer's own block
    /// contributes a 20 m-thick shell at its bearing; a cell inside
    /// <see cref="AmbientSoundConstants.InViewerBlockDistanceSq"/> could be
    /// anywhere around the listener, so it contributes 4–10 m in all eight
    /// directions.
    /// </summary>
    public void AddTo(float weight, Vector3 offset, AmbientDirection direction)
    {
        SoundCount += weight;
        if (Descriptor.IsContinuous)
            return;   // continuous beds track weight only, never bearings

        float distance = MathF.Sqrt(offset.LengthSquared());
        float half = AmbientSoundConstants.ShellHalfThickness;

        if (direction != AmbientDirection.InViewerBlock)
        {
            AddDirection(direction, distance - half, distance + half);
            return;
        }

        AddDirection(AmbientDirection.North, AmbientSoundConstants.InBlockNearDistance, half);
        AddDirection(AmbientDirection.South, AmbientSoundConstants.InBlockNearDistance, half);
        AddDirection(AmbientDirection.East, AmbientSoundConstants.InBlockNearDistance, half);
        AddDirection(AmbientDirection.West, AmbientSoundConstants.InBlockNearDistance, half);
        AddDirection(AmbientDirection.Northwest, AmbientSoundConstants.InBlockNearDistance, half);
        AddDirection(AmbientDirection.Southwest, AmbientSoundConstants.InBlockNearDistance, half);
        AddDirection(AmbientDirection.Northeast, AmbientSoundConstants.InBlockNearDistance, half);
        AddDirection(AmbientDirection.Southeast, AmbientSoundConstants.InBlockNearDistance, half);
    }

    /// <summary>
    /// <c>AddDir</c> @ <c>0x550CF0</c>: widen an existing shell for this bearing
    /// or append a new one. Retail keeps at most eight.
    /// </summary>
    private void AddDirection(AmbientDirection direction, float min, float max)
    {
        for (int i = 0; i < _directions.Count; i++)
        {
            if (_directions[i].Direction != direction)
                continue;

            AmbientDirectionShell existing = _directions[i];
            _directions[i] = new AmbientDirectionShell(
                direction,
                MathF.Min(existing.MinDistance, min),
                MathF.Max(existing.MaxDistance, max));
            return;
        }

        if (_directions.Count >= 8)
            return;
        _directions.Add(new AmbientDirectionShell(direction, min, max));
    }

    /// <summary>
    /// <c>UpdateSound</c> (<c>0x551540</c> continuous, <c>0x551310</c>
    /// intermittent). <paramref name="totalSoundCount"/> is the sum over ALL
    /// ambients, not per-descriptor — that denominator is what makes the mix a
    /// terrain-share crossfade.
    /// </summary>
    public void UpdateSound(float totalSoundCount)
    {
        if (Descriptor.IsContinuous)
        {
            if (SoundCount == 0f)
            {
                CurrentVolume = 0f;
                return;
            }
            CurrentVolume = Descriptor.Volume / totalSoundCount * SoundCount;
            return;
        }

        // Intermittent: note the asymmetry — a zero weight leaves PlayChance
        // ALONE rather than zeroing it. Only ResetCount clears it.
        if (SoundCount <= 0f)
            return;
        PlayChance = Descriptor.BaseChance / totalSoundCount * SoundCount;
    }

    /// <summary>
    /// <c>CanHear</c> (<c>0x550FD0</c> continuous, <c>0x550F80</c>
    /// intermittent). Both compares are rendered as an unimplemented predicate
    /// by Binary Ninja and would port inverted.
    /// </summary>
    public bool CanHear() =>
        Descriptor.IsContinuous
            ? CurrentVolume >= AmbientSoundConstants.MinVolume
            : PlayChance > 0f;

    /// <summary>
    /// <c>PlayNow</c> (continuous is a folded <c>mov eax,1</c> — ALWAYS true;
    /// intermittent rolls against <see cref="PlayChance"/> @ <c>0x550FA0</c>).
    /// </summary>
    public bool PlayNow(ISoundRandom rng)
    {
        ArgumentNullException.ThrowIfNull(rng);
        return Descriptor.IsContinuous || rng.NextVariantRoll() <= PlayChance;
    }

    /// <summary>
    /// <c>GetVolume</c>: the crossfaded value for a continuous bed
    /// (<c>0x551070</c> returns the AUTHORED volume for intermittent — the
    /// crossfade lives in its probability instead).
    /// </summary>
    public float GetVolume() =>
        Descriptor.IsContinuous ? CurrentVolume : Descriptor.Volume;

    /// <summary>
    /// <c>GetPlayInterval</c>: intermittent rolls between the authored rates
    /// (<c>0x551080</c>); continuous uses <c>min_rate</c> alone
    /// (<c>0x5510A0</c>) — that rate IS the author's intended loop period, which
    /// is how retail fakes a sustained bed without a looping voice.
    /// </summary>
    public float GetPlayInterval(ISoundRandom rng)
    {
        ArgumentNullException.ThrowIfNull(rng);
        return Descriptor.IsContinuous
            ? Descriptor.MinRate
            : RollDice(Descriptor.MinRate, Descriptor.MaxRate, rng);
    }

    /// <summary>
    /// <c>GetSoundPos</c> @ <c>0x551350</c>: offset the LISTENER's position in
    /// the XY plane, keeping their Z. Returns false for a continuous bed, whose
    /// base implementation is a folded <c>xor eax,eax</c> — no position at all,
    /// so it plays from centre.
    ///
    /// <para>
    /// The distance is <c>min + (max − min)·t²</c>, quadratically biased toward
    /// <c>min</c>; a linear lerp puts intermittent ambients audibly further away
    /// on average.
    /// </para>
    /// </summary>
    public bool TryGetSoundPosition(
        Vector3 listenerPosition,
        ISoundRandom rng,
        out Vector3 position)
    {
        ArgumentNullException.ThrowIfNull(rng);
        position = listenerPosition;

        if (Descriptor.IsContinuous || _directions.Count == 0)
            return false;

        int index = (int)MathF.Floor(rng.NextVariantRoll() * _directions.Count);
        if (index >= _directions.Count)
            index = _directions.Count - 1;
        AmbientDirectionShell shell = _directions[index];

        float spread = AmbientSoundConstants.HeadingSpread;
        float angle = AmbientSoundConstants.Heading(shell.Direction)
            + (rng.NextVariantRoll() * spread)
            - (spread * 0.5f);

        float t = rng.NextVariantRoll();
        float distance = shell.MinDistance
            + ((shell.MaxDistance - shell.MinDistance) * t * t);

        // AC's compass convention: north is +Y, east is +X.
        position = new Vector3(
            listenerPosition.X + (MathF.Sin(angle) * distance),
            listenerPosition.Y + (MathF.Cos(angle) * distance),
            listenerPosition.Z);
        return true;
    }

    /// <summary>
    /// <c>Random::RollDice</c> @ <c>0x42C600</c>, including its swap on an
    /// inverted range and its equal-bounds short circuit.
    /// </summary>
    internal static float RollDice(float min, float max, ISoundRandom rng)
    {
        if (min == max) return min;
        float lo = min, hi = max;
        if (max < min) { lo = max; hi = min; }
        return lo + ((hi - lo) * rng.NextVariantRoll());
    }
}

/// <summary>
/// One accumulated bearing for an intermittent ambient: a distance shell at a
/// compass direction.
/// </summary>
public readonly record struct AmbientDirectionShell(
    AmbientDirection Direction,
    float MinDistance,
    float MaxDistance);