// This file is part of ClassicAPI. // // ClassicAPI is free software: you can redistribute it and/or modify it under the terms // of the GNU General Public License as published by the Free Software Foundation, either // version 3 of the License, or (at your option) any later version. // // ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR // PURPOSE. See the GNU General Public License for more details. // // You should have received a copy of the GNU General Public License along with // ClassicAPI. If not, see . // `MuteSoundFile(path)` / `UnmuteSoundFile(path)` — stop a specific sound // file from playing — plus `C_Sound.GetRecentSoundFiles()`, which reports // what has played lately so a caller can find the path to mute. // // Blizzard's pair takes a file id or a path; only the path form is // meaningful here, since file ids are a later scheme. The path is the one // the engine itself uses, e.g. "Sound\Creature\Ragnaros\RagnarosAggro01.wav". // // HOW: co-hooks on the two engine functions every sound open ends in — // Sound::Play (FUN_SOUND_OPEN, behind both the 2D and the 3D opener) and // Sound::PlayLooped (FUN_SOUND_OPEN_LOOPED, ambience and emitters). See // Offsets.h for why there is no third route. A muted path returns NULL, // which is the engine's OWN "this did not play" answer: its pre-play gate // `0x007A66A0` already produces NULL for a bus at its cap, and a failed // stream open does the same in both functions, so every caller in the // binary already handles it. Muting therefore needs no new failure path. // // Suppressing the open rather than muting the opened stream is deliberate: // nothing is decoded for a sound nobody hears. The one visible difference // from a true mute is that a play call reports a muted file as not played. // // WHY THE RECENT LIST IS ALWAYS ON: the hook exists for muting regardless, // and recording costs one bounded copy into a preallocated slot on a call // that is about to hash a path, open an archive file, decompress it and // hand it to FMOD — three or four orders of magnitude more work. Play rate // is bounded too: the engine caps concurrent streams per category, so this // is tens per second at worst, never per-frame. A switch would guard a cost // that is not there, and would have to be armed BEFORE hearing the sound // you wanted to identify, which is exactly when you cannot know to arm it. // // Muted entries stay in the list, flagged. Dropping them would make a sound // vanish from the one view you would use to un-mute it. #include "Common.h" #include "Game.h" #include "Offsets.h" #include "time/Clock.h" #include #include #include #include namespace Sound::Mute { namespace { // Paths are at most 260 bytes elsewhere in the engine's file layer; the // longest this client actually ships is well under half that. constexpr size_t kMaxPath = 260; // How far back the recent list reaches. Deep enough that a busy pull cannot // flush the sound you just heard before you can read it, while staying a // fixed ~17 KB with no allocation on the hook path. constexpr int kRecentSlots = 64; struct Recent { char path[kMaxPath]; uint32_t seq; // insertion order; 0 = slot never used uint32_t timeMs; // engine tick, GetTime()-comparable once scaled bool muted; }; Recent g_recent[kRecentSlots]; uint32_t g_seq = 0; // Muted paths, normalized. Empty in the overwhelmingly common case, which // is one `empty()` test on the hook path. std::unordered_set g_muted; // Fold each character as Common::SamePath compares it, so a caller may pass // either separator and any casing — the engine's own path compares are // case-insensitive. void Normalize(const char *path, std::string &out) { out.clear(); for (const char *p = path; *p != '\0'; ++p) out.push_back(Common::FoldPathChar(*p)); } bool IsMuted(const char *path) { if (g_muted.empty()) return false; std::string key; Normalize(path, key); return g_muted.find(key) != g_muted.end(); } // Note a path as played. Re-playing a path refreshes its existing slot // rather than taking a new one, so a looping footstep cannot push the rest // of the window out — the list holds the last N DISTINCT sounds, which is // what makes it usable for identifying one. void Record(const char *path, bool muted) { const uint32_t now = Time::Clock::NowMs(); int oldest = 0; for (int i = 0; i < kRecentSlots; ++i) { Recent &r = g_recent[i]; if (r.seq != 0 && Common::SamePath(r.path, path)) { r.seq = ++g_seq; r.timeMs = now; r.muted = muted; return; } if (r.seq < g_recent[oldest].seq) oldest = i; // an unused slot (seq 0) wins this outright } Recent &r = g_recent[oldest]; const size_t n = std::strlen(path); const size_t copy = (n < kMaxPath) ? n : kMaxPath - 1; std::memcpy(r.path, path, copy); r.path[copy] = '\0'; r.seq = ++g_seq; r.timeMs = now; r.muted = muted; } // Records the open and answers whether it must be refused. bool Refuse(const char *path) { if (path == nullptr || *path == '\0') return false; const bool muted = IsMuted(path); Record(path, muted); return muted; } using Open_t = void *(__fastcall *)(int bus, const char *path, unsigned mode, char held, unsigned flags); using OpenLooped_t = void *(__fastcall *)(int bus, const char *path, int loopCount, unsigned mode, char held, unsigned flags); Open_t g_open = nullptr; OpenLooped_t g_openLooped = nullptr; void *__fastcall Open_h(int bus, const char *path, unsigned mode, char held, unsigned flags) { if (Refuse(path)) return nullptr; // exactly what the engine's own failures return return g_open(bus, path, mode, held, flags); } void *__fastcall OpenLooped_h(int bus, const char *path, int loopCount, unsigned mode, char held, unsigned flags) { if (Refuse(path)) return nullptr; return g_openLooped(bus, path, loopCount, mode, held, flags); } // MuteSoundFile(path) -> true when the path is now muted, false for a bad // argument. Muting a path that is already muted is a no-op, not an error. int __fastcall Script_MuteSoundFile(void *L) { const char *path = Game::Lua::ToString(L, 1); if (path == nullptr || *path == '\0') { Game::Lua::PushBool(L, false); return 1; } std::string key; Normalize(path, key); g_muted.insert(key); Game::Lua::PushBool(L, true); return 1; } // UnmuteSoundFile(path) -> true when the path had been muted. int __fastcall Script_UnmuteSoundFile(void *L) { const char *path = Game::Lua::ToString(L, 1); if (path == nullptr || *path == '\0') { Game::Lua::PushBool(L, false); return 1; } std::string key; Normalize(path, key); Game::Lua::PushBool(L, g_muted.erase(key) != 0); return 1; } // C_Sound.GetRecentSoundFiles() -> array of { file, time, muted }, newest // first. `time` is milliseconds on GetTime()'s epoch, so // `GetTime() * 1000 - time` is how long ago the sound played. int __fastcall Script_GetRecentSoundFiles(void *L) { // Selection-sort the used slots by seq, newest first. At most 64 // entries, and only when Lua asks. int order[kRecentSlots]; int used = 0; for (int i = 0; i < kRecentSlots; ++i) if (g_recent[i].seq != 0) order[used++] = i; for (int i = 0; i < used; ++i) { int best = i; for (int j = i + 1; j < used; ++j) if (g_recent[order[j]].seq > g_recent[order[best]].seq) best = j; const int t = order[i]; order[i] = order[best]; order[best] = t; } Game::Lua::NewTable(L); // [list] for (int i = 0; i < used; ++i) { const Recent &r = g_recent[order[i]]; Game::Lua::PushNumber(L, static_cast(i + 1)); // [list, idx] Game::Lua::NewTable(L); // [list, idx, entry] Game::Lua::SetFieldString(L, "file", r.path); Game::Lua::SetFieldNumber(L, "time", static_cast(r.timeMs)); Game::Lua::SetFieldBool(L, "muted", r.muted); Game::Lua::RawSet(L, -3); // list[idx] = entry. [list] } return 1; } void RegisterLuaFunctions() { // Blizzard's own names are plain globals, so these are too. Game::Lua::RegisterGlobalFunction("MuteSoundFile", &Script_MuteSoundFile); Game::Lua::RegisterGlobalFunction("UnmuteSoundFile", &Script_UnmuteSoundFile); Game::Lua::RegisterTableFunction("C_Sound", "GetRecentSoundFiles", &Script_GetRecentSoundFiles); } const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; const Game::HookAutoRegister _openHook{Offsets::FUN_SOUND_OPEN, reinterpret_cast(&Open_h), reinterpret_cast(&g_open)}; const Game::HookAutoRegister _openLoopedHook{Offsets::FUN_SOUND_OPEN_LOOPED, reinterpret_cast(&OpenLooped_h), reinterpret_cast(&g_openLooped)}; } // namespace } // namespace Sound::Mute