SoundPhysicsAdaptedModSystem.cs

using Vintagestory.API.Common;
using Vintagestory.API.Client;
using Vintagestory.API.Server;
using Vintagestory.API.MathTools;
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Runtime.CompilerServices;
using System.Linq;
using System.Reflection;
using System.Text;
using HarmonyLib;
using Vintagestory.GameContent;
using soundphysicsadapted.Patches;
using Vintagestory.API.Common.Entities;
using Vintagestory.API.Datastructures;

namespace soundphysicsadapted
{
    /// <summary>
    /// Sound Physics Adapted - Adds realistic sound occlusion and reverb to Vintage Story
    ///
    /// Phase 1 Features:
    /// - Raycast-based sound occlusion through blocks
    /// - Lowpass filtering for muffled sounds
    /// - Per-sound OpenAL filters
    ///
    /// Phase 3 Features (SPR-Style):
    /// - Completely replaces vanilla reverb
    /// - Multi-slot EAX reverb with different decay times
    /// - Works for ALL materials (wood, glass, soil, etc.)
    /// - Works for small spaces (tunnels) unlike vanilla
    ///
    /// Algorithm based on Sound Physics Remastered (GPL)
    /// </summary>
    public class SoundPhysicsAdaptedModSystem : ModSystem
    {
        private static SoundPhysicsAdaptedModSystem instance;
        private Harmony harmony;
        private static SoundPhysicsConfig config;

        /// <summary>
        /// Version of the main config file. A config file with a different version
        /// is replaced by fresh defaults. Bump this when the defaults change.
        /// Keep it equal to <see cref="MaterialSoundConfig.CurrentVersion"/> — both
        /// config files use one version number.
        /// </summary>
        private const int CurrentConfigVersion = 12;
        private static MaterialSoundConfig materialConfig;
        private static ICoreClientAPI clientApi;
        private static AudioPhysicsSystem acousticsManager;
        private static SoundPlaybackThrottle soundThrottle;
        
        // Phase 5A: Weather audio manager
        private static WeatherAudioManager weatherManager;
        private long weatherTimerId = 0;

        // Debug visualization (IRenderer wireframe)
        private static DebugVisualization debugViz;

        // === BLOCK ACCESSOR FOR THE COMPUTE CORE ===
        // Every DDA step reads one block. The default accessor takes two locks per read:
        // the global chunk lock in ClientWorldMap.GetChunkAtPos, and the chunk's own pack
        // lock in WorldChunk.UnpackAndReadBlock. A 90 s profile put 3056 ms of the mod's
        // 4465 ms main-thread cost inside those two calls — 68 percent of all mod CPU,
        // and 63 percent of the whole main thread's chunk lookups.
        //
        // ICachingBlockAccessor keeps the last two chunks and reads their block array
        // directly, so a ray that stays inside one chunk takes no lock at all. It returns
        // the same block ids: both paths end at ChunkData.GetBlockId(index, layer).
        //
        // Begin() drops the two cached chunks. It must run at the start of every tick,
        // because a chunk can unload between ticks and the cache would then hold a dead
        // reference.
        //
        // Main thread only — this type is not thread safe. Off-thread code (the sound
        // start patches) keeps using clientApi.World.BlockAccessor.
        private static ICachingBlockAccessor tickBlockAccessor;

        // === WORLD READINESS GATE ===
        // Prevents tick handlers and Harmony patches from running expensive raycasts
        // before the world is fully loaded. Without this, DDA raycasts against an
        // incomplete block accessor take 100+ seconds and freeze the client.
        private static bool _worldReady = false;
        private static int _warmupTicksRemaining = 0;
        private const int WARMUP_TICKS = 4; // ~100ms stabilization after LevelFinalize
        /// <summary>Full readiness: world loaded + warmup complete. Gates heavy ACOUSTICS tick.</summary>
        public static bool IsWorldReady => _worldReady && _warmupTicksRemaining <= 0;
        /// <summary>Block accessor available (LevelFinalize fired). Gates cheap single-ray occlusion on sound start.</summary>
        public static bool IsWorldDataLoaded => _worldReady;

        // === FREEZE DIAGNOSTIC: Heartbeat + timing infrastructure ===
        private static Stopwatch _diagStopwatch = new Stopwatch();
        private static long _diagHeartbeatCounter = 0;
        private static long _diagLastHeartbeatLogMs = 0;
        private const long DIAG_HEARTBEAT_INTERVAL_MS = 5000; // Log heartbeat every 5s
        private static long _diagSmoothTickCount = 0;
        private static long _diagOcclusionTickCount = 0;
        private static long _diagCleanupTickCount = 0;
        private static double _diagSmoothTotalMs = 0;
        private static double _diagOcclusionTotalMs = 0;
        private static double _diagSmoothMaxMs = 0;
        private static double _diagOcclusionMaxMs = 0;
        // FPS tracking: measure frame time via smoothing tick (fires every 25ms game tick)
        private static Stopwatch _diagFpsStopwatch = new Stopwatch();
        private static long _diagFrameCount = 0;
        private static double _diagFrameTimeSum = 0;
        private static double _diagFrameTimeMax = 0;
        
        // Mod compatibility detection
        private static bool carryOnModLoaded = false;
        private static bool surroundSoundModLoaded = false;
        
        /// <summary>
        /// True if the "Carry On" mod is loaded - changes resonator pause/resume from Shift+RMB to Ctrl+RMB
        /// </summary>
        public static bool CarryOnModLoaded => carryOnModLoaded;

        /// <summary>
        /// True if "Vintage Story Surround Sound" mod is loaded - weather audio files may be
        /// replaced with 5.1 surround (6ch) OGGs. MonoDownmixManager handles N-channel downmix.
        /// Their experimental RainEmitterSystem may produce double positional rain if both active.
        /// </summary>
        public static bool SurroundSoundModLoaded => surroundSoundModLoaded;

        public static SoundPhysicsConfig Config => config;
        public static MaterialSoundConfig MaterialConfig => materialConfig;
        public static ICoreClientAPI ClientApi => clientApi;
        public static SoundPhysicsAdaptedModSystem Instance => instance;
        public static AudioPhysicsSystem Acoustics => acousticsManager;
        public static WeatherAudioManager Weather => weatherManager;
        public static SoundPlaybackThrottle Throttle => soundThrottle;

        public const string HARMONY_ID = "com.soundphysicsadapted.mod";
        public const string MOD_ID = "soundphysicsadapted";

        // Networking
        public static IClientNetworkChannel ClientChannel;
        public static IServerNetworkChannel ServerChannel;

        public override void Start(ICoreAPI api)
        {
            base.Start(api);
            instance = this;

            // Register Network Channel
            api.Network.RegisterChannel("soundphysicsadapted")
                .RegisterMessageType(typeof(ResonatorSyncPacket))
                .RegisterMessageType(typeof(ServerHandshakePacket))
                .RegisterMessageType(typeof(BoomboxSyncPacket));

            // Load main configuration
            try
            {
                config = api.LoadModConfig<SoundPhysicsConfig>("soundphysicsadapted.json");
                if (config == null)
                {
                    // First install — generate fresh defaults
                    config = new SoundPhysicsConfig();
                    config.ConfigVersion = CurrentConfigVersion;
                    api.Logger.Notification("[SoundPhysicsAdapted] No config found, generating defaults.");
                }
                else if (config.ConfigVersion > CurrentConfigVersion)
                {
                    // Newer config (mod downgrade) gets regenerated from fresh defaults —
                    // it may carry values this version can't interpret, so silently
                    // re-stamping its version would be wrong.
                    api.Logger.Notification($"[SoundPhysicsAdapted] Config v{config.ConfigVersion} is newer than mod's v{CurrentConfigVersion}. Regenerating with fresh defaults.");
                    config = new SoundPhysicsConfig();
                    config.ConfigVersion = CurrentConfigVersion;
                }
                else if (config.ConfigVersion < CurrentConfigVersion)
                {
                    if (UpgradeConfig(config, api.Logger))
                    {
                        MigrateConfig(config);
                    }
                    else
                    {
                        api.Logger.Notification($"[SoundPhysicsAdapted] Config v{config.ConfigVersion} has no upgrade step to v{CurrentConfigVersion}. Regenerating with fresh defaults.");
                        config = new SoundPhysicsConfig();
                        config.ConfigVersion = CurrentConfigVersion;
                    }
                }
                else
                {
                    // Current version — clamp-only sanity pass
                    MigrateConfig(config);
                }
                api.StoreModConfig(config, "soundphysicsadapted.json");
                config.RecalculateDerived();
                api.Logger.Notification($"[SoundPhysicsAdapted] Config loaded (v{config.ConfigVersion}) - Enabled: {config.Enabled}, DebugMode: {config.DebugMode}, InaudibleThreshold: {config.InaudibleOcclusionThreshold:F1}");
            }
            catch (Exception ex)
            {
                api.Logger.Error($"[SoundPhysicsAdapted] Failed to load config: {ex.Message}");
                config = new SoundPhysicsConfig();
                config.RecalculateDerived();
            }

            // Load material sound configuration
            try
            {
                materialConfig = api.LoadModConfig<MaterialSoundConfig>("soundphysicsadapted_materials.json");
                if (materialConfig == null)
                {
                    materialConfig = MaterialSoundConfig.CreateDefault();
                }
                else if (materialConfig.Version > MaterialSoundConfig.CurrentVersion)
                {
                    // Newer material config (mod downgrade) — regenerate, same reason as
                    // the main config above.
                    api.Logger.Notification($"[SoundPhysicsAdapted] Material config v{materialConfig.Version} is newer than mod's v{MaterialSoundConfig.CurrentVersion}. Regenerating with fresh defaults.");
                    materialConfig = MaterialSoundConfig.CreateDefault();
                }
                else if (materialConfig.Version < MaterialSoundConfig.CurrentVersion)
                {
                    // Upgrade the file the user has. Only entries whose default changed
                    // are touched. A version with no upgrade step falls back to defaults.
                    if (!materialConfig.Upgrade(api.Logger))
                    {
                        api.Logger.Notification($"[SoundPhysicsAdapted] Material config v{materialConfig.Version} has no upgrade step to v{MaterialSoundConfig.CurrentVersion}. Regenerating with fresh defaults.");
                        materialConfig = MaterialSoundConfig.CreateDefault();
                    }
                }
                // Always re-save to add any new properties from updates
                api.StoreModConfig(materialConfig, "soundphysicsadapted_materials.json");
                api.Logger.Notification($"[SoundPhysicsAdapted] Material config loaded - {materialConfig.Occlusion.Materials.Count} materials, {materialConfig.Occlusion.BlockOverrides.Count} overrides, {materialConfig.Occlusion.TreatAsFullCube?.Count ?? 0} full-cube patterns, {materialConfig.SoundPenetration?.Overrides?.Count ?? 0} penetration overrides");
            }
            catch (Exception ex)
            {
                api.Logger.Error($"[SoundPhysicsAdapted] Failed to load material config: {ex.Message}");
                try
                {
                    materialConfig = MaterialSoundConfig.CreateDefault();
                }
                catch (Exception ex2)
                {
                    api.Logger.Error($"[SoundPhysicsAdapted] CreateDefault also failed: {ex2.Message}");
                    materialConfig = new MaterialSoundConfig();
                }
            }

            // Initialize sound override manager (logs active overrides)
            Core.SoundOverrideManager.Initialize(api, config);

            // Optional ConfigLib integration: in-game config GUI if mod is present
            if (api.ModLoader.IsModEnabled("configlib"))
                new ConfigLibBridge(api, config);
        }

        // Server-side Harmony instance for resonator patches
        private Harmony serverHarmony;
        private static ICoreServerAPI serverApi;

        /// <summary>
        /// Distance filter for boombox sync relay (blocks).
        /// Matches the point where vanilla resonator volume curve hits ~0.
        /// </summary>
        private const float BOOMBOX_RELAY_RANGE = 48f;

        /// <summary>
        /// Server-side cache of the most recent BoomboxSyncPacket per carrier (key = entity id).
        /// Populated whenever a carrier sends an IsPlaying=true packet, cleared on IsPlaying=false.
        /// Used to (1) sync state to late joiners and (2) push state to players who newly enter
        /// relay range, since the periodic 500ms relay only reaches in-range players at send time.
        /// </summary>
        private static readonly Dictionary<long, BoomboxSyncPacket> activeBoomboxesByCarrier = new Dictionary<long, BoomboxSyncPacket>();

        /// <summary>
        /// Per-receiver tracking of which carriers each player currently has "in range" (received).
        /// Used so we only resend a cached packet on rising edge (player crosses INTO range), not
        /// every server tick. Keyed by receiver entity id, value = set of carrier entity ids known.
        /// </summary>
        private static readonly Dictionary<long, HashSet<long>> boomboxInRangeByReceiver = new Dictionary<long, HashSet<long>>();

        /// <summary>
        /// Server tick handle for the boombox range-entry / cleanup loop.
        /// </summary>
        private long boomboxServerTickId = 0;

        public override void StartServerSide(ICoreServerAPI api)
        {
            serverApi = api;

            // Detect Carry On mod on server side (needed for boombox itemstack position updates)
            if (!carryOnModLoaded)
            {
                carryOnModLoaded = api.ModLoader.Mods.Any(m => m.Info.ModID.Equals("carryon", StringComparison.OrdinalIgnoreCase));
                if (carryOnModLoaded)
                {
                    api.Logger.Notification("[SoundPhysicsAdapted] Server: Carry On mod detected - boombox itemstack sync enabled");
                }
            }

            // Channel + message types already registered in Start().
            // Only get the channel reference and set handlers here — do NOT re-register
            // message types, as duplicate RegisterMessageType calls can shift packet indices
            // and cause server/client mismatch (handshake packets silently dropped).
            ServerChannel = api.Network.GetChannel("soundphysicsadapted");
            ServerChannel.SetMessageHandler<ResonatorSyncPacket>(OnResonatorSyncPacket);
            ServerChannel.SetMessageHandler<BoomboxSyncPacket>(OnBoomboxSyncPacket);

            // Apply server-side Harmony patches for resonator interaction
            // This ensures OnInteract prefix fires on the server too (critical for multiplayer)
            // Only apply if enabled in config
            serverHarmony = new Harmony(HARMONY_ID + ".server");

            if (config.EnableResonatorFix)
            {
                ResonatorPatches.ApplyShared(serverHarmony, api);
            }
            else
            {
                api.Logger.Notification("[SoundPhysicsAdapted] Server resonator patches DISABLED by config");
            }

            // Always apply persistence patches on server (ToTreeAttributes/FromTreeAttributes)
            // These are normally applied via PatchAll in StartClientSide, but PatchAll cannot
            // run on the server because AudioLoaderPatch targets client-only OggDecoder type.
            ResonatorPatches.ApplyServer(serverHarmony, api);

            // Send handshake to clients when they join
            api.Event.PlayerJoin += (byPlayer) =>
            {
                ServerChannel.SendPacket(new ServerHandshakePacket { ModVersion = Mod.Info.Version }, byPlayer);
                api.Logger.Debug($"[SoundPhysicsAdapted] Sent handshake to {byPlayer.PlayerName}");

                // Sync any currently-active carried boomboxes to the joiner so they hear them
                // immediately, regardless of distance. The remote handler already drift-syncs
                // PlaybackPosition based on what we send here.
                try
                {
                    if (activeBoomboxesByCarrier.Count > 0 && byPlayer?.Entity != null)
                    {
                        // Snapshot to avoid mutation-during-enumeration if a packet arrives mid-loop
                        var snapshot = activeBoomboxesByCarrier.Values.ToArray();
                        int sent = 0;
                        foreach (var pkt in snapshot)
                        {
                            // Don't echo a carrier's own boombox to themselves
                            if (pkt.CarrierEntityId == byPlayer.Entity.EntityId) continue;
                            ServerChannel.SendPacket(pkt, byPlayer);
                            sent++;
                        }
                        if (sent > 0)
                            api.Logger.Debug($"[SoundPhysicsAdapted] Boombox join-sync: sent {sent} active carrier states to {byPlayer.PlayerName}");
                    }
                }
                catch (Exception ex)
                {
                    api.Logger.Warning($"[SoundPhysicsAdapted] Boombox join-sync failed for {byPlayer.PlayerName}: {ex.Message}");
                }
            };

            // Drop carrier from cache when they disconnect (otherwise stale state lingers
            // and gets pushed to every future joiner).
            api.Event.PlayerDisconnect += (byPlayer) =>
            {
                if (byPlayer?.Entity == null) return;
                long eid = byPlayer.Entity.EntityId;
                if (activeBoomboxesByCarrier.Remove(eid) && serverApi != null)
                {
                    serverApi.Logger.Debug($"[SoundPhysicsAdapted] Boombox cache: removed disconnected carrier {byPlayer.PlayerName} ({eid})");
                }
                boomboxInRangeByReceiver.Remove(eid);
                // Also forget this player as a receiver in everyone else's range sets — not
                // strictly needed since lookups are keyed by receiver, but keeps memory clean.
            };

            // Periodic boombox range-entry tick: when a player crosses INTO BOOMBOX_RELAY_RANGE
            // of an active carrier, push the cached packet to them once. This covers chunk-load
            // and walking-into-range cases that the carrier's own 500ms relay misses (the relay
            // only reaches players in range AT send time).
            boomboxServerTickId = api.Event.RegisterGameTickListener(OnBoomboxRangeTick, 1000);
        }

        /// <summary>
        /// Server tick (~1s) that detects players newly entering boombox relay range
        /// and sends them the cached carrier state once on rising edge.
        /// </summary>
        private void OnBoomboxRangeTick(float dt)
        {
            if (serverApi == null || activeBoomboxesByCarrier.Count == 0) return;

            try
            {
                var allPlayers = serverApi.World.AllOnlinePlayers;
                // Build quick lookup of carrier entities so we can read their current position
                // without trusting the cached PosX/Y/Z which may be stale by up to 500ms.
                foreach (var kv in activeBoomboxesByCarrier)
                {
                    long carrierId = kv.Key;
                    var pkt = kv.Value;

                    // Locate carrier player. If they went offline without a clean disconnect
                    // event, drop the entry.
                    IServerPlayer carrierPlr = null;
                    for (int i = 0; i < allPlayers.Length; i++)
                    {
                        if (allPlayers[i]?.Entity?.EntityId == carrierId)
                        {
                            carrierPlr = allPlayers[i] as IServerPlayer;
                            break;
                        }
                    }
                    if (carrierPlr?.Entity == null) continue;

                    var carrierPos = carrierPlr.Entity.Pos.XYZ;

                    for (int i = 0; i < allPlayers.Length; i++)
                    {
                        var rcv = allPlayers[i] as IServerPlayer;
                        if (rcv == null || rcv == carrierPlr || rcv.Entity == null) continue;
                        if (rcv.ConnectionState != EnumClientState.Playing) continue;

                        long rcvId = rcv.Entity.EntityId;
                        double dist = rcv.Entity.Pos.XYZ.DistanceTo(carrierPos);
                        bool inRange = dist <= BOOMBOX_RELAY_RANGE;

                        if (!boomboxInRangeByReceiver.TryGetValue(rcvId, out var known))
                        {
                            known = new HashSet<long>();
                            boomboxInRangeByReceiver[rcvId] = known;
                        }

                        bool wasInRange = known.Contains(carrierId);

                        if (inRange && !wasInRange)
                        {
                            // Rising edge — push cached packet so they pick up the music now
                            // instead of waiting for the next 500ms carrier relay tick.
                            ServerChannel.SendPacket(pkt, rcv);
                            known.Add(carrierId);
                        }
                        else if (!inRange && wasInRange)
                        {
                            known.Remove(carrierId);
                        }
                    }
                }
            }
            catch (Exception ex)
            {
                serverApi?.Logger.Warning($"[SoundPhysicsAdapted] Boombox range-entry tick failed: {ex.Message}");
            }
        }

        // === SERVER-SIDE PACKET VALIDATION ===
        // Client packets are untrusted input in multiplayer. Without these checks a
        // modified client could grow the pos-keyed dictionaries without bound, pause
        // resonators anywhere on the map, or relay arbitrary strings to nearby clients
        // as an AssetLocation for LoadSound.
        private const double RESONATOR_SYNC_MAX_DIST = 12.0;  // blocks; reach is ~5, auto-pause target is near the player
        private const double BOOMBOX_SYNC_MAX_DIST = 16.0;    // blocks; carrier moves while playing
        private const int RESONATOR_SYNC_MAX_ENTRIES = 512;   // cap on the pos-keyed stores
        private const long PACKET_MIN_INTERVAL_MS = 200;      // per-player rate floor (~2 Hz senders unaffected)
        private static readonly Dictionary<string, long> packetLastMsByPlayer = new Dictionary<string, long>();

        /// <summary>Per-player, per-packet-type rate limit. True = accept the packet.
        /// Separate buckets: a playing boombox relays at ~2 Hz and must not eat the
        /// resonator's budget (or vice versa).</summary>
        private static bool AcceptPacketRate(IServerPlayer player, string packetKind)
        {
            long now = Environment.TickCount64;
            string key = packetKind + ":" + player.PlayerUID;
            if (packetLastMsByPlayer.TryGetValue(key, out long last) && now - last < PACKET_MIN_INTERVAL_MS)
            {
                return false;
            }
            packetLastMsByPlayer[key] = now;
            return true;
        }

        /// <summary>
        /// Track strings are relayed to every nearby client and fed to AssetLocation /
        /// LoadSound there. VS asset codes are lowercase alphanumerics plus :/._- —
        /// anything else never came from a legit client.
        /// </summary>
        private static bool ValidTrackLocation(string loc)
        {
            if (string.IsNullOrEmpty(loc)) return true; // empty = "stopped playing", legitimate
            if (loc.Length > 256) return false;
            foreach (char c in loc)
            {
                bool ok = (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9')
                          || c == ':' || c == '/' || c == '.' || c == '_' || c == '-';
                if (!ok) return false;
            }
            return true;
        }

        private void OnResonatorSyncPacket(IServerPlayer player, ResonatorSyncPacket packet)
        {
            if (player?.Entity?.World?.BlockAccessor == null || packet?.Pos == null) return;

            if (!AcceptPacketRate(player, "resonator")) return;

            // Trust boundary: the sender must be near the resonator they claim to sync.
            var resonatorCenter = new Vec3d(packet.Pos.X + 0.5, packet.Pos.Y + 0.5, packet.Pos.Z + 0.5);
            double dist = player.Entity.Pos.XYZ.DistanceTo(resonatorCenter);
            if (dist > RESONATOR_SYNC_MAX_DIST)
            {
                player.Entity.World.Logger.Debug(
                    $"[SoundPhysicsAdapted] Rejected resonator sync from {player.PlayerName}: {dist:F0} blocks from {packet.Pos}");
                return;
            }

            // Bound the pos-keyed stores: a hostile client must not be able to grow
            // them without bound. Known positions keep updating; new ones need room.
            if (ResonatorPatches.serverPositionsByPos.Count >= RESONATOR_SYNC_MAX_ENTRIES
                && !ResonatorPatches.serverPositionsByPos.ContainsKey(packet.Pos))
            {
                player.Entity.World.Logger.Warning(
                    $"[SoundPhysicsAdapted] Resonator sync store full ({RESONATOR_SYNC_MAX_ENTRIES}) — dropping sync for {packet.Pos}");
                return;
            }

            // ALWAYS store by BlockPos first - this survives chunk reload
            // The weak table entries are lost when chunk unloads (instance destroyed)
            ResonatorPatches.serverPositionsByPos[packet.Pos.Copy()] = packet.PlaybackPosition;
            ResonatorPatches.serverPausedByPos[packet.Pos.Copy()] = packet.IsPaused;
            ResonatorPatches.serverRotationsByPos[packet.Pos.Copy()] = packet.FrozenRotation;

            if (SoundPhysicsAdaptedModSystem.IsDebugEnabled)
                player.Entity.World.Logger.Debug($"[SoundPhysicsAdapted] Server received sync: pos={packet.Pos}, position={packet.PlaybackPosition:F2}s, isPaused={packet.IsPaused}, rotation={packet.FrozenRotation:F2}");

            BlockEntity be = player.Entity.World.BlockAccessor.GetBlockEntity(packet.Pos);
            if (be is BlockEntityResonator resonator)
            {
                // Also update weak table for current instance (used during same session)
                ResonatorPatches.savedPositions.Remove(resonator);
                ResonatorPatches.savedPositions.Add(resonator, new PlaybackPosition(packet.PlaybackPosition));

                // Update paused state for persistence
                ResonatorPatches.pausedStates.Remove(resonator);
                ResonatorPatches.pausedStates.Add(resonator, new PausedState(packet.IsPaused));

                // If a client auto-paused this resonator (because they started another one),
                // the server's OnInteractPrefix won't have run for this resonator and IsPlaying
                // is still true. Apply the IsPaused=true intent here. We gate on the explicit
                // RequestServerAutoPause flag so a regular Ctrl+RMB pause (which DOES run server
                // OnInteract) doesn't double-toggle and accidentally restart playback.
                if (packet.RequestServerAutoPause && packet.IsPaused && resonator.IsPlaying)
                {
                    try
                    {
                        resonator.IsPlaying = false;
                        HarmonyLib.AccessTools.Method(typeof(BlockEntityResonator), "StopMusic")?.Invoke(resonator, null);
                        resonator.MarkDirty(true);
                        player.Entity.World.Logger.Debug($"[SoundPhysicsAdapted] Server applied auto-pause for {packet.Pos} from client {player.PlayerName}");
                    }
                    catch (Exception ex)
                    {
                        player.Entity.World.Logger.Warning($"[SoundPhysicsAdapted] Server auto-pause apply failed at {packet.Pos}: {ex.Message}");
                    }
                }
            }
        }

        /// <summary>
        /// Server relay for boombox sync: forward to nearby players (except sender).
        /// </summary>
        private void OnBoomboxSyncPacket(IServerPlayer sender, BoomboxSyncPacket packet)
        {
            if (sender?.Entity == null || serverApi == null) return;

            if (!AcceptPacketRate(sender, "boombox")) return;

            var senderPos = sender.Entity.Pos.XYZ;

            // Trust boundary: the sender must be near the carrier position it reports.
            var claimedPos = new Vec3d(packet.PosX, packet.PosY, packet.PosZ);
            if (senderPos.DistanceTo(claimedPos) > BOOMBOX_SYNC_MAX_DIST)
            {
                serverApi.Logger.Debug(
                    $"[SoundPhysicsAdapted] Rejected boombox sync from {sender.PlayerName}: {senderPos.DistanceTo(claimedPos):F0} blocks from reported carrier");
                return;
            }

            // The track string reaches every nearby client and is fed to
            // AssetLocation/LoadSound there. Reject anything that is not a VS asset code.
            if (!ValidTrackLocation(packet.TrackLocation))
            {
                serverApi.Logger.Debug(
                    $"[SoundPhysicsAdapted] Rejected boombox sync from {sender.PlayerName}: malformed track location '{packet.TrackLocation}'");
                return;
            }

            long carrierId = sender.Entity.EntityId;

            // Maintain the active-carrier cache used by join-sync and range-entry sync.
            // IsPlaying=false is sent on placement / drop; remove the entry then so we
            // don't keep replaying a stopped boombox to future joiners.
            if (packet.IsPlaying)
            {
                // Defensive: ensure the cached packet always carries the correct carrier id
                // even if a buggy client sent 0 (matches what receivers expect).
                if (packet.CarrierEntityId == 0) packet.CarrierEntityId = carrierId;
                activeBoomboxesByCarrier[carrierId] = packet;
            }
            else
            {
                activeBoomboxesByCarrier.Remove(carrierId);
                // Forget receivers' "in range" memory for this carrier so a future pickup
                // re-triggers the rising-edge push.
                foreach (var set in boomboxInRangeByReceiver.Values) set.Remove(carrierId);
            }

            var allPlayers = serverApi.World.AllOnlinePlayers;
            int relayCount = 0;

            for (int i = 0; i < allPlayers.Length; i++)
            {
                var plr = allPlayers[i] as IServerPlayer;
                if (plr == null || plr == sender || plr.Entity == null) continue;

                double dist = plr.Entity.Pos.XYZ.DistanceTo(senderPos);
                if (dist <= BOOMBOX_RELAY_RANGE)
                {
                    ServerChannel.SendPacket(packet, plr);
                    relayCount++;

                    // Mark this receiver as currently knowing about this carrier so the
                    // periodic range-entry tick doesn't double-send.
                    if (packet.IsPlaying)
                    {
                        long rcvId = plr.Entity.EntityId;
                        if (!boomboxInRangeByReceiver.TryGetValue(rcvId, out var known))
                        {
                            known = new HashSet<long>();
                            boomboxInRangeByReceiver[rcvId] = known;
                        }
                        known.Add(carrierId);
                    }
                }
            }

            // Per-relay packet log — 2 Hz per playing boombox in normal play, so it
            // stays behind the debug gate instead of flooding the server log.
            if (SoundPhysicsAdaptedModSystem.IsDebugEnabled)
                serverApi.Logger.Debug($"[SoundPhysicsAdapted] Boombox relay: {sender.PlayerName} playing={packet.IsPlaying} track={packet.TrackLocation} pos=({packet.PosX:F0},{packet.PosY:F0},{packet.PosZ:F0}) relayed to {relayCount} players, cache={activeBoomboxesByCarrier.Count}");

            // Sync the playback position to the carrier's Itemstack so that when the boombox
            // is placed down, it starts from the correct position.
            UpdateCarrierItemStackPosition(sender.Entity, packet.PlaybackPosition);
        }

        /// <summary>
        /// Update the saved playback position on the carrier's Itemstack while they are carrying it.
        /// </summary>
        private void UpdateCarrierItemStackPosition(Entity carrier, float playbackPosition)
        {
            if (carrier == null || !carryOnModLoaded) return;
            
            try
            {
                var carriedAttr = carrier.WatchedAttributes.GetTreeAttribute("carryon:Carried");
                var carriedDataAttr = carrier.Attributes.GetTreeAttribute("carryon:Carried");
                if (carriedAttr == null && carriedDataAttr == null) return;
                
                bool updated = false;

                // Check Hands slot first
                if (UpdateSlotPlaybackPosition(carrier, carriedAttr, carriedDataAttr, "Hands", playbackPosition))
                {
                    updated = true;
                }
                // Check Back slot
                else if (UpdateSlotPlaybackPosition(carrier, carriedAttr, carriedDataAttr, "Back", playbackPosition))
                {
                    updated = true;
                }

                if (updated)
                {
                    // Force the attribute to sync
                    carrier.WatchedAttributes.MarkPathDirty("carryon:Carried");
                }
            }
            catch (Exception ex)
            {
                serverApi?.Logger.Warning($"[SoundPhysicsAdapted] Error updating carrier itemstack position: {ex.Message}");
            }
        }

        private bool UpdateSlotPlaybackPosition(Entity carrier, ITreeAttribute carriedAttr, ITreeAttribute carriedDataAttr, string slotName, float playbackPosition)
        {
            var slotAttr = carriedAttr?.GetTreeAttribute(slotName);
            if (slotAttr == null) return false;

            var stack = slotAttr.GetItemstack("Stack");
            if (stack == null) return false;

            // Resolve the block to check if it's a resonator
            stack.ResolveBlockOrItem(carrier.World);
            if (stack.Block == null || !(stack.Block.Code?.Path?.Contains("resonator") == true)) return false;

            // Found a resonator. Update its savedPlaybackPos in the block entity data.
            stack.Attributes.SetFloat("savedPlaybackPos", playbackPosition);
            stack.Attributes.SetBool("isPaused", false);
            
            // Set the modified stack back to the tree
            slotAttr.SetItemstack("Stack", stack);

            var dataSlotAttr = carriedDataAttr?.GetTreeAttribute(slotName);
            var blockEntityData = dataSlotAttr?.GetTreeAttribute("Data");
            if (blockEntityData != null)
            {
                blockEntityData.SetFloat("savedPlaybackPos", playbackPosition);
                blockEntityData.SetBool("isPaused", false);
            }

            return true;
        }

        private void OnServerHandshake(ServerHandshakePacket packet)
        {
            ResonatorPatches.ServerHasMod = true;
            clientApi?.Logger.Notification($"[SoundPhysicsAdapted] Server has mod v{packet.ModVersion} — resonator pause/resume enabled.");
        }

        // Cleanup timer
        private long cleanupTimerId = 0;
        private const float CLEANUP_INTERVAL_SEC = 1.0f;

        // Occlusion update timer - AcousticsManager handles interval logic internally
        private long occlusionUpdateTimerId = 0;
        private const float OCCLUSION_UPDATE_INTERVAL_MS = 50f; // 20 times per second

        // Smoothing tick - decoupled from raycast, runs fast for all sounds
        private long smoothingTimerId = 0;

        public override void StartClientSide(ICoreClientAPI api)
        {
            base.StartClientSide(api);
            clientApi = api;
            // Channel + message types already registered in Start().
            // Do NOT re-register — duplicate RegisterMessageType shifts packet indices.
            ClientChannel = api.Network.GetChannel("soundphysicsadapted");

            // Listen for server handshake — confirms server has the mod
            ClientChannel.SetMessageHandler<ServerHandshakePacket>(OnServerHandshake);

            // Listen for boombox sync from other players carrying resonators
            ClientChannel.SetMessageHandler<BoomboxSyncPacket>(BoomboxRemoteHandler.OnBoomboxSyncReceived);
            BoomboxRemoteHandler.Initialize(api);

            // In singleplayer, client and server share the same process
            // so the server-side patches already cover both sides.
            // Set the flag immediately for SP.
            if (api.IsSinglePlayer)
            {
                ResonatorPatches.ServerHasMod = true;
            }
            
            // Detect Carry On mod - it hijacks Shift+RMB for block pickup, conflicting with our resonator pause/resume
            carryOnModLoaded = api.ModLoader.Mods.Any(m => m.Info.ModID.Equals("carryon", StringComparison.OrdinalIgnoreCase));
            if (carryOnModLoaded)
            {
                api.Logger.Notification("[SoundPhysicsAdapted] Carry On mod detected - resonator pause/resume changed to Ctrl+RMB");
            }

            // Detect Surround Sound mod - replaces vanilla weather OGGs with 5.1 surround (6ch).
            // Our N-channel MonoDownmixManager handles the 6ch->mono conversion for positional sources.
            // Their experimental RainEmitterSystem may cause double positional rain alongside Phase 5B.
            surroundSoundModLoaded = api.ModLoader.IsModEnabled("vintagestorysurroundsound");
            if (surroundSoundModLoaded)
            {
                api.Logger.Notification("[SoundPhysicsAdapted] Surround Sound mod detected - weather audio may be 5.1 surround, N-channel mono downmix active");
                api.Logger.Warning("[SoundPhysicsAdapted] If Surround Sound's experimental rain emitters are enabled alongside SPA positional weather, double rain audio may occur. Disable one system for best results.");
            }

            // Apply Harmony patches (client-side only - sounds are client-side)
            // Using manual patching since ClientMain is internal to VintagestoryLib
            try
            {
                harmony = new Harmony(HARMONY_ID);

                // Phase 1: Occlusion patches (manual - targets internal types)
                LoadSoundPatch.ApplyPatches(harmony, api);

                // Resonator patches (consolidated - logic, audio, networking)
                // Only apply if enabled in config
                if (config.EnableResonatorFix)
                {
                    // Carry On compatibility: Boombox feature
                    // MUST be applied BEFORE ResonatorPatches so its StopMusicPrefix runs first
                    // (checks pausingResonators before ResonatorPatches clears it)
                    if (carryOnModLoaded)
                    {
                        CarryOnCompatPatches.ApplyPatches(harmony, api);
                    }

                    ResonatorPatches.ApplyShared(harmony, api);
                    ResonatorPatches.ApplyClient(harmony, api);
                }
                else
                {
                    api.Logger.Notification("[SoundPhysicsAdapted] Resonator enhancements DISABLED by config");
                }

                // Phase 3: Reverb patches (disable vanilla, enable our system)
                ReverbPatch.ApplyPatches(harmony, api);

                // Phase 5A: Weather sound suppression patches
                WeatherSoundPatches.ApplyPatches(harmony, api);

                // Ambient sound bbox face-sampling patches (beehive/water occlusion fix)
                AmbientSoundPatches.ApplyPatches(harmony, api);

                // Block ambient injection: rain surface impacts + torch ambient
                // Patches GetAmbientSoundStrength to control when injected sounds play
                BlockAmbientInjector.ApplyPatches(harmony, api);
            }
            catch (Exception ex)
            {
                api.Logger.Error("[SoundPhysicsAdapted] Failed to apply manual Harmony patches: " + ex.Message);
                api.Logger.Error("[SoundPhysicsAdapted] Stack: " + ex.StackTrace);
            }

            // Attribute-based patches (AudioLoaderPatch etc.) - isolated so failures
            // here can't block the manual patches above
            try
            {
                harmony.PatchAll(Assembly.GetExecutingAssembly());
            }
            catch (Exception ex)
            {
                api.Logger.Warning($"[SoundPhysicsAdapted] PatchAll failed (non-critical): {ex.Message}");
            }

            // Block ambient injection is deferred to LevelFinalize (below)
            // because api.World.Blocks is empty during StartClientSide on servers.

            // Note: Universal mono downmix is handled by MonoDownmixManager +
            // LoadSoundPatch.StartPlayingAudioMonoPrefix (auto-detects positional stereo sounds)
            // and LoadSoundPatch.LoadSoundMonoPrefix (explicit requests from weather/resonator)

            // Initialize AudioPhysicsSystem (optimization: time-slicing, sky probe, static cache)
            acousticsManager = new AudioPhysicsSystem();

            // Initialize sound playback throttle (limits concurrent OpenAL sources)
            soundThrottle = new SoundPlaybackThrottle();

            // Register periodic cleanup for disposed sounds
            if (AudioRenderer.IsInitialized)
            {
                cleanupTimerId = api.Event.RegisterGameTickListener(OnCleanupTick, (int)(CLEANUP_INTERVAL_SEC * 1000));
                occlusionUpdateTimerId = api.Event.RegisterGameTickListener(OnOcclusionUpdateTick, (int)OCCLUSION_UPDATE_INTERVAL_MS);
                smoothingTimerId = api.Event.RegisterGameTickListener(OnSmoothingTick, (int)AudioRenderer.SmoothTickIntervalMs);
                api.Logger.Debug("[SoundPhysicsAdapted] Registered cleanup, occlusion, and smoothing tick handlers");

                _diagLastHeartbeatLogMs = api.ElapsedMilliseconds;

                // Optimization: Invalidate cache on block changes
                api.Event.BlockChanged += OnBlockChanged;
                api.Logger.Debug("[SoundPhysicsAdapted] Hooked BlockChanged event");
            }

            // WORLD READINESS: Defer all heavy processing until LevelFinalize.
            // The block accessor is incomplete/slow before this fires, causing 100s+ freezes
            // in DDA raycasts. player != null is NOT sufficient — entity exists before chunks load.
            api.Event.LevelFinalize += () =>
            {
                _worldReady = true;
                _warmupTicksRemaining = WARMUP_TICKS;
                api.Logger.Notification("[SoundPhysicsAdapted] World ready — warmup started, raycasting deferred");

                // Block ambient injection: inject Sounds.Ambient onto matching block types.
                // Must run here (not StartClientSide) because api.World.Blocks is empty on
                // multiplayer servers until blocks are received from the server.
                BlockAmbientInjector.InjectAmbientSounds(api);

                // DIAGNOSTIC: Dump beehive entries from soundAudioData after a delay.
                // Debug-gated: it walks the whole soundAudioData dictionary via
                // reflection + dynamic, which ran on EVERY world join regardless of
                // DebugMode and stalled joins on mod-heavy installs.
                if (config.DebugMode)
                {
                    long diagId = 0;
                    diagId = api.Event.RegisterGameTickListener((float dt) =>
                    {
                        api.Event.UnregisterGameTickListener(diagId);
                        DumpBeehiveSoundDiag(api);
                    }, 3000); // 3 second delay to let CatalogSounds finish
                }
            };

            // Phase 3: Initialize reverb effect system
            if (config.EnableCustomReverb)
            {
                if (ReverbEffects.Initialize())
                {
                    api.Logger.Notification("[SoundPhysicsAdapted] Reverb effects initialized");
                }
                else
                {
                    api.Logger.Warning("[SoundPhysicsAdapted] Reverb effects initialization failed - reverb disabled");
                    config.EnableCustomReverb = false;
                }
            }

            // Phase 5A: Initialize weather audio manager
            if (config.EnableWeatherEnhancement && WeatherSoundPatches.PatchesApplied)
            {
                weatherManager = new WeatherAudioManager(api);
                if (weatherManager.Initialize())
                {
                    weatherTimerId = api.Event.RegisterGameTickListener(OnWeatherTick, config.WeatherTickIntervalMs);
                    api.Logger.Notification("[SoundPhysicsAdapted] Weather audio system initialized");
                }
                else
                {
                    api.Logger.Warning("[SoundPhysicsAdapted] Weather audio initialization failed");
                    weatherManager = null;
                }
            }

            // Initialize debug visualization (IRenderer wireframe)
            debugViz = new DebugVisualization(api);

            // Register debug commands
            RegisterCommands(api);

            string reverbStatus = config.EnableCustomReverb
                ? (ReverbPatch.VanillaReverbDisabled ? "SPR-style reverb ENABLED (vanilla disabled)" : "Reverb enabled (vanilla NOT disabled)")
                : "Reverb disabled";
            api.Logger.Notification($"[SoundPhysicsAdapted] Initialized - Occlusion enabled, {reverbStatus}");
        }

        // === Master toggle lifecycle ===
        // Last state of config.Enabled that we actually acted on. null = nothing applied
        // yet (startup), so the first observation only records the state.
        private static bool? appliedEnabledState = null;

        /// <summary>
        /// Detect a change of the master toggle and run the matching transition once.
        ///
        /// The per-tick guards elsewhere only stop NEW work. They cannot undo the OpenAL
        /// state already written to sounds that are playing right now, so the OFF edge
        /// needs an explicit restore.
        /// </summary>
        private void SyncEnabledState()
        {
            if (config == null) return;

            bool nowEnabled = config.Enabled;
            if (appliedEnabledState == nowEnabled) return;

            bool firstObservation = appliedEnabledState == null;
            appliedEnabledState = nowEnabled;

            // Startup: nothing of ours is applied yet, so there is nothing to undo.
            if (firstObservation) return;

            if (nowEnabled) ReArmAfterToggle();
            else RestoreVanillaState();
        }

        /// <summary>
        /// Give the game back to vanilla audio. Undoes every per-source change we made
        /// to sounds that are playing now; the suppression patches stand down on their
        /// own because they all read config.Enabled.
        /// </summary>
        private void RestoreVanillaState()
        {
            int sources = AudioRenderer.RestoreAllToVanilla();
            int distanceOverrides = LoadSoundPatch.RestoreVanillaDistanceModel();

            // Our replacement weather/thunder sounds must stop, and the patches that
            // zero the vanilla loops now let VS control its own volumes again.
            weatherManager?.StopAllReplacements();

            // New sounds load as vanilla stereo again. Buffers already downmixed to
            // mono stay mono until the game reloads that asset.
            MonoDownmixManager.ClearCache();

            acousticsManager?.CellCache?.Clear();
            OcclusionCalculator.ClearCache();
            soundThrottle?.Clear();

            clientApi?.Logger.Notification(
                $"[SoundPhysicsAdapted] Master toggle OFF — vanilla audio restored " +
                $"({sources} live sources cleared, {distanceOverrides} distance overrides reverted). " +
                $"Sound-file overrides and injected block ambients are applied at asset load and stay until restart.");
        }

        /// <summary>
        /// Resume our processing. The ticks compute real values again within one raycast
        /// interval; this only puts our filter objects back and drops stale geometry
        /// caches so the first result reflects the world as it is now.
        /// </summary>
        private void ReArmAfterToggle()
        {
            OcclusionCalculator.ClearCache();
            acousticsManager?.CellCache?.Clear();

            int reattached = AudioRenderer.ReattachAllFilters();

            // The weather system is skipped at startup when the master toggle is off.
            // Initialize is guarded against a second run, so this is safe either way.
            if (weatherManager != null && config.EnableWeatherEnhancement)
            {
                weatherManager.Initialize();
            }

            clientApi?.Logger.Notification(
                $"[SoundPhysicsAdapted] Master toggle ON — occlusion, reverb and weather resume ({reattached} sources re-armed).");
        }

        /// <summary>
        /// Periodic cleanup of disposed sound filters
        /// </summary>
        private void OnCleanupTick(float dt)
        {
            _diagCleanupTickCount++;
            AudioRenderer.CleanupDisposed();
        }

        /// <summary>
        /// Fast 25ms tick - smooths all filter values toward their targets.
        /// Decoupled from raycast so convergence is consistent regardless of distance.
        /// </summary>
        private void OnSmoothingTick(float dt)
        {
            // Runs BEFORE the enabled guard: a toggle from any source (chat command,
            // ConfigLib GUI, config reload) must trigger the transition exactly once.
            SyncEnabledState();

            if (!config.Enabled || !AudioRenderer.IsInitialized)
                return;

            // Warmup countdown: burns down after LevelFinalize, ensures game loop is
            // actually ticking before we start raycasting. Prevents freeze when
            // hundreds of async-loaded sounds trigger Start() during the first few frames.
            if (_warmupTicksRemaining > 0)
            {
                _warmupTicksRemaining--;
                if (_warmupTicksRemaining == 0)
                {
                    clientApi?.Logger.Notification("[SoundPhysicsAdapted] Warmup complete — occlusion/reverb processing enabled");

                    // Retroactively process sounds that started during warmup (querns, forges, etc.)
                    // These were queued because SoundStartPrefix skipped them while IsWorldReady was false.
                    LoadSoundPatch.ProcessPreWarmupQueue();
                }
            }

            // FREEZE DIAGNOSTIC: Track frame intervals via this 25ms tick
            if (_diagFpsStopwatch.IsRunning)
            {
                double frameMs = _diagFpsStopwatch.Elapsed.TotalMilliseconds;
                _diagFrameTimeSum += frameMs;
                _diagFrameCount++;
                if (frameMs > _diagFrameTimeMax) _diagFrameTimeMax = frameMs;
            }
            _diagFpsStopwatch.Restart();

            // FREEZE DIAGNOSTIC: Time SmoothAll
            _diagStopwatch.Restart();
            // The listener position feeds the slew ceiling only: a far sound goes quiet
            // over a wider shadow boundary, so it converges slower. Same ear position the
            // occlusion tick measures from.
            var smoothPlayer = clientApi?.World?.Player?.Entity;
            Vec3d listenerPos = smoothPlayer != null
                ? smoothPlayer.Pos.XYZ.Add(smoothPlayer.LocalEyePos)
                : null;
            AudioRenderer.SmoothAll(clientApi?.World?.ElapsedMilliseconds ?? 0L, listenerPos);
            _diagStopwatch.Stop();
            double smoothMs = _diagStopwatch.Elapsed.TotalMilliseconds;
            _diagSmoothTickCount++;
            _diagSmoothTotalMs += smoothMs;
            if (smoothMs > _diagSmoothMaxMs) _diagSmoothMaxMs = smoothMs;

            // Heartbeat: log stats every 5s (DebugMode only — gated in DiagnosticLog)
            EmitDiagnosticHeartbeat();
        }

        /// <summary>
        /// Phase 5A: Update weather audio (~100ms tick).
        /// Reads VS weather state, applies LPF to replacement sounds.
        /// </summary>
        private void OnWeatherTick(float dt)
        {
            if (!config.Enabled || !config.EnableWeatherEnhancement)
                return;

            weatherManager?.OnGameTick(dt);
        }

        /// <summary>
        /// Recalculate occlusion for sounds using AudioPhysicsSystem.
        /// All sounds checked every tick; raycast gated by distance-based intervals.
        /// </summary>
        /// <summary>
        /// Gives the main-thread block accessor with an empty chunk cache.
        /// Call it at the start of a scan and use the result for that scan only.
        /// Every main-thread scan shares this one instance, because the game runs the
        /// tick listeners one after the other on that thread.
        /// See the comment on <see cref="tickBlockAccessor"/> for why the cache exists.
        /// </summary>
        internal static IBlockAccessor BeginTickBlockAccess()
        {
            var world = clientApi?.World;
            if (world == null) return null;

            tickBlockAccessor ??= world.GetCachingBlockAccessor(false, false);
            tickBlockAccessor.Begin();
            return tickBlockAccessor;
        }

        private void OnOcclusionUpdateTick(float dt)
        {
            if (!config.Enabled || !IsWorldReady || clientApi?.World?.Player?.Entity == null)
                return;

            // Always update underwater state
            UpdateUnderwaterState();

            var player = clientApi.World.Player.Entity;
            Vec3d currentPos = player.Pos.XYZ.Add(player.LocalEyePos);

            // FREEZE DIAGNOSTIC: Time the full occlusion update
            _diagStopwatch.Restart();

            // AudioPhysicsSystem: all sounds every tick, raycast gated by distance intervals
            long currentTimeMs = clientApi.World.ElapsedMilliseconds;
            acousticsManager?.Update(currentPos, BeginTickBlockAccess(), currentTimeMs);

            _diagStopwatch.Stop();
            double occMs = _diagStopwatch.Elapsed.TotalMilliseconds;
            _diagOcclusionTickCount++;
            _diagOcclusionTotalMs += occMs;
            if (occMs > _diagOcclusionMaxMs) _diagOcclusionMaxMs = occMs;

            // Warn immediately if a single tick takes >50ms
            if (occMs > 50.0)
            {
                DiagnosticLog($"DIAG-SLOW: OcclusionTick took {occMs:F1}ms! filters={AudioRenderer.ActiveFilterCount}");
            }
        }

        private void RegisterCommands(ICoreClientAPI api)
        {
            api.ChatCommands.Create("soundphysics")
                .WithRootAlias("sp")
                .WithDescription("Sound Physics Adapted commands")
                .BeginSubCommand("debug")
                    .WithDescription("Toggle master debug mode (gates all sub-debug flags)")
                    .HandleWith((args) =>
                    {
                        config.DebugMode = !config.DebugMode;
                        api.StoreModConfig(config, "soundphysicsadapted.json");
                        string status = config.DebugMode
                            ? $"[SoundPhysicsAdapted] Debug mode: ON\n" +
                              $"  Sub-debug flags (edit config or use commands):\n" +
                              $"  Occlusion: {(config.DebugOcclusion ? "ON" : "off")}\n" +
                              $"  Reverb: {(config.DebugReverb ? "ON" : "off")}\n" +
                              $"  SoundPaths: {(config.DebugSoundPaths ? "ON" : "off")}\n" +
                              $"  Weather: {(config.DebugWeather ? "ON" : "off")}\n" +
                              $"  WeatherViz: {(config.DebugWeatherVisualization ? "ON" : "off")}\n" +
                              $"  PositionalWeather: {(config.DebugPositionalWeather ? "ON" : "off")}\n" +
                              $"  Resonator: {(config.DebugResonator ? "ON" : "off")}\n" +
                              $"  Verbose: {(config.DebugVerbose ? "ON" : "off")}"
                            : "[SoundPhysicsAdapted] Debug mode: OFF (all sub-debug logging disabled)";
                        return TextCommandResult.Success(status);
                    })
                .EndSubCommand()
                .BeginSubCommand("status")
                    .WithDescription("Show current config")
                    .HandleWith((args) =>
                    {
                        return TextCommandResult.Success(
                            $"[SoundPhysicsAdapted] Config:\n" +
                            $"  Enabled: {config.Enabled}\n" +
                            $"  DebugMode: {config.DebugMode}\n" +
                            $"  MaxOcclusion: {config.MaxOcclusion}\n" +
                            $"  OcclusionPerBlock: {config.OcclusionPerSolidBlock}\n" +
                            $"  BlockAbsorption: {config.BlockAbsorption}\n" +
                            $"  PermeationBase: {config.PermeationBase}\n" +
                            $"  PermeationOccThreshold: {config.PermeationOcclusionThreshold}\n" +
                            $"  MaxDistance: (deprecated, using per-sound range)\n" +
                            $"  MinFilter: {config.MinLowPassFilter}\n" +
                            $"  OcclusionVariation: {config.OcclusionVariation} (0=strict, 0.35=soft)"
                        );
                    })
                .EndSubCommand()
                .BeginSubCommand("toggle")
                    .WithDescription("Enable/disable sound physics (disabled = vanilla audio)")
                    .HandleWith((args) =>
                    {
                        config.Enabled = !config.Enabled;
                        api.StoreModConfig(config, "soundphysicsadapted.json");

                        // Apply the transition now instead of waiting for the next tick,
                        // so the reply below is already true when the player reads it.
                        SyncEnabledState();

                        return TextCommandResult.Success(config.Enabled
                            ? "[SoundPhysicsAdapted] Sound physics: ENABLED"
                            : "[SoundPhysicsAdapted] Sound physics: DISABLED — vanilla audio restored");
                    })
                .EndSubCommand()
                .BeginSubCommand("set")
                    .WithDescription("Set config value: .soundphysics set <param> <value>")
                    .WithArgs(api.ChatCommands.Parsers.Word("param"), api.ChatCommands.Parsers.Float("value"))
                    .HandleWith((args) =>
                    {
                        string param = (string)args[0];
                        float value = (float)args[1];
                        
                        switch (param.ToLower())
                        {
                            case "maxocclusion":
                                config.MaxOcclusion = value;
                                break;
                            case "occlusionperblock":
                            case "occlusion":
                                config.OcclusionPerSolidBlock = value;
                                break;
                            case "absorption":
                            case "blockabsorption":
                                config.BlockAbsorption = value;
                                break;
                            case "maxdistance":
                            case "distance":
                                return TextCommandResult.Error("maxdistance is deprecated. Reverb attenuation now uses per-sound vanilla range automatically.");
                            case "minfilter":
                                config.MinLowPassFilter = value;
                                break;
                            case "maxrays":
                                return TextCommandResult.Error("maxrays is deprecated and no longer used.");
                            case "variation":
                            case "occlusionvariation":
                                config.OcclusionVariation = value;
                                break;
                            case "permeation":
                            case "permeationbase":
                                config.PermeationBase = value;
                                break;
                            case "permeationthreshold":
                            case "permthreshold":
                                config.PermeationOcclusionThreshold = value;
                                break;
                            default:
                                return TextCommandResult.Error($"Unknown param: {param}\nValid: maxocclusion, occlusionperblock, absorption, maxdistance, minfilter, maxrays, variation, permeation, permeationthreshold");
                        }
                        
                        api.StoreModConfig(config, "soundphysicsadapted.json");
                        config.RecalculateDerived();
                        return TextCommandResult.Success($"[SoundPhysicsAdapted] Set {param} = {value}");
                    })
                .EndSubCommand()
                .BeginSubCommand("reset")
                    .WithDescription("Reset config to defaults")
                    .HandleWith((args) =>
                    {
                        config = new SoundPhysicsConfig();
                        config.RecalculateDerived();
                        api.StoreModConfig(config, "soundphysicsadapted.json");
                        return TextCommandResult.Success("[SoundPhysicsAdapted] Config reset to defaults");
                    })
                .EndSubCommand()
                .BeginSubCommand("stats")
                    .WithDescription("Show filter statistics")
                    .HandleWith((args) =>
                    {
                        string filterStats = AudioRenderer.IsInitialized
                            ? AudioRenderer.GetStats()
                            : "Not initialized";
                        return TextCommandResult.Success(
                            $"[SoundPhysicsAdapted] Filter Stats:\n" +
                            $"  Per-sound filters: {(AudioRenderer.IsInitialized ? "ENABLED" : "DISABLED")}\n" +
                            $"  {filterStats}"
                        );
                    })
                .EndSubCommand()
                // Phase 3: Reverb commands
                .BeginSubCommand("reverb")
                    .WithDescription("Show current room reverb values")
                    .HandleWith((args) =>
                    {
                        if (!config.EnableCustomReverb)
                        {
                            return TextCommandResult.Success("[SoundPhysicsAdapted] Reverb is DISABLED");
                        }

                        var player = api.World?.Player?.Entity;
                        if (player == null)
                        {
                            return TextCommandResult.Error("[SoundPhysicsAdapted] Player not found");
                        }

                        Vec3d playerPos = player.Pos.XYZ.Add(player.LocalEyePos);
                        string roomStats = AcousticRaytracer.GetRoomStats(playerPos, api.World.BlockAccessor);

                        return TextCommandResult.Success(
                            $"[SoundPhysicsAdapted] {roomStats}\n" +
                            $"  ---\n" +
                            $"  Config: rays={config.ReverbRayCount}, bounces={config.ReverbBounces}, maxDist={config.ReverbMaxDistance}"
                        );
                    })
                .EndSubCommand()
                .BeginSubCommand("reverb-toggle")
                    .WithDescription("Toggle our reverb system")
                    .HandleWith((args) =>
                    {
                        config.EnableCustomReverb = !config.EnableCustomReverb;
                        api.StoreModConfig(config, "soundphysicsadapted.json");
                        return TextCommandResult.Success($"[SoundPhysicsAdapted] Reverb: {(config.EnableCustomReverb ? "ENABLED" : "DISABLED")}");
                    })
                .EndSubCommand()
                .BeginSubCommand("reverb-vanilla")
                    .WithDescription("Toggle vanilla reverb (for comparison)")
                    .HandleWith((args) =>
                    {
                        config.DisableVanillaReverb = !config.DisableVanillaReverb;
                        api.StoreModConfig(config, "soundphysicsadapted.json");
                        return TextCommandResult.Success($"[SoundPhysicsAdapted] Vanilla reverb: {(config.DisableVanillaReverb ? "DISABLED" : "ENABLED (for comparison)")}");
                    })
                .EndSubCommand()
                .BeginSubCommand("reverb-debug")
                    .WithDescription("Toggle reverb debug logging (requires debug mode)")
                    .HandleWith((args) =>
                    {
                        config.DebugReverb = !config.DebugReverb;
                        api.StoreModConfig(config, "soundphysicsadapted.json");
                        string gate = config.DebugMode ? "" : " (DebugMode is OFF — enable with /soundphysics debug)";
                        return TextCommandResult.Success($"[SoundPhysicsAdapted] Reverb debug: {(config.DebugReverb ? "ON" : "OFF")}{gate}");
                    })
                .EndSubCommand()
                .BeginSubCommand("occlusion-debug")
                    .WithDescription("Toggle occlusion debug logging (requires debug mode)")
                    .HandleWith((args) =>
                    {
                        config.DebugOcclusion = !config.DebugOcclusion;
                        api.StoreModConfig(config, "soundphysicsadapted.json");
                        string gate = config.DebugMode ? "" : " (DebugMode is OFF — enable with /soundphysics debug)";
                        return TextCommandResult.Success($"[SoundPhysicsAdapted] Occlusion debug: {(config.DebugOcclusion ? "ON" : "OFF")}{gate}");
                    })
                .EndSubCommand()
                .BeginSubCommand("debugpaths")
                    .WithDescription("Toggle sound path debug logging (requires debug mode)")
                    .HandleWith((args) =>
                    {
                        config.DebugSoundPaths = !config.DebugSoundPaths;
                        api.StoreModConfig(config, "soundphysicsadapted.json");
                        string gate = config.DebugMode ? "" : " (DebugMode is OFF — enable with /soundphysics debug)";
                        return TextCommandResult.Success($"[SoundPhysicsAdapted] Sound paths debug: {(config.DebugSoundPaths ? "ON" : "OFF")}{gate}");
                    })
                .EndSubCommand()
                .BeginSubCommand("acoustics")
                    .WithDescription("Show AudioPhysicsSystem optimization stats")
                    .HandleWith((args) =>
                    {
                        string stats = acousticsManager != null
                            ? acousticsManager.GetStats()
                            : "Not initialized";
                        return TextCommandResult.Success($"[SoundPhysicsAdapted] Acoustics: {stats}");
                    })
                .EndSubCommand()
                // Phase 5A: Weather commands
                .BeginSubCommand("weather")
                    .WithDescription("Show weather audio status")
                    .HandleWith((args) =>
                    {
                        string status = weatherManager != null
                            ? weatherManager.GetStatus()
                            : "Weather audio: NOT INITIALIZED (check EnableWeatherEnhancement in config)";
                        return TextCommandResult.Success($"[SoundPhysicsAdapted] {status}");
                    })
                .EndSubCommand()
                .BeginSubCommand("weather-toggle")
                    .WithDescription("Toggle weather audio enhancement")
                    .HandleWith((args) =>
                    {
                        config.EnableWeatherEnhancement = !config.EnableWeatherEnhancement;
                        api.StoreModConfig(config, "soundphysicsadapted.json");
                        if (!config.EnableWeatherEnhancement)
                        {
                            weatherManager?.OnGameTick(0); // Triggers StopAll path
                        }
                        return TextCommandResult.Success($"[SoundPhysicsAdapted] Weather enhancement: {(config.EnableWeatherEnhancement ? "ENABLED" : "DISABLED")}");
                    })
                .EndSubCommand()
                .BeginSubCommand("weather-debug")
                    .WithDescription("Toggle weather debug logging (requires debug mode)")
                    .HandleWith((args) =>
                    {
                        config.DebugWeather = !config.DebugWeather;
                        api.StoreModConfig(config, "soundphysicsadapted.json");
                        string gate = config.DebugMode ? "" : " (DebugMode is OFF — enable with /soundphysics debug)";
                        return TextCommandResult.Success($"[SoundPhysicsAdapted] Weather debug: {(config.DebugWeather ? "ON" : "OFF")}{gate}");
                    })
                .EndSubCommand()
                .BeginSubCommand("viz")
                    .WithDescription("Toggle debug visualizations.\n" +
                        "Modes: bounces | rays | occlusion | reposition | weather | openings | off\n" +
                        "bounces cycles: reflectivity \u2192 reverb slots \u2192 off\n" +
                        "No argument = show status of all modes")
                    .WithArgs(api.ChatCommands.Parsers.OptionalWord("mode"))
                    .HandleWith((args) =>
                    {
                        var viz = DebugVisualization.Instance;
                        if (viz == null)
                            return TextCommandResult.Error("[SPA] Visualization system not initialized");

                        string mode = (args.Parsers[0].IsMissing) ? null : (string)args[0];

                        if (mode == null)
                        {
                            string bounceLabel = viz.BounceColorMode switch
                            {
                                1 => "ON (reflectivity)",
                                2 => "ON (reverb slots)",
                                _ => "off"
                            };
                            return TextCommandResult.Success(
                                $"[SPA] Viz modes:\n" +
                                $"  bounces: {bounceLabel}\n" +
                                $"  rays: {(viz.ShowRays ? "ON" : "off")}\n" +
                                $"  occlusion: {(viz.ShowOcclusion ? "ON" : "off")}\n" +
                                $"  reposition: {(viz.ShowReposition ? "ON" : "off")}\n" +
                                $"  openings: {(viz.ShowOpenings ? "ON" : "off")}\n" +
                                $"  bocc: {(viz.ShowBOccPaths ? "ON" : "off")}\n" +
                                $"  weather: {(config.DebugWeatherVisualization ? "ON" : "off")}");
                        }

                        switch (mode.ToLower())
                        {
                            case "bounces":
                                viz.BounceColorMode = (viz.BounceColorMode + 1) % 3;
                                string bLabel = viz.BounceColorMode switch { 1 => "ON (reflectivity)", 2 => "ON (reverb slots)", _ => "OFF" };
                                return TextCommandResult.Success($"[SPA] Bounce viz: {bLabel}");
                            case "rays":
                                viz.ShowRays = !viz.ShowRays;
                                return TextCommandResult.Success($"[SPA] Ray path viz: {(viz.ShowRays ? "ON" : "OFF")}");
                            case "occlusion":
                                viz.ShowOcclusion = !viz.ShowOcclusion;
                                return TextCommandResult.Success($"[SPA] Occlusion path viz: {(viz.ShowOcclusion ? "ON" : "OFF")}");
                            case "reposition":
                                viz.ShowReposition = !viz.ShowReposition;
                                return TextCommandResult.Success($"[SPA] Reposition viz: {(viz.ShowReposition ? "ON" : "OFF")}");
                            case "weather":
                                config.DebugWeatherVisualization = !config.DebugWeatherVisualization;
                                return TextCommandResult.Success($"[SPA] Weather viz: {(config.DebugWeatherVisualization ? "ON" : "OFF")}" +
                                    (config.DebugWeatherVisualization ? "\nSky: Blue=covered Yellow=exposed | Paths: White=confirmed Red=blocked | Audio: Magenta=source" : ""));
                            case "openings":
                                viz.ShowOpenings = !viz.ShowOpenings;
                                return TextCommandResult.Success($"[SPA] Opening probe viz: {(viz.ShowOpenings ? "ON" : "OFF")}");
                            case "bocc":
                                viz.ShowBOccPaths = !viz.ShowBOccPaths;
                                return TextCommandResult.Success($"[SPA] bOcc LOS path viz: {(viz.ShowBOccPaths ? "ON" : "OFF")}" +
                                    (viz.ShowBOccPaths ? "\nGreen=clear LOS | Yellow=partial | Orange=heavy | DarkRed=blocked" : ""));
                            case "off":
                            case "clear":
                                viz.ClearAll();
                                config.DebugWeatherVisualization = false;
                                return TextCommandResult.Success("[SPA] All visualizations OFF");
                            default:
                                return TextCommandResult.Error($"Unknown viz mode: {mode}\nValid: bounces | rays | occlusion | reposition | weather | openings | bocc | off");
                        }
                    })
                .EndSubCommand();
        }

        public override void Dispose()
        {
            // Unregister tick listeners
            if (clientApi != null)
            {
                if (cleanupTimerId != 0)
                {
                    clientApi.Event.UnregisterGameTickListener(cleanupTimerId);
                    cleanupTimerId = 0;
                }
                if (occlusionUpdateTimerId != 0)
                {
                    clientApi.Event.UnregisterGameTickListener(occlusionUpdateTimerId);
                    occlusionUpdateTimerId = 0;
                }
                if (smoothingTimerId != 0)
                {
                    clientApi.Event.UnregisterGameTickListener(smoothingTimerId);
                    smoothingTimerId = 0;
                }
                if (weatherTimerId != 0)
                {
                    clientApi.Event.UnregisterGameTickListener(weatherTimerId);
                    weatherTimerId = 0;
                }

                // Cleanup Carry On boombox feature
                if (carryOnModLoaded)
                {
                    CarryOnCompatPatches.Cleanup();
                }

                // Cleanup remote boombox sounds from other players
                BoomboxRemoteHandler.Cleanup();

                clientApi.Event.BlockChanged -= OnBlockChanged;
            }

            // Server-side cleanup: stop the boombox range tick and drop cached carrier
            // state. Statics survive world unload — without this, stale boombox packets
            // from the previous session get pushed to joiners of the next one.
            if (serverApi != null && boomboxServerTickId != 0)
            {
                serverApi.Event.UnregisterGameTickListener(boomboxServerTickId);
                boomboxServerTickId = 0;
            }
            activeBoomboxesByCarrier.Clear();
            boomboxInRangeByReceiver.Clear();
            serverApi = null;

            // Reset world readiness
            _worldReady = false;
            _warmupTicksRemaining = 0;

            // Release the cached chunks — they must not outlive the world.
            tickBlockAccessor?.Dispose();
            tickBlockAccessor = null;

            // Dispose AudioPhysicsSystem
            acousticsManager?.Dispose();
            acousticsManager = null;

            // Dispose sound throttle
            soundThrottle?.Dispose();
            soundThrottle = null;

            // Phase 5A: Dispose weather audio
            weatherManager?.Dispose();
            weatherManager = null;

            // Dispose debug visualization
            debugViz?.Dispose();
            debugViz = null;

            // Dispose all per-sound filters
            AudioRenderer.Dispose();

            // Phase 3: Dispose reverb effects
            ReverbEffects.Dispose();

            // Clear mono downmix cache
            MonoDownmixManager.ClearCache();

            // Clear static block occlusion caches (survive across world loads if not reset)
            BlockClassification.ClearCache();

            // Clear ambient face-sampling data
            AmbientSoundPatches.Clear();

            // Clear block ambient injection data
            BlockAmbientInjector.Clear();

            // Reset LoadSoundPatch statics (pre-warmup queue, cached block accessor,
            // local-player queues, distance-model dedupe). Statics survive world unload;
            // without this, world #2 in the same session kept a dead pre-warmup queue
            // (ambient loops never registered) and raycast against the old world's accessor.
            LoadSoundPatch.Reset();

            // Reset weather patch statics (applied latch, weather-sim instance, thunder
            // handler, latched leafy state) — same survive-unload problem. A stale
            // PatchesApplied flag made the next session start the replacement weather
            // system while the removed patches left vanilla loops playing on top.
            WeatherSoundPatches.Reset();

            // Reset resonator renderer statics (saved rotations, pause timing) — frozen
            // rotations from world #1 otherwise apply to same-coordinate resonators in #2.
            ResonatorRendererPatch.Reset();

            // Unpatch Harmony
            harmony?.UnpatchAll(HARMONY_ID);
            serverHarmony?.UnpatchAll(HARMONY_ID + ".server");

            // Reset server detection flag
            ResonatorPatches.ServerHasMod = false;

            // Clear per-player packet rate buckets (server side, bounded by UID count
            // but stale entries would survive into the next server session)
            packetLastMsByPlayer.Clear();

            // Dispose sound override manager
            Core.SoundOverrideManager.Dispose();

            base.Dispose();
        }

        // === Rate-limited debug logging ===
        // Prevents debug mode from generating 1.5GB+ of logs in heavy scenes.
        // Normal: 200/sec, Verbose: 5000/sec (higher cap for DDA-level debugging).
        private static int debugLogCount = 0;
        private static int debugLogSuppressed = 0;
        private static long debugLogWindowStart = 0;
        private const int DEBUG_LOG_MAX_PER_SECOND = 200;
        private const int DEBUG_VERBOSE_MAX_PER_SECOND = 5000;
        private const long DEBUG_LOG_WINDOW_MS = 1000;

        private static int EffectiveLogLimit => config?.DebugVerbose == true
            ? DEBUG_VERBOSE_MAX_PER_SECOND
            : DEBUG_LOG_MAX_PER_SECOND;

        /// <summary>
        /// Upgrade an older config file in place, one version step at a time.
        /// Every value the user set stays. A field whose default changed is only
        /// written when it still holds the old default — an edited value is kept.
        /// Returns false when a version has no upgrade step; the caller then
        /// regenerates the file from fresh defaults.
        /// </summary>
        private static bool UpgradeConfig(SoundPhysicsConfig cfg, ILogger logger)
        {
            while (cfg.ConfigVersion < CurrentConfigVersion)
            {
                switch (cfg.ConfigVersion)
                {
                    case 10:
                        // v11: torch ambient default went from 0.35 to 0.42 (20% louder).
                        if (Math.Abs(cfg.TorchAmbientVolume - 0.35f) < 0.0001f)
                            cfg.TorchAmbientVolume = 0.42f;
                        cfg.ConfigVersion = 11;
                        break;

                    case 11:
                        // v12: rain source budget 4 -> 8. The value also caps how many
                        // openings the tracker can discover per tick, and 4 starved
                        // multi-opening scenes (cave mouths). Only lift users who still
                        // sit at the old default; respect an explicit choice of 4.
                        if (cfg.MaxPositionalRainSources == 4)
                            cfg.MaxPositionalRainSources = 8;
                        cfg.ConfigVersion = 12;
                        break;

                    default:
                        return false;
                }

                logger?.Notification($"[SoundPhysicsAdapted] Config upgraded to v{cfg.ConfigVersion}.");
            }

            return true;
        }

        /// <summary>
        /// Sanity pass for a config file that has the current version.
        /// A config file with an older version goes through <see cref="UpgradeConfig"/>
        /// first. To change a default for all users: bump CurrentConfigVersion and add
        /// the upgrade step for the new version.
        /// </summary>
        private static void MigrateConfig(SoundPhysicsConfig cfg)
        {
            cfg.ThunderLayer1Volume = GameMath.Clamp(cfg.ThunderLayer1Volume, 0f, 1f);
            cfg.ThunderLayer2Volume = GameMath.Clamp(cfg.ThunderLayer2Volume, 0f, 1f);
            cfg.ConfigVersion = CurrentConfigVersion;
        }

        /// <summary>
        /// Core rate-limited logging. All debug methods delegate here.
        /// Handles window check, suppression counter, and flush summary.
        /// </summary>
        private static void RateLimitedLog(string message, string prefix = null, bool force = false)
        {
            long now = clientApi.ElapsedMilliseconds;
            if (now - debugLogWindowStart >= DEBUG_LOG_WINDOW_MS)
            {
                // New window - flush suppression summary from previous window
                if (debugLogSuppressed > 0)
                {
                    clientApi.Logger.Debug($"[SoundPhysicsAdapted] [Rate limit] Suppressed {debugLogSuppressed} debug messages in last {DEBUG_LOG_WINDOW_MS}ms");
                }
                debugLogCount = 0;
                debugLogSuppressed = 0;
                debugLogWindowStart = now;
            }

            if (force || debugLogCount < EffectiveLogLimit)
            {
                if (!force) debugLogCount++;
                clientApi.Logger.Debug(prefix != null
                    ? $"[SoundPhysicsAdapted] {prefix}{message}"
                    : $"[SoundPhysicsAdapted] {message}");
            }
            else
            {
                debugLogSuppressed++;
            }
        }

        /// <summary>
        /// Debug logging helper - only logs when DebugMode is enabled.
        /// Rate-limited to prevent log flooding in heavy scenes.
        /// Shows occlusion results, path resolution, filter values.
        /// </summary>
        public static void DebugLog(string message, bool force = false)
        {
            if (config?.DebugMode != true || clientApi == null) return;
            RateLimitedLog(message, force: force);
        }

        /// <summary>
        /// Performance diagnostics (heartbeat, slow-tick warnings). Gated behind
        /// DebugMode — the always-on freeze investigation this was built for is resolved.
        /// </summary>
        public static void DiagnosticLog(string message)
        {
            if (config == null || !config.DebugMode) return;
            clientApi?.Logger.Debug($"[SPA-DIAG] {message}");
        }

        /// <summary>
        /// OVERRIDE DIAGNOSTIC: Dump all soundAudioData entries containing "beehive"
        /// to verify whether mod override is actually present in the sound cache.
        /// </summary>
        private static void DumpBeehiveSoundDiag(ICoreClientAPI api)
        {
            try
            {
                // Get soundAudioData via reflection (same approach as LoadSoundPatch)
                Type screenManagerType = null;
                foreach (var asm in AppDomain.CurrentDomain.GetAssemblies())
                {
                    screenManagerType = asm.GetType("Vintagestory.Client.ScreenManager")
                                     ?? asm.GetType("Vintagestory.Client.NoObf.ScreenManager");
                    if (screenManagerType != null) break;
                }
                if (screenManagerType == null)
                {
                    api.Logger.Notification("[SPA-BEEHIVE-DIAG] Could not find ScreenManager type");
                    return;
                }

                var field = screenManagerType.GetField("soundAudioData",
                    BindingFlags.Public | BindingFlags.Static);
                if (field == null)
                {
                    api.Logger.Notification("[SPA-BEEHIVE-DIAG] Could not find soundAudioData field");
                    return;
                }

                var dictObj = field.GetValue(null);
                if (dictObj == null)
                {
                    api.Logger.Notification("[SPA-BEEHIVE-DIAG] soundAudioData is null");
                    return;
                }

                // Use dynamic to iterate since we may not have direct type access
                var dictType = dictObj.GetType();
                int count = (int)dictType.GetProperty("Count").GetValue(dictObj);
                api.Logger.Notification($"[SPA-BEEHIVE-DIAG] soundAudioData has {count} total entries");

                int found = 0;
                // Iterate using IEnumerable
                foreach (dynamic kvp in (System.Collections.IEnumerable)dictObj)
                {
                    AssetLocation key = kvp.Key;
                    object audioData = kvp.Value;

                    if (key.Path != null && key.Path.Contains("beehive"))
                    {
                        found++;
                        // Use reflection to get AudioMetaData properties
                        var adType = audioData.GetType();
                        var assetProp = adType.GetProperty("Asset");
                        var channelsProp = adType.GetProperty("Channels");
                        var rateProp = adType.GetProperty("Rate");
                        var loadedPropInfo = adType.GetProperty("Loaded");
                        var loadedFieldInfo = loadedPropInfo == null ? adType.GetField("Loaded") : null;

                        object asset = assetProp?.GetValue(audioData);
                        int channels = channelsProp != null ? (int)channelsProp.GetValue(audioData) : -1;
                        int rate = rateProp != null ? (int)rateProp.GetValue(audioData) : -1;
                        int loaded = -1;
                        if (loadedPropInfo != null) loaded = (int)loadedPropInfo.GetValue(audioData);
                        else if (loadedFieldInfo != null) loaded = (int)loadedFieldInfo.GetValue(audioData);

                        string originInfo = "unknown";
                        string assetLocStr = "n/a";
                        int dataSize = -1;

                        if (asset != null)
                        {
                            var iasset = asset as IAsset;
                            if (iasset != null)
                            {
                                originInfo = iasset.Origin?.OriginPath ?? "null-origin";
                                assetLocStr = iasset.Location?.ToString() ?? "null-loc";
                                dataSize = iasset.Data?.Length ?? -1;
                            }
                        }

                        api.Logger.Notification(
                            $"[SPA-BEEHIVE-DIAG] KEY={key.Domain}:{key.Path} | " +
                            $"AssetLoc={assetLocStr} | Origin={originInfo} | DataLen={dataSize} | " +
                            $"Channels={channels} | Rate={rate} | Loaded={loaded}");
                    }
                }

                if (found == 0)
                {
                    api.Logger.Notification("[SPA-BEEHIVE-DIAG] NO beehive entries found in soundAudioData!");

                    // Dump all keys that contain "creature" for comparison
                    int creatureCount = 0;
                    foreach (dynamic kvp in (System.Collections.IEnumerable)dictObj)
                    {
                        AssetLocation key = kvp.Key;
                        if (key.Path != null && key.Path.Contains("creature"))
                        {
                            creatureCount++;
                            api.Logger.Notification($"[SPA-BEEHIVE-DIAG] CREATURE: {key.Domain}:{key.Path}");
                        }
                    }
                    api.Logger.Notification($"[SPA-BEEHIVE-DIAG] Found {creatureCount} creature sound entries total");
                }
            }
            catch (Exception ex)
            {
                api.Logger.Error($"[SPA-BEEHIVE-DIAG] Error: {ex}");
            }
        }

        /// <summary>
        /// FREEZE DIAGNOSTIC: Emits a heartbeat every 5s with accumulated tick stats.
        /// If heartbeats stop appearing in the log, the tick handlers stopped firing.
        /// If heartbeats continue but show high ms values, we found the bottleneck.
        /// </summary>
        private void EmitDiagnosticHeartbeat()
        {
            if (clientApi == null) return;
            long nowMs = clientApi.ElapsedMilliseconds;
            if (nowMs - _diagLastHeartbeatLogMs < DIAG_HEARTBEAT_INTERVAL_MS) return;

            _diagHeartbeatCounter++;

            // Calculate FPS from smoothing tick intervals
            double avgFrameMs = _diagFrameCount > 0 ? _diagFrameTimeSum / _diagFrameCount : 0;
            double fps = avgFrameMs > 0 ? 1000.0 / avgFrameMs : 0;

            // Average ms per tick
            double avgSmoothMs = _diagSmoothTickCount > 0 ? _diagSmoothTotalMs / _diagSmoothTickCount : 0;
            double avgOccMs = _diagOcclusionTickCount > 0 ? _diagOcclusionTotalMs / _diagOcclusionTickCount : 0;

            int hookCalls = LoadSoundPatch.DiagGetAndResetHookCount();
            int hookUntracked = LoadSoundPatch.DiagGetAndResetUntrackedCount();

            DiagnosticLog(
                $"HEARTBEAT #{_diagHeartbeatCounter} | " +
                $"fps={fps:F1} avgFrame={avgFrameMs:F1}ms maxFrame={_diagFrameTimeMax:F1}ms | " +
                $"smooth: {_diagSmoothTickCount}ticks avg={avgSmoothMs:F2}ms max={_diagSmoothMaxMs:F2}ms | " +
                $"occlusion: {_diagOcclusionTickCount}ticks avg={avgOccMs:F2}ms max={_diagOcclusionMaxMs:F2}ms | " +
                $"cleanup: {_diagCleanupTickCount}ticks | " +
                $"filters={AudioRenderer.ActiveFilterCount} | " +
                $"hooks={hookCalls} untracked={hookUntracked}");

            // Reset accumulators
            _diagSmoothTickCount = 0;
            _diagSmoothTotalMs = 0;
            _diagSmoothMaxMs = 0;
            _diagOcclusionTickCount = 0;
            _diagOcclusionTotalMs = 0;
            _diagOcclusionMaxMs = 0;
            _diagCleanupTickCount = 0;
            _diagFrameCount = 0;
            _diagFrameTimeSum = 0;
            _diagFrameTimeMax = 0;
            _diagLastHeartbeatLogMs = nowMs;
        }

        /// <summary>
        /// Occlusion-specific debug logging - per-sound occlusion results.
        /// Only logs when BOTH DebugMode AND DebugOcclusion are enabled.
        /// </summary>
        public static void OcclusionDebugLog(string message, bool force = false)
        {
            if (config?.DebugMode != true || config?.DebugOcclusion != true || clientApi == null) return;
            RateLimitedLog(message, "[Occlusion] ", force);
        }

        /// <summary>
        /// Verbose debug logging - per-block DDA hits, individual ray steps.
        /// Only logs when DebugMode, DebugOcclusion AND DebugVerbose are all enabled.
        /// WARNING: Generates 300+ lines per sound per update. Use sparingly.
        /// </summary>
        public static void VerboseDebugLog(string message)
        {
            if (config?.DebugMode != true || config?.DebugOcclusion != true || config?.DebugVerbose != true || clientApi == null) return;
            RateLimitedLog(message);
        }

        // ═══════════════════════════════════════════════════════════
        // Zero-cost guard properties for caller-side debug log gating.
        // C# evaluates $"..." interpolated strings at the call site BEFORE
        // entering the method. Wrapping calls with these guards ensures
        // the string is never built when debug is off. AggressiveInlining
        // lets the JIT eliminate the entire branch.
        // ═══════════════════════════════════════════════════════════

        /// <summary>True when general debug logging is active.</summary>
        public static bool IsDebugEnabled
        {
            [MethodImpl(MethodImplOptions.AggressiveInlining)]
            get => config?.DebugMode == true && clientApi != null;
        }

        /// <summary>True when occlusion-specific debug logging is active.</summary>
        public static bool IsOcclusionDebugEnabled
        {
            [MethodImpl(MethodImplOptions.AggressiveInlining)]
            get => config?.DebugMode == true && config?.DebugOcclusion == true && clientApi != null;
        }

        /// <summary>True when reverb-specific debug logging is active.</summary>
        public static bool IsReverbDebugEnabled
        {
            [MethodImpl(MethodImplOptions.AggressiveInlining)]
            get => config?.DebugMode == true && config?.DebugReverb == true && clientApi != null;
        }

        /// <summary>True when resonator-specific debug logging is active.</summary>
        public static bool IsResonatorDebugEnabled
        {
            [MethodImpl(MethodImplOptions.AggressiveInlining)]
            get => config?.DebugMode == true && config?.DebugResonator == true && clientApi != null;
        }

        /// <summary>
        /// Fast check for whether verbose DDA logging is active.
        /// Use to gate StringBuilder accumulation and avoid f-string allocations.
        /// </summary>
        public static bool IsVerboseDebugEnabled
        {
            [MethodImpl(MethodImplOptions.AggressiveInlining)]
            get => config?.DebugMode == true && config?.DebugOcclusion == true && config?.DebugVerbose == true && clientApi != null;
        }

        /// <summary>
        /// Flush a batched verbose debug log (e.g. entire DDA ray trace).
        /// Logs the full StringBuilder content as a single Logger.Debug() call,
        /// reducing synchronous I/O from ~10 calls per ray to 1.
        /// </summary>
        public static void VerboseDebugBatch(StringBuilder sb)
        {
            if (sb == null || sb.Length == 0) return;
            if (config?.DebugMode != true || config?.DebugOcclusion != true || config?.DebugVerbose != true || clientApi == null) return;
            RateLimitedLog(sb.ToString());
        }

        /// <summary>
        /// Reverb-specific debug logging - uses DebugReverb flag.
        /// Requires DebugMode=true as master gate.
        /// Rate-limited via shared counter.
        /// </summary>
        public static void ReverbDebugLog(string message)
        {
            if (config?.DebugMode != true || config?.DebugReverb != true || clientApi == null) return;
            RateLimitedLog(message);
        }

        /// <summary>
        /// Resonator-specific debug logging - uses DebugResonator flag.
        /// Requires DebugMode=true as master gate.
        /// Shows pause/resume events, Carry On pickup/placement, boombox state.
        /// Rate-limited via shared counter.
        /// </summary>
        public static void ResonatorDebugLog(string message)
        {
            if (config?.DebugMode != true || config?.DebugResonator != true || clientApi == null) return;
            RateLimitedLog(message, "[Resonator] ");
        }

        /// <summary>
        /// Always log (for important events)
        /// </summary>
        public static void Log(string message)
        {
            clientApi?.Logger.Notification($"[SoundPhysicsAdapted] {message}");
        }

        // Submersion state cache (updated each tick)
        private static bool isPlayerUnderwater = false;
        private static bool isPlayerInLava = false;

        /// <summary>
        /// Check if player is currently underwater (head submerged in water).
        /// Cached and updated in tick handler for performance.
        /// </summary>
        public static bool IsPlayerUnderwater => isPlayerUnderwater;

        /// <summary>
        /// Check if player is currently submerged in lava.
        /// Cached and updated in tick handler for performance.
        /// </summary>
        public static bool IsPlayerInLava => isPlayerInLava;

        /// <summary>
        /// Check if player is submerged in any liquid (water or lava).
        /// </summary>
        public static bool IsPlayerSubmerged => isPlayerUnderwater || isPlayerInLava;

        /// <summary>
        /// Get the submersion filter multiplier (water or lava).
        /// Returns 1.0 if not submerged or ReplaceVanillaLowpass is disabled.
        /// </summary>
        public static float GetUnderwaterMultiplier()
        {
            return GetUnderwaterMultiplier(isMusic: false);
        }

        /// <summary>
        /// Get the submersion filter multiplier with music handling.
        /// Lava uses heavier filter values when EnableLavaFilter is true.
        /// </summary>
        public static float GetUnderwaterMultiplier(bool isMusic)
        {
            if (!config.ReplaceVanillaLowpass)
                return 1.0f;

            // Lava submersion (heavier filter)
            if (isPlayerInLava)
            {
                if (!config.EnableLavaFilter)
                    return isPlayerUnderwater ? config.UnderwaterFilterValue : 1.0f;
                if (isMusic && !config.UnderwaterFilterAffectsMusic)
                    return 1.0f;
                return config.LavaFilterValue;
            }

            // Water submersion
            if (!isPlayerUnderwater)
                return 1.0f;
            if (isMusic && !config.UnderwaterFilterAffectsMusic)
                return 1.0f;
            return config.UnderwaterFilterValue;
        }

        /// <summary>
        /// Get the submersion pitch offset (water or lava).
        /// Returns 0 if not submerged or ReplaceVanillaLowpass is disabled.
        /// </summary>
        public static float GetUnderwaterPitchOffset()
        {
            if (!config.ReplaceVanillaLowpass)
                return 0f;

            if (isPlayerInLava && config.EnableLavaFilter)
                return config.LavaPitchOffset;

            if (!isPlayerUnderwater)
                return 0f;

            return config.UnderwaterPitchOffset;
        }

        /// <summary>
        /// Get the submersion reverb cutoff multiplier.
        /// Returns 1.0 if not submerged.
        /// </summary>
        public static float GetSubmersionReverbCutoff()
        {
            if (isPlayerInLava && config.EnableLavaFilter)
                return config.LavaReverbCutoff;
            if (isPlayerUnderwater)
                return config.UnderwaterReverbCutoff;
            return 1.0f;
        }

        /// <summary>
        /// Get the submersion reverb gain multiplier.
        /// Returns 1.0 if not submerged.
        /// </summary>
        public static float GetSubmersionReverbMultiplier()
        {
            if (isPlayerInLava && config.EnableLavaFilter)
                return config.LavaReverbMultiplier;
            if (isPlayerUnderwater)
                return config.UnderwaterReverbMultiplier;
            return 1.0f;
        }

        /// <summary>
        /// Update submersion state - called from tick handler.
        /// Uses LiquidCode to distinguish water from lava.
        /// </summary>
        private void UpdateUnderwaterState()
        {
            if (clientApi?.World?.Player?.Entity == null)
            {
                isPlayerUnderwater = false;
                isPlayerInLava = false;
                return;
            }

            var player = clientApi.World.Player.Entity;
            Vec3d eyePos = player.Pos.XYZ.Add(player.LocalEyePos);

            // Check fluid layer at eye position for water/lava detection.
            // Using BlockLayersAccess.Fluid ensures we detect water even when
            // waterlogged blocks (Milfoil, seaweed, kelp, etc.) occupy the solid layer.
            // Math.Floor, not a cast: at negative coordinates in (-1, 0) the truncating
            // cast samples the block one over (submersion detection).
            BlockPos blockPos = new BlockPos((int)Math.Floor(eyePos.X), (int)Math.Floor(eyePos.Y), (int)Math.Floor(eyePos.Z));
            var fluidBlock = clientApi.World.BlockAccessor.GetBlock(blockPos, BlockLayersAccess.Fluid);

            bool wasUnderwater = isPlayerUnderwater;
            bool wasInLava = isPlayerInLava;

            // Use LiquidCode to distinguish liquid types
            // Water: "water", "saltwater", "seawater"
            // Lava: "lava"
            // Lava also uses block.Code.PathStartsWith("lava") in vanilla
            string liquidCode = fluidBlock?.LiquidCode;
            bool isLiquid = fluidBlock != null && fluidBlock.IsLiquid();

            if (isLiquid && liquidCode == "lava")
            {
                isPlayerUnderwater = false;
                isPlayerInLava = true;
            }
            else if (isLiquid)
            {
                // water, saltwater, seawater, boilingwater, etc.
                isPlayerUnderwater = true;
                isPlayerInLava = false;
            }
            else
            {
                // Also check solid layer for lava (some lava blocks use solid layer)
                var solidBlock = clientApi.World.BlockAccessor.GetBlock(blockPos, BlockLayersAccess.Solid);
                string blockPath = solidBlock?.Code?.Path;
                if (blockPath != null && blockPath.StartsWith("lava"))
                {
                    isPlayerUnderwater = false;
                    isPlayerInLava = true;
                }
                else
                {
                    isPlayerUnderwater = false;
                    isPlayerInLava = false;
                }
            }

            // On state change, update ALL playing sounds (including music)
            bool stateChanged = (isPlayerUnderwater != wasUnderwater) || (isPlayerInLava != wasInLava);
            if (stateChanged)
            {
                if (isPlayerInLava)
                    DebugLog($"SUBMERSION: ENTERED lava - filter={config.LavaFilterValue:F2}, pitch={config.LavaPitchOffset:F2}");
                else if (isPlayerUnderwater)
                    DebugLog($"SUBMERSION: ENTERED water - filter={config.UnderwaterFilterValue:F2}, pitch={config.UnderwaterPitchOffset:F2}, music={config.UnderwaterFilterAffectsMusic}");
                else
                    DebugLog($"SUBMERSION: EXITED liquid");

                // Force recalculate all sounds to apply/remove submersion filter
                // This affects already-playing sounds including music
                AudioRenderer.RecalculateAllUnderwater();
            }
        }

        // Debounce block change events
        private long lastBlockChangeTimeMs = 0;
        private const long BLOCK_CHANGE_DEBOUNCE_MS = 200;

        /// <summary>
        /// Hook for block changes to invalidate acoustics cache.
        /// Debounced to avoid thrashing during chunk loads or large updates.
        /// </summary>
        private void OnBlockChanged(BlockPos pos, Block oldBlock)
        {
            if (acousticsManager == null || clientApi == null) return;

            // Always do cell-targeted invalidation (cheap, O(1) per cell)
            acousticsManager.CellCache?.InvalidateCellAt(pos.X, pos.Y, pos.Z);

            // Always notify weather system for entry-point proximity checks (cheap, O(n*m))
            weatherManager?.NotifyBlockChanged(pos);

            long currentTime = clientApi.World.ElapsedMilliseconds;
            
            // Debounce: if we recently invalidated, don't do it again immediately.
            if (currentTime - lastBlockChangeTimeMs < BLOCK_CHANGE_DEBOUNCE_MS)
            {
                return;
            }

            lastBlockChangeTimeMs = currentTime;
            acousticsManager.InvalidateCache(currentTime);
        }
    }
}