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

feat(editor): add WIFS (Item Flag Set) open catalog format

Browse source 
Open replacement for the bit-flag meanings used in Item.dbc /
item_template.Flags. Documents every individual bit of the
32-bit item flags field with a human-readable name, description,
kind classification, and is-positive hint.

WoW's Item.dbc Flags field packs ~25 bits of metadata like
Heroic, Lootable, NoLoot, Conjured, BindOnPickup, BindOnEquip —
each controlling a specific gameplay behavior. The hardcoded
client knows what each bit means via a switch statement; this
catalog exposes that table to data-driven editors so:
  - server admins can document custom flag bits
  - tooltip generators can decode "why is this item soulbound?"
    via flag-name lookup (decode(0x40240000) returns
    ["Heroic", "BindOnPickup", "Unique"])
  - validators can warn about contradictory flag combinations

Seven flagKind values classify the bit families (Quality / Drop
/ Trade / Magic / Account / Server / Misc), and an isPositive
hint tells UIs whether the flag enhances the item (green) or
restricts it (red).

Cross-references back to WIT (decodes WIT.flags into the
matching named flag list) and WIQR (validators can pair Heroic
flag with WIQR Epic+ quality requirement).

Three preset emitters: --gen-ifs (8 canonical Item.dbc bits
matching the standard 3.3.5a constants), --gen-ifs-binding (5
binding-related flags BindOnPickup / BindOnEquip / etc — all
restrictive so isPositive=0), --gen-ifs-server (5 server-custom
bits in the upper range demonstrating how to overlay extra
metadata without colliding with Blizzard's bits).

Validation enforces id+name+bitMask presence, flagKind 0..6, no
duplicate ids, no duplicate bitMasks (collision means engine
would only honor first matching name when decoding); warns on
multi-bit masks (unusual — usually want individual bits).

decode(flagsValue) is the engine helper that expands a raw
flags integer into its named flag list — used directly by the
tooltip generator and item info renderers. Wired through the
cross-format table; WIFS appears automatically in all 16
cross-format utilities. Format count 85 -> 86; CLI flag count
1018 -> 1023.
This commit is contained in:
Kelsi 2026-05-09 23:10:35 -07:00
parent f43b444056
commit 0ceb70f3e7
10 changed files with 655 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

243
tools/editor/cli_item_flags_catalog.cpp Normal file
View file

@ -0,0 +1,243 @@
#include "cli_item_flags_catalog.hpp"
#include "cli_arg_parse.hpp"
#include "cli_box_emitter.hpp"
#include "pipeline/wowee_item_flags.hpp"
#include <nlohmann/json.hpp>
#include <cstdint>
#include <cstdio>
#include <cstring>
#include <fstream>
#include <string>
#include <vector>
namespace wowee {
namespace editor {
namespace cli {
namespace {
std::string stripWifsExt(std::string base) {
stripExt(base, ".wifs");
return base;
}
bool saveOrError(const wowee::pipeline::WoweeItemFlags& c,
const std::string& base, const char* cmd) {
if (!wowee::pipeline::WoweeItemFlagsLoader::save(c, base)) {
std::fprintf(stderr, "%s: failed to save %s.wifs\n",
cmd, base.c_str());
return false;
}
return true;
}
void printGenSummary(const wowee::pipeline::WoweeItemFlags& c,
const std::string& base) {
std::printf("Wrote %s.wifs\n", base.c_str());
std::printf(" catalog : %s\n", c.name.c_str());
std::printf(" flags : %zu\n", c.entries.size());
}
int handleGenStandard(int& i, int argc, char** argv) {
std::string base = argv[++i];
std::string name = "StandardItemFlags";
if (parseOptArg(i, argc, argv)) name = argv[++i];
base = stripWifsExt(base);
auto c = wowee::pipeline::WoweeItemFlagsLoader::makeStandard(name);
if (!saveOrError(c, base, "gen-ifs")) return 1;
printGenSummary(c, base);
return 0;
}
int handleGenBinding(int& i, int argc, char** argv) {
std::string base = argv[++i];
std::string name = "BindingItemFlags";
if (parseOptArg(i, argc, argv)) name = argv[++i];
base = stripWifsExt(base);
auto c = wowee::pipeline::WoweeItemFlagsLoader::makeBinding(name);
if (!saveOrError(c, base, "gen-ifs-binding")) return 1;
printGenSummary(c, base);
return 0;
}
int handleGenServer(int& i, int argc, char** argv) {
std::string base = argv[++i];
std::string name = "ServerCustomItemFlags";
if (parseOptArg(i, argc, argv)) name = argv[++i];
base = stripWifsExt(base);
auto c = wowee::pipeline::WoweeItemFlagsLoader::makeServer(name);
if (!saveOrError(c, base, "gen-ifs-server")) return 1;
printGenSummary(c, base);
return 0;
}
int handleInfo(int& i, int argc, char** argv) {
std::string base = argv[++i];
bool jsonOut = consumeJsonFlag(i, argc, argv);
base = stripWifsExt(base);
if (!wowee::pipeline::WoweeItemFlagsLoader::exists(base)) {
std::fprintf(stderr, "WIFS not found: %s.wifs\n", base.c_str());
return 1;
}
auto c = wowee::pipeline::WoweeItemFlagsLoader::load(base);
if (jsonOut) {
nlohmann::json j;
j["wifs"] = base + ".wifs";
j["name"] = c.name;
j["count"] = c.entries.size();
nlohmann::json arr = nlohmann::json::array();
for (const auto& e : c.entries) {
arr.push_back({
{"flagId", e.flagId},
{"name", e.name},
{"description", e.description},
{"bitMask", e.bitMask},
{"flagKind", e.flagKind},
{"flagKindName", wowee::pipeline::WoweeItemFlags::flagKindName(e.flagKind)},
{"isPositive", e.isPositive != 0},
{"iconColorRGBA", e.iconColorRGBA},
});
}
j["entries"] = arr;
std::printf("%s\n", j.dump(2).c_str());
return 0;
}
std::printf("WIFS: %s.wifs\n", base.c_str());
std::printf(" catalog : %s\n", c.name.c_str());
std::printf(" flags : %zu\n", c.entries.size());
if (c.entries.empty()) return 0;
std::printf(" id bitMask kind +/- name\n");
for (const auto& e : c.entries) {
std::printf(" %4u 0x%08x %-9s %s %s\n",
e.flagId, e.bitMask,
wowee::pipeline::WoweeItemFlags::flagKindName(e.flagKind),
e.isPositive ? "+" : "-",
e.name.c_str());
}
return 0;
}
int handleValidate(int& i, int argc, char** argv) {
std::string base = argv[++i];
bool jsonOut = consumeJsonFlag(i, argc, argv);
base = stripWifsExt(base);
if (!wowee::pipeline::WoweeItemFlagsLoader::exists(base)) {
std::fprintf(stderr,
"validate-wifs: WIFS not found: %s.wifs\n", base.c_str());
return 1;
}
auto c = wowee::pipeline::WoweeItemFlagsLoader::load(base);
std::vector<std::string> errors;
std::vector<std::string> warnings;
if (c.entries.empty()) {
warnings.push_back("catalog has zero entries");
}
std::vector<uint32_t> idsSeen;
std::vector<uint32_t> bitsSeen;
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.flagId);
if (!e.name.empty()) ctx += " " + e.name;
ctx += ")";
if (e.flagId == 0)
errors.push_back(ctx + ": flagId is 0");
if (e.name.empty())
errors.push_back(ctx + ": name is empty");
if (e.flagKind > wowee::pipeline::WoweeItemFlags::Misc) {
errors.push_back(ctx + ": flagKind " +
std::to_string(e.flagKind) + " not in 0..6");
}
if (e.bitMask == 0) {
errors.push_back(ctx +
": bitMask is 0 — flag will never match anything");
}
// bitMask should typically be a single bit (power
// of 2). Multi-bit masks are valid but unusual —
// warn so author can confirm.
if (e.bitMask != 0 && (e.bitMask & (e.bitMask - 1)) != 0) {
warnings.push_back(ctx +
": bitMask 0x" + std::to_string(e.bitMask) +
" is not a single bit (multi-bit flags are "
"unusual; usually you want one of the "
"individual bits)");
}
for (uint32_t prev : idsSeen) {
if (prev == e.flagId) {
errors.push_back(ctx + ": duplicate flagId");
break;
}
}
idsSeen.push_back(e.flagId);
// Two flags claiming the same bit is a serious
// collision — engine would only match the first
// entry's name when decoding.
if (e.bitMask != 0) {
for (uint32_t prevBit : bitsSeen) {
if (prevBit == e.bitMask) {
errors.push_back(ctx +
": duplicate bitMask 0x" +
std::to_string(e.bitMask) +
" — collides with another entry");
break;
}
}
bitsSeen.push_back(e.bitMask);
}
}
bool ok = errors.empty();
if (jsonOut) {
nlohmann::json j;
j["wifs"] = base + ".wifs";
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-wifs: %s.wifs\n", base.c_str());
if (ok && warnings.empty()) {
std::printf(" OK — %zu flags, all flagIds + bitMasks 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 handleItemFlagsCatalog(int& i, int argc, char** argv,
int& outRc) {
if (std::strcmp(argv[i], "--gen-ifs") == 0 && i + 1 < argc) {
outRc = handleGenStandard(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--gen-ifs-binding") == 0 && i + 1 < argc) {
outRc = handleGenBinding(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--gen-ifs-server") == 0 && i + 1 < argc) {
outRc = handleGenServer(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--info-wifs") == 0 && i + 1 < argc) {
outRc = handleInfo(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--validate-wifs") == 0 && i + 1 < argc) {
outRc = handleValidate(i, argc, argv); return true;
}
return false;
}
} // namespace cli
} // namespace editor
} // namespace wowee