Files
ClassicAPI/src/spell/SchoolString.cpp
T
Brues 108a91a843 feat(api): describe the API in the code, browse it with /classicapi
docs/API.md is 18.7k lines and its anchors are signature slugs, so editing a
signature breaks the 281 internal and 88 README links into it. Blizzard
solved the same problem by shipping the API as data plus a browser addon,
and warcraft.wiki.gg renders those same tables. One set of descriptors can
feed all three.

Each registration now carries one next to it: typed arguments and returns,
nilability, defaults, and a sentence. Events, enumerations and returned table
shapes are described the same way. No Script_* body changed.

Game.h gains namespace Game::Doc (Field with Req/Opt/Vararg, FieldList,
Function, Method, Structure, Event) and a trailing descriptor argument on all
six Game::Lua::Register* plus Event::Custom::AutoReserve.

api/Documentation.cpp records every registration on the first pass of each
Lua state and seals it, so /reload re-registers but records nothing and the
environment comes from which pass saw the name. Export is lazy: nothing is
materialized until C_APIDocumentation.GetSystem asks for one system, because
eager export would build thousands of tables per reload for a slash command.
_classicapi_UndocumentedAPI lists what still has no descriptor.

AddOns/!!!ClassicAPI/APIDocumentation/ ports Blizzard_APIDocumentation's eight
files. Named /classicapi, not /api: the browser holds only what ClassicAPI
adds, so /api would have implied the whole 1.12 surface. Two deliberate
differences from the retail source, both noted in the file headers: a system
search also matches its namespace, since that is the name people type; and an
undocumented function says so, because an empty signature otherwise reads as
a real one.

LinkUtil gains the SetItemRef to LinkUtil.ProcessLink dispatch. That handler
registry was dead code; a new link type now registers a handler instead of
stacking another SetItemRef override. Also defines assertsafe there, which
was undefined and only mattered once the function went live.

Documented: the C_Spell and C_SpellBook surface, the spell globals, both
spellbook enumerations, the 13 UNIT_SPELLCAST_* events, GameTooltip as the
widget-method example and C_Glue as the glue and mixed-environment example.
66 of 692 function registrations. tools/New-ApiDocSkeletons.ps1 emits
paste-ready skeletons to make the rest of the sweep tractable.

Verified in game: the browser lists, searches, and prints detail; links
render and click through; right-click copies and shift-click dumps.
2026-09-12 23:20:46 -05:00

85 lines
2.9 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/>.
// `C_Spell.GetSchoolString(schoolMask)` — localized name for a damage
// school bitmask. Vanilla spells are single-school (the multi-school
// combos like "Frostfire" / "Shadowflame" / "Spellstorm" were
// TBC-and-later additions), so we resolve any single-bit mask to its
// `SPELL_SCHOOL<n>_CAP` global string and return "Unknown" for any
// combination — matching the modern API's documented fallback.
#include "Game.h"
#include "Offsets.h"
#include <cstdint>
#include <cstdio>
namespace Spell::SchoolString {
namespace {
// Returns the 0-based school index for a single-bit mask, or -1 if
// the mask has zero or multiple bits set (or is out of the 7-school
// range vanilla supports).
int SingleBitSchoolIndex(uint32_t mask) {
if (mask == 0 || (mask & (mask - 1)) != 0)
return -1;
for (int i = 0; i < 7; ++i) {
if (mask == (1u << i))
return i;
}
return -1;
}
} // namespace
static int __fastcall Script_GetSchoolString(void *L) {
if (!Game::Lua::IsNumber(L, 1)) {
Game::Lua::PushString(L, "Unknown");
return 1;
}
const auto mask = static_cast<uint32_t>(Game::Lua::ToNumber(L, 1));
const int idx = SingleBitSchoolIndex(mask);
if (idx < 0) {
Game::Lua::PushString(L, "Unknown");
return 1;
}
char globalName[24];
std::snprintf(globalName, sizeof globalName, "SPELL_SCHOOL%d_CAP", idx);
Game::Lua::PushLocalizedString(L, globalName, "Unknown");
return 1;
}
// --- Documentation ----------------------------------------------------------
const Game::Doc::Field kArgs[] = {
Game::Doc::Req("schoolMask", "number",
"A damage-school bitmask, such as 4 for fire or 32 for shadow."),
};
const Game::Doc::Field kRets[] = {
Game::Doc::Req("school", "string",
"The localized school name, or \"Unknown\" when the mask names "
"more than one school."),
};
const Game::Doc::Function kGetSchoolString{
"The localized name of a damage school.", kArgs, kRets};
static void RegisterLuaFunctions() {
Game::Lua::RegisterTableFunction("C_Spell", "GetSchoolString",
&Script_GetSchoolString, &kGetSchoolString);
}
static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
} // namespace Spell::SchoolString