phaneron/Kelsidavis-WoWee
1
0
Fork 0
mirror of https://github.com/Kelsidavis/WoWee.git synced 2026-05-11 03:23:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

feat(pipeline): add WSND (Wowee Sound Catalog) format

Browse source 
Novel open replacement for Blizzard's SoundEntries.dbc +
SoundEntriesAdvanced.dbc. The 10th open format added to the
editor — covers the audio-metadata gap (the previous 9 cover
geometry, terrain, atmosphere, and world manifests, but no
sound metadata).

Format:
  • magic "WSND", version 1, little-endian
  • catalogName + entry count
  • per entry: soundId / kind / flags / volume /
    minDistance / maxDistance / filePath / label

Kind enum (7 categories):
  sfx, music, ambient, ui, voice, spell, combat

Flags packed (3 bits used, rest reserved):
  loop (0x01), 3d (0x02), stream (0x04)

API: WoweeSoundLoader::save / load / exists; presets
makeStarter (one entry per kind), makeAmbient (wilderness
loops + footsteps), makeTavern (fire + crowd + drink + door
+ lute).

CLI added (5 flags, 465 documented total now):
  --gen-sound-catalog <base> [name]
  --gen-sound-catalog-ambient <base> [name]
  --gen-sound-catalog-tavern <base> [name]
  --info-wsnd <base> [--json]
  --validate-wsnd <base> [--json]

Validator catches: out-of-range kind, NaN/inf volume or
distances, 3D sounds with bad min/max, duplicate sound IDs,
empty filePaths.

All 3 presets verified: save / load / validate clean
on first run. Variable-length string fields use length-
prefixed encoding with a 1 MiB sanity cap on read to
prevent corrupted-file allocation blowups.
This commit is contained in:
Kelsi 2026-05-09 14:47:16 -07:00
parent 13312096ea
commit 36d63d8dd0
8 changed files with 566 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

3
tools/editor/cli_arg_required.cpp
View file

@ -25,6 +25,9 @@ const char* const kArgRequired[] = {
"--gen-world-map-arena",
"--info-womx", "--validate-womx",
"--export-womx-json", "--import-womx-json",
"--gen-sound-catalog", "--gen-sound-catalog-ambient",
"--gen-sound-catalog-tavern",
"--info-wsnd", "--validate-wsnd",
"--gen-weather-temperate", "--gen-weather-arctic",
"--gen-weather-desert", "--gen-weather-stormy",
"--gen-zone-atmosphere",

2
tools/editor/cli_dispatch.cpp
View file

@ -37,6 +37,7 @@
#include "cli_info_audio.hpp"
#include "cli_world_info.hpp"
#include "cli_world_map.hpp"
#include "cli_sound_catalog.hpp"
#include "cli_quest_objective.hpp"
#include "cli_quest_reward.hpp"
#include "cli_clone.hpp"
@ -115,6 +116,7 @@ constexpr DispatchFn kDispatchTable[] = {
handleInfoAudio,
handleWorldInfo,
handleWorldMap,
handleSoundCatalog,
handleQuestObjective,
handleQuestReward,
handleClone,

10
tools/editor/cli_help.cpp
View file

@ -835,6 +835,16 @@ void printUsage(const char* argv0) {
std::printf(" Export binary .womx to a human-editable JSON sidecar (rows of '1'/'0' strings, easy to hand-edit)\n");
std::printf(" --import-womx-json <json-path> [out-base]\n");
std::printf(" Import a .womx.json sidecar back into binary .womx (round-trip with --export-womx-json)\n");
std::printf(" --gen-sound-catalog <wsnd-base> [name]\n");
std::printf(" Emit .wsnd starter catalog (one entry per kind: sfx/music/ambient/ui/voice/spell/combat)\n");
std::printf(" --gen-sound-catalog-ambient <wsnd-base> [name]\n");
std::printf(" Emit .wsnd wilderness catalog: looped birds + wind + 3 footstep variants\n");
std::printf(" --gen-sound-catalog-tavern <wsnd-base> [name]\n");
std::printf(" Emit .wsnd tavern catalog: fire-crackle + crowd murmur + drink-clink + door-creak + lute music\n");
std::printf(" --info-wsnd <wsnd-base> [--json]\n");
std::printf(" Print WSND catalog entries (id / kind / flags / volume / 3D distances / file path / label)\n");
std::printf(" --validate-wsnd <wsnd-base> [--json]\n");
std::printf(" Static checks: kind in 0..6, finite distances, 3D needs max>min>=0, no duplicate sound IDs\n");
std::printf(" --gen-weather-temperate <wow-base> [zoneName]\n");
std::printf(" Emit .wow weather schedule: clear-dominant + occasional rain + fog (forest / grassland)\n");
std::printf(" --gen-weather-arctic <wow-base> [zoneName]\n");

251
tools/editor/cli_sound_catalog.cpp Normal file
View file

@ -0,0 +1,251 @@
#include "cli_sound_catalog.hpp"
#include "pipeline/wowee_sound.hpp"
#include <nlohmann/json.hpp>
#include <cmath>
#include <cstdint>
#include <cstdio>
#include <cstring>
#include <string>
#include <vector>
namespace wowee {
namespace editor {
namespace cli {
namespace {
std::string stripWsndExt(std::string base) {
if (base.size() >= 5 && base.substr(base.size() - 5) == ".wsnd")
base = base.substr(0, base.size() - 5);
return base;
}
void appendFlagsStr(std::string& s, uint32_t flags) {
if (flags & wowee::pipeline::WoweeSound::Loop) s += "loop ";
if (flags & wowee::pipeline::WoweeSound::Is3D) s += "3d ";
if (flags & wowee::pipeline::WoweeSound::Stream) s += "stream ";
if (s.empty()) s = "-";
else if (s.back() == ' ') s.pop_back();
}
bool saveOrError(const wowee::pipeline::WoweeSound& c,
const std::string& base, const char* cmd) {
if (!wowee::pipeline::WoweeSoundLoader::save(c, base)) {
std::fprintf(stderr, "%s: failed to save %s.wsnd\n",
cmd, base.c_str());
return false;
}
return true;
}
void printGenSummary(const wowee::pipeline::WoweeSound& c,
const std::string& base) {
std::printf("Wrote %s.wsnd\n", base.c_str());
std::printf(" catalog : %s\n", c.name.c_str());
std::printf(" entries : %zu\n", c.entries.size());
}
int handleGenStarter(int& i, int argc, char** argv) {
std::string base = argv[++i];
std::string name = "StarterCatalog";
if (i + 1 < argc && argv[i + 1][0] != '-') name = argv[++i];
base = stripWsndExt(base);
auto c = wowee::pipeline::WoweeSoundLoader::makeStarter(name);
if (!saveOrError(c, base, "gen-sound-catalog")) return 1;
printGenSummary(c, base);
return 0;
}
int handleGenAmbient(int& i, int argc, char** argv) {
std::string base = argv[++i];
std::string name = "AmbientCatalog";
if (i + 1 < argc && argv[i + 1][0] != '-') name = argv[++i];
base = stripWsndExt(base);
auto c = wowee::pipeline::WoweeSoundLoader::makeAmbient(name);
if (!saveOrError(c, base, "gen-sound-catalog-ambient")) return 1;
printGenSummary(c, base);
return 0;
}
int handleGenTavern(int& i, int argc, char** argv) {
std::string base = argv[++i];
std::string name = "TavernCatalog";
if (i + 1 < argc && argv[i + 1][0] != '-') name = argv[++i];
base = stripWsndExt(base);
auto c = wowee::pipeline::WoweeSoundLoader::makeTavern(name);
if (!saveOrError(c, base, "gen-sound-catalog-tavern")) return 1;
printGenSummary(c, base);
return 0;
}
int handleInfo(int& i, int argc, char** argv) {
std::string base = argv[++i];
bool jsonOut = (i + 1 < argc &&
std::strcmp(argv[i + 1], "--json") == 0);
if (jsonOut) i++;
base = stripWsndExt(base);
if (!wowee::pipeline::WoweeSoundLoader::exists(base)) {
std::fprintf(stderr, "WSND not found: %s.wsnd\n", base.c_str());
return 1;
}
auto c = wowee::pipeline::WoweeSoundLoader::load(base);
if (jsonOut) {
nlohmann::json j;
j["wsnd"] = base + ".wsnd";
j["name"] = c.name;
j["count"] = c.entries.size();
nlohmann::json arr = nlohmann::json::array();
for (const auto& e : c.entries) {
std::string fs;
appendFlagsStr(fs, e.flags);
arr.push_back({
{"soundId", e.soundId},
{"kind", e.kind},
{"kindName", wowee::pipeline::WoweeSound::kindName(e.kind)},
{"flags", e.flags},
{"flagsStr", fs},
{"volume", e.volume},
{"minDistance", e.minDistance},
{"maxDistance", e.maxDistance},
{"filePath", e.filePath},
{"label", e.label},
});
}
j["entries"] = arr;
std::printf("%s\n", j.dump(2).c_str());
return 0;
}
std::printf("WSND: %s.wsnd\n", base.c_str());
std::printf(" catalog : %s\n", c.name.c_str());
std::printf(" entries : %zu\n", c.entries.size());
if (c.entries.empty()) return 0;
std::printf(" id kind flags vol min max label / file\n");
for (const auto& e : c.entries) {
std::string fs;
appendFlagsStr(fs, e.flags);
std::printf(" %4u %-7s %-12s %4.2f %5.1f %5.1f %s\n",
e.soundId,
wowee::pipeline::WoweeSound::kindName(e.kind),
fs.c_str(),
e.volume, e.minDistance, e.maxDistance,
e.label.empty() ? e.filePath.c_str()
: (e.label + " (" + e.filePath + ")").c_str());
}
return 0;
}
int handleValidate(int& i, int argc, char** argv) {
std::string base = argv[++i];
bool jsonOut = (i + 1 < argc &&
std::strcmp(argv[i + 1], "--json") == 0);
if (jsonOut) i++;
base = stripWsndExt(base);
if (!wowee::pipeline::WoweeSoundLoader::exists(base)) {
std::fprintf(stderr,
"validate-wsnd: WSND not found: %s.wsnd\n", base.c_str());
return 1;
}
auto c = wowee::pipeline::WoweeSoundLoader::load(base);
std::vector<std::string> errors;
std::vector<std::string> warnings;
if (c.entries.empty()) {
warnings.push_back("catalog has zero entries");
}
// Per-entry checks plus a duplicate-soundId scan.
std::vector<uint32_t> idsSeen;
idsSeen.reserve(c.entries.size());
for (size_t k = 0; k < c.entries.size(); ++k) {
const auto& e = c.entries[k];
std::string ctx = "entry " + std::to_string(k) +
" (id=" + std::to_string(e.soundId) + ")";
if (e.kind > wowee::pipeline::WoweeSound::Combat) {
errors.push_back(ctx + ": kind " + std::to_string(e.kind) +
" not in known range 0..6");
}
// Reject NaN/inf early — these crash audio engines.
if (!std::isfinite(e.volume) ||
!std::isfinite(e.minDistance) ||
!std::isfinite(e.maxDistance)) {
errors.push_back(ctx + ": volume/min/max distance not finite");
}
if (e.volume < 0.0f || e.volume > 4.0f) {
warnings.push_back(ctx + ": volume " +
std::to_string(e.volume) +
" outside typical 0..4 range");
}
// 3D sounds need min < max; non-3D sounds usually have
// both at 0 (positional fields ignored at runtime).
if (e.flags & wowee::pipeline::WoweeSound::Is3D) {
if (e.minDistance < 0 || e.maxDistance <= e.minDistance) {
errors.push_back(ctx +
": 3d sound needs minDistance >= 0 and "
"maxDistance > minDistance");
}
}
if (e.filePath.empty()) {
errors.push_back(ctx + ": filePath is empty");
}
for (uint32_t prev : idsSeen) {
if (prev == e.soundId) {
errors.push_back(ctx +
": soundId already used by an earlier entry");
break;
}
}
idsSeen.push_back(e.soundId);
}
bool ok = errors.empty();
if (jsonOut) {
nlohmann::json j;
j["wsnd"] = base + ".wsnd";
j["ok"] = ok;
j["errors"] = errors;
j["warnings"] = warnings;
std::printf("%s\n", j.dump(2).c_str());
return ok ? 0 : 1;
}
std::printf("validate-wsnd: %s.wsnd\n", base.c_str());
if (ok && warnings.empty()) {
std::printf(" OK — %zu entries, all sound IDs unique\n",
c.entries.size());
return 0;
}
if (!warnings.empty()) {
std::printf(" warnings (%zu):\n", warnings.size());
for (const auto& w : warnings)
std::printf(" - %s\n", w.c_str());
}
if (!errors.empty()) {
std::printf(" ERRORS (%zu):\n", errors.size());
for (const auto& e : errors)
std::printf(" - %s\n", e.c_str());
}
return ok ? 0 : 1;
}
} // namespace
bool handleSoundCatalog(int& i, int argc, char** argv, int& outRc) {
if (std::strcmp(argv[i], "--gen-sound-catalog") == 0 && i + 1 < argc) {
outRc = handleGenStarter(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--gen-sound-catalog-ambient") == 0 && i + 1 < argc) {
outRc = handleGenAmbient(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--gen-sound-catalog-tavern") == 0 && i + 1 < argc) {
outRc = handleGenTavern(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--info-wsnd") == 0 && i + 1 < argc) {
outRc = handleInfo(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--validate-wsnd") == 0 && i + 1 < argc) {
outRc = handleValidate(i, argc, argv); return true;
}
return false;
}
} // namespace cli
} // namespace editor
} // namespace wowee

11
tools/editor/cli_sound_catalog.hpp Normal file
View file

@ -0,0 +1,11 @@
#pragma once
namespace wowee {
namespace editor {
namespace cli {
bool handleSoundCatalog(int& i, int argc, char** argv, int& outRc);
} // namespace cli
} // namespace editor
} // namespace wowee