Files
ClassicAPI/src/sound/Mute.cpp
T
Brues 3e0c40184b feat(cursor): add expanded cursors for NPCs and the fishing bobber
Adds the expandedCursors cvar (default 0; AddOn Options > ClassicAPI >
Interface > Cursor). At 1 the hover cursor shows what an NPC offers: an
anvil for a repairer, a hearthstone for an innkeeper, a horseshoe for a
stable master, and a quest giver's ! or ? (a blue ? for a repeatable
reward). The player's fishing bobber shows a fish hook in place of the
Interact gear. Each has a gray form beyond reach or when not usable.

NPCs: ClassifyHoveredUnit (0x00482200) reaches its NPC flag chain at
0x00482336 for a unit the player can interact with, the unit in ESI and
the beyond-reach flag in EBX. The chain's `mov ecx, [esi+0x110]` becomes
a call to a thunk. At 0 it replays the instruction and the stock chain
runs. At 1 it picks from the quest giver status first (CGUnit_C +0xCB8,
read by the meaning of the client's status-to-marker table at
0x0080C454), then the NPC flags in service order: repair, innkeeper,
flight master, trainer, spirit healer, banker, registrar/tabard/
battlemaster, auctioneer, stable master, vendor, then gossip or a quest
giver IsQuestGiverToTalk (0x005DF490) accepts. It leaves through the
chain's own epilogue (0x00482356).

Bobber: the fishing node handler's cursor slot (vtable 0x0080BC80, slot
4; GetCursor 0x005F8760 is its one reader) points at a wrapper that runs
BaseHandlerGetCursor (0x005F3070) and maps Interact/UnableInteract to
the hook. The engine still decides whether the bobber is interactable
and usable.

Showing a mode past 41: SetCursorMode indexes a 42-slot image table, so
its existing hook now sends the new modes to Cursor::Extended::Show. It
calls SetCustomCursor (0x00523C40) with the mode's path, so a real file
wins, and otherwise does what that function does after its load: copy
the 32x32 image into slot 41 (0x00C0BD80), store mode 41, send it
(SendCursorImage 0x00523790) and keep the name. The hook also records
the new modes while Hover::Mode computes, so the soft-interact pick, its
icon and SetUnitCursorTexture follow; a quest cursor has no icon image.

Images: the 14 BLPs ship inside the DLL (src/embed/Textures, a new
TEXTURES_ROOT pack). Texture::Builtin decodes each once with the
engine's BLP reader from memory: BlpParse (0x005A83B0) is BlpOpen
without the file read, and BlpReset never frees the file buffer. The
reader moves to Texture::BlpReader, shared with the map overlays.
Texture loads of the same paths, such as the option label's inline
icons, get the same images.

The reader refuses a DXT5 file. BlpDecodeLevel (0x005A7F00) converts a
DXT level through the matrix InitConvertMatrix (0x005A4FC0) fills, and
that matrix has DXT1 and DXT3 converters to BGRA8888 but none for DXT5:
BlpDecodeLevel would return 1 with its SMemAlloc buffer unwritten. No
shipped cursor is DXT5; the check keeps a later embedded DXT5 file, or a
DXT5 map overlay, from being read as heap memory.

Game paths now compare through one rule, Common::SamePath (any case,
either slash), and the embedded manifests through Embed::FindFile. The
embedded addons, the bindings splice and sound muting each had their own
copy of the rule; they and Texture::Builtin now share it.

The option's header, label and tooltip are translated for every client
locale, in Blizzard's own terms for each (NSC, PNJ, 物体, 物件, ...).

Release Win32 build is clean. In game, only the soft-interact quest
icon was checked so far.
2026-11-04 02:36:18 -06:00

239 lines
9.3 KiB
C++

// 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 <https://www.gnu.org/licenses/>.
// `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 <cstdint>
#include <cstring>
#include <string>
#include <unordered_set>
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<std::string> 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<double>(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<double>(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<void *>(&Open_h),
reinterpret_cast<void **>(&g_open)};
const Game::HookAutoRegister _openLoopedHook{Offsets::FUN_SOUND_OPEN_LOOPED,
reinterpret_cast<void *>(&OpenLooped_h),
reinterpret_cast<void **>(&g_openLooped)};
} // namespace
} // namespace Sound::Mute