diff --git a/README.md b/README.md
index aa61a6f1..e2705823 100644
--- a/README.md
+++ b/README.md
@@ -232,6 +232,7 @@ when launching with `-console`), not as Lua functions. See the
| `QUEST_DATA_LOAD_RESULT` | `questID, success` |
| `QUEST_REMOVED` | `questID` |
| `QUEST_TURNED_IN` | `questID, xpReward, moneyReward` |
+| `SOUNDKIT_FINISHED` | `soundHandle` (only for sounds played with `runFinishCallback`) |
| `UNIT_SPELLCAST_SENT` | `"player", target, castGUID, spellID, spellName, rank` |
| `UNIT_SPELLCAST_START` | `unit, castGUID, spellID, spellName, rank` |
| `UNIT_SPELLCAST_STOP` | `unit, castGUID, spellID, spellName, rank` |
diff --git a/docs/API.md b/docs/API.md
index 509e5d60..3c7dc531 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -169,6 +169,7 @@ build instructions.
- [`QUEST_ACCEPTED` event](#quest_accepted-event)
- [`QUEST_REMOVED` event](#quest_removed-event)
- [`QUEST_TURNED_IN` event](#quest_turned_in-event)
+ - [`SOUNDKIT_FINISHED` event](#soundkit_finished-event)
- [`UNIT_FACTION` event (fire-coverage fix)](#unit_faction-event-fire-coverage-fix)
- [`UPDATE_MOUSEOVER_UNIT` event (loss-fire fix)](#update_mouseover_unit-event-loss-fire-fix)
- [`UPDATE_SHAPESHIFT_FORM` event](#update_shapeshift_form-event)
@@ -558,8 +559,8 @@ build instructions.
- [`GetQuestLogLeaderBoardID(objectiveIndex [, questIndex])`](#getquestlogleaderboardidobjectiveindex--questindex)
- [Sound](#sound)
- - [`PlaySound(soundKitID [, channel])` / `PlaySound(soundName)`](#playsoundsoundkitid--channel--playsoundsoundname)
- - [`C_Sound.PlaySound(soundKitID [, channel])`](#c_soundplaysoundsoundkitid--channel)
+ - [`PlaySound(soundKitID)` / `PlaySound(soundName)`](#playsoundsoundkitid--playsoundsoundname)
+ - [`C_Sound.PlaySound(soundKitID [, channel, forceNoDuplicates, runFinishCallback])`](#c_soundplaysoundsoundkitid--channel-forcenoduplicates-runfinishcallback)
- [`C_Sound.IsPlaying(soundHandle)`](#c_soundisplayingsoundhandle)
- [`C_Sound.PlayItemSound(soundType, item)`](#c_soundplayitemsoundsoundtype-item)
- [`MuteSoundFile(file)` / `UnmuteSoundFile(file)`](#mutesoundfilefile--unmutesoundfilefile)
@@ -4242,6 +4243,31 @@ quest invalidated, etc.). Only fires on a real successful turn-in.
> done, quest removed from log). Hooking the packet handler gives
> us a clean turn-in signal.
+### `SOUNDKIT_FINISHED` event
+
+Fires when a sound finishes playing.
+
+```lua
+local f = CreateFrame("Frame")
+f:RegisterEvent("SOUNDKIT_FINISHED")
+f:SetScript("OnEvent", function()
+ print("finished:", arg1) -- the handle of the sound that ended
+end)
+
+C_Sound.PlaySound(8959, nil, nil, true)
+```
+
+| Argument | Meaning |
+|---|---|
+| `arg1` | `soundHandle` — the handle [`C_Sound.PlaySound`](#c_soundplaysoundsoundkitid--channel-forcenoduplicates-runfinishcallback) returned for the sound that just ended. |
+
+It fires **only** for sounds played with `runFinishCallback` set to `true`.
+Sounds played any other way report nothing — every footstep and button
+click would otherwise raise an event.
+
+The event arrives on the frame after the sound ends, which is when the
+client releases it.
+
### `UNIT_FACTION` event (fire-coverage fix)
`UNIT_FACTION` already exists in the event table — addons can register
@@ -13645,7 +13671,7 @@ To see the file paths, extract them with the
[`ExportSoundFiles`](#exportsoundfiles-subpath-console-command) console
command.
-### `PlaySound(soundKitID [, channel])` / `PlaySound(soundName)`
+### `PlaySound(soundKitID)` / `PlaySound(soundName)`
Plays a sound.
@@ -13659,14 +13685,12 @@ PlaySound(8959) -- true, 394043692
PlaySound("igMainMenuOpen") -- plays, returns nothing
```
-`channel` selects the sound category, `0` to `12`. Leave it out for `0`,
-which is what the client uses for interface sounds and music. A channel
-**name** such as `"SFX"` is accepted and ignored, so code written for the
-modern client still runs. The categories here do not match those names.
+The id is the only thing added here. For a channel, or to be told when the
+sound ends, use `C_Sound.PlaySound` below.
-### `C_Sound.PlaySound(soundKitID [, channel])`
+### `C_Sound.PlaySound(soundKitID [, channel, forceNoDuplicates, runFinishCallback])`
-The same as the numeric form above, and it takes only a number. Returns
+Plays a SoundKitID, and takes only a number. Returns
`willPlay, soundHandle`.
```lua
@@ -13680,6 +13704,12 @@ has as many sounds as it allows.
An entry can hold several files. The client picks one of them, with the
same weighting it uses for its own sounds.
+| Argument | Meaning |
+|---|---|
+| `channel` | The sound category, `0` to `12`. Leave it out for `0`, which is what the client uses for interface sounds and music. A channel **name** such as `"SFX"` is accepted and ignored: the categories here do not match those names. |
+| `forceNoDuplicates` | Accepted and ignored. |
+| `runFinishCallback` | Pass `true` to get the [`SOUNDKIT_FINISHED`](#soundkit_finished-event) event when this sound ends. |
+
### `C_Sound.IsPlaying(soundHandle)`
Returns `true` while the sound for that handle is still playing.
diff --git a/src/Offsets.h b/src/Offsets.h
index 7f71fcdd..f3f053a0 100644
--- a/src/Offsets.h
+++ b/src/Offsets.h
@@ -6147,6 +6147,22 @@ enum Offsets {
// when it finishes, so the handle must never be dereferenced directly.
VAR_SOUND_STREAM_LIST_HEAD = 0x00CF557C,
OFF_SOUND_STREAM_NEXT = 0x04,
+ // Hash of the path the stream was opened with, stamped at creation
+ // (`FUN_007A51D0`: `obj[0x20] = FUN_0064AF90(path)`) and compared by
+ // the dedup pass. Stream objects come from a pool and their addresses
+ // are reused, so this is what tells one instance from another at the
+ // same address — see `Sound::Play`'s finish tracking.
+ OFF_SOUND_STREAM_PATH_HASH = 0x80,
+
+ // Per-frame sound update, main thread: drains finished streams
+ // (`FUN_007A4B60`), updates the 3D listener, then calls FSOUND_Update.
+ // The drain matters for anything reporting completion: FMOD's own end
+ // callback (`FUN_007A53C0`) runs on the STREAMER thread and only moves
+ // the stream onto a deferred list under a critical section
+ // (`0x00CF55B4`) — so a finished sound must never be reported from
+ // there. `FUN_007A4B60` is where the engine reclaims those, on the main
+ // thread, which is the only safe side to notice completion from.
+ FUN_SOUND_UPDATE_FRAME = 0x007A4AD0,
// `Script_PlaySound` — the engine's `PlaySound(soundName)`: hashes the
// name to a SoundEntries row and calls `FUN_00458850`, whose tail is
diff --git a/src/sound/Play.cpp b/src/sound/Play.cpp
index d3ffa0b2..ce757099 100644
--- a/src/sound/Play.cpp
+++ b/src/sound/Play.cpp
@@ -11,9 +11,10 @@
// You should have received a copy of the GNU General Public License along with
// ClassicAPI. If not, see .
-// `C_Sound.PlaySound(soundKitID [, channel])`,
-// `C_Sound.IsPlaying(soundHandle)`, and the global `PlaySound` widened to
-// take a SoundKitID as well as the row name it has always taken.
+// `C_Sound.PlaySound(soundKitID [, channel [, forceNoDuplicates
+// [, runFinishCallback]]])`, `C_Sound.IsPlaying(soundHandle)`, the
+// `SOUNDKIT_FINISHED` event, and the global `PlaySound` widened to take a
+// SoundKitID as well as the row name it has always taken.
//
// A SoundKitID is a SoundEntries.dbc row id — the same ids the modern
// client's SOUNDKIT constants carry, because it is the same table under a
@@ -37,8 +38,11 @@
#include "Game.h"
#include "Offsets.h"
+#include "event/Custom.h"
+#include "tick/WorldTick.h"
#include
+#include
namespace Sound::Play {
@@ -55,29 +59,110 @@ constexpr int kVariantRandom = -1; // the engine's own weighted pick
// never be dereferenced. Membership of the engine's live stream list is the
// safe test — the same list its dedup pass walks (`FUN_007A66A0`): an
// intrusive list whose `next` sits at +0x04, ended by a null or a
-// low-bit-tagged sentinel.
-bool HandleAlive(uintptr_t handle) {
+// low-bit-tagged sentinel. Returns the node so a caller that needs a field
+// off it reads only a node that is provably still there.
+uintptr_t FindStreamNode(uintptr_t handle) {
if (handle == 0)
- return false;
+ return 0;
uintptr_t node = *reinterpret_cast(
static_cast(Offsets::VAR_SOUND_STREAM_LIST_HEAD));
for (int guard = 0; guard < 4096; ++guard) {
if (node == 0 || (node & 1) != 0)
- return false;
+ return 0;
if (node == handle)
- return true;
+ return node;
node = *reinterpret_cast(
node + Offsets::OFF_SOUND_STREAM_NEXT);
}
- return false; // cycle or corruption — never spin inside a Lua call
+ return 0; // cycle or corruption — never spin inside a Lua call
}
-// Play a row by id and push `willPlay, soundHandle`. `channel` is the
-// engine's sound category (0..12; 0 is what the engine itself uses for UI
-// sounds and music, 3 for a file played by path). A channel NAME is
-// accepted and ignored, so code written against the modern string form
-// still runs — the categories here do not correspond to it.
-int PlayById(void *L, int soundKitID, int argChannel) {
+bool HandleAlive(uintptr_t handle) { return FindStreamNode(handle) != 0; }
+
+uint32_t PathHash(uintptr_t node) {
+ return *reinterpret_cast(
+ node + Offsets::OFF_SOUND_STREAM_PATH_HASH);
+}
+
+// ---- SOUNDKIT_FINISHED ------------------------------------------------
+//
+// Fires with the sound handle once that sound stops, and ONLY for sounds
+// started with `runFinishCallback` — which is both the documented contract
+// and the reason this is affordable. Without the opt-in every footstep and
+// UI click would dispatch a Lua event.
+//
+// Detected on the world tick rather than from FMOD's end callback: that
+// callback (`FUN_007A53C0`) runs on the STREAMER thread and only defers the
+// stream onto a list under a critical section. Firing a Lua event from
+// there would call into the VM off the main thread. The engine notices
+// completion on its own side in `FUN_007A4B60`, from the per-frame sound
+// update — so a main-thread check is what the engine itself does.
+//
+// A tracked entry keeps the stream's path hash alongside the handle.
+// Stream objects are pooled and their addresses reused, so "the handle is
+// still in the list" is not enough on its own: a later sound can land on
+// the same address. Comparing the hash too means only the same file
+// replaying at the same address can be mistaken for the original, and that
+// costs one extra dword read of a node we have already found alive.
+const Event::Custom::AutoReserve _soundkitFinished{"SOUNDKIT_FINISHED"};
+
+struct Tracked {
+ uintptr_t handle;
+ uint32_t pathHash;
+};
+
+// Only ever holds sounds a caller opted in for, so it is empty almost
+// always and never needs a cap.
+std::vector g_tracked;
+
+void TrackForFinish(uintptr_t handle) {
+ const uintptr_t node = FindStreamNode(handle);
+ if (node == 0)
+ return; // already over, or never started — nothing to report
+ g_tracked.push_back({handle, PathHash(node)});
+}
+
+void OnWorldTick() {
+ if (g_tracked.empty())
+ return;
+ const int slot = _soundkitFinished.Slot();
+ size_t keep = 0;
+ for (size_t i = 0; i < g_tracked.size(); ++i) {
+ const Tracked &t = g_tracked[i];
+ const uintptr_t node = FindStreamNode(t.handle);
+ if (node != 0 && PathHash(node) == t.pathHash) {
+ g_tracked[keep++] = t; // still playing
+ continue;
+ }
+ if (slot >= 0)
+ Event::Custom::Fire(slot, "%u", static_cast(t.handle));
+ }
+ g_tracked.resize(keep);
+}
+
+const Tick::WorldTick::AutoSubscribe _tick{&OnWorldTick};
+
+// Play a row by id and push `willPlay, soundHandle`.
+//
+// `optionalBase` is the 1-based stack index of the `channel` argument, with
+// `forceNoDuplicates` and `runFinishCallback` after it — or 0 for a caller
+// that takes none of them. The global `PlaySound` passes 0: it gains only
+// the id form, and the fuller argument list belongs to `C_Sound.PlaySound`.
+//
+// `channel` is the engine's sound category (0..12; 0 is what the engine
+// itself uses for UI sounds and music, 3 for a file played by path). A
+// channel NAME is accepted and ignored, so code written against the modern
+// string form still runs — the categories here do not correspond to it.
+//
+// `forceNoDuplicates` is likewise accepted and does nothing. The engine
+// does have a by-path dedup, but it is bit 0 of a flag word the row itself
+// supplies; the by-id player ORs in only bits 1, 2 and 4 from its
+// arguments, so there is no way to ask for it without bypassing that
+// player and re-deriving its weighted file pick, which would be a worse
+// trade than the missing flag.
+//
+// `runFinishCallback` opts the sound in to SOUNDKIT_FINISHED.
+int PlayById(void *L, int soundKitID, int optionalBase) {
if (soundKitID <= 0) {
Game::Lua::PushBool(L, false);
Game::Lua::PushNil(L);
@@ -85,15 +170,22 @@ int PlayById(void *L, int soundKitID, int argChannel) {
}
int category = 0;
- if (Game::Lua::Type(L, argChannel) == Game::Lua::TYPE_NUMBER) {
- category = static_cast(Game::Lua::ToNumber(L, argChannel));
- if (category < 0 || category > Offsets::SOUND_CATEGORY_MAX)
- category = 0; // the engine rejects the rest outright
+ bool runFinishCallback = false;
+ if (optionalBase > 0) {
+ if (Game::Lua::Type(L, optionalBase) == Game::Lua::TYPE_NUMBER) {
+ category = static_cast(Game::Lua::ToNumber(L, optionalBase));
+ if (category < 0 || category > Offsets::SOUND_CATEGORY_MAX)
+ category = 0; // the engine rejects the rest outright
+ }
+ runFinishCallback = Game::Lua::ToBoolean(L, optionalBase + 2) != 0;
}
auto play = reinterpret_cast(Offsets::FUN_SOUND_PLAY_ENTRY);
void *handle = play(0, 0, category, soundKitID, kVariantRandom, 0);
+ if (handle != nullptr && runFinishCallback)
+ TrackForFinish(reinterpret_cast(handle));
+
Game::Lua::PushBool(L, handle != nullptr);
if (handle != nullptr)
Game::Lua::PushNumber(L, static_cast(reinterpret_cast(handle)));
@@ -102,16 +194,19 @@ int PlayById(void *L, int soundKitID, int argChannel) {
return 2;
}
-// C_Sound.PlaySound(soundKitID [, channel]) -> willPlay, soundHandle
+// C_Sound.PlaySound(soundKitID [, channel [, forceNoDuplicates
+// [, runFinishCallback]]]) -> willPlay, soundHandle
int __fastcall Script_C_Sound_PlaySound(void *L) {
if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_NUMBER) {
- Game::Lua::Error(L, "Usage: C_Sound.PlaySound(soundKitID [, channel])");
+ Game::Lua::Error(L,
+ "Usage: C_Sound.PlaySound(soundKitID [, channel [, forceNoDuplicates "
+ "[, runFinishCallback]]])");
return 0;
}
return PlayById(L, static_cast(Game::Lua::ToNumber(L, 1)), 2);
}
-// The global `PlaySound(soundKitID | soundName [, channel])`.
+// The global `PlaySound(soundKitID | soundName)`.
//
// The engine's own `PlaySound` takes a SoundEntries row NAME
// ("igMainMenuOpen"); the modern one takes that row's id. Both now work:
@@ -119,13 +214,18 @@ int __fastcall Script_C_Sound_PlaySound(void *L) {
// else tail-calls the engine with the stack untouched, so the name form
// behaves exactly as it always has (it pushes no return values).
//
+// The id form is the ONLY thing added here — the optional channel /
+// forceNoDuplicates / runFinishCallback arguments live on
+// `C_Sound.PlaySound` instead, which keeps this global as close to the
+// one it replaces as the extension allows.
+//
// Discriminating on `lua_type`, not `lua_isnumber`: the latter also
// accepts a numeric STRING, which would quietly reroute `PlaySound("123")`
// away from the name lookup. No row in this table is named with digits, so
// nothing real is lost, but the type test is the honest rule.
int __fastcall Script_PlaySound(void *L) {
if (Game::Lua::Type(L, 1) == Game::Lua::TYPE_NUMBER)
- return PlayById(L, static_cast(Game::Lua::ToNumber(L, 1)), 2);
+ return PlayById(L, static_cast(Game::Lua::ToNumber(L, 1)), 0);
return reinterpret_cast(Offsets::FUN_SCRIPT_PLAY_SOUND)(L);
}