diff --git a/README.md b/README.md index c4265bbc..bd156f71 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**. | [MerchantFrame](docs/API.md#merchantframe) | `C_MerchantFrame.GetBuybackItemID`, `C_MerchantFrame.GetItemInfo`, `C_MerchantFrame.GetNumJunkItems`, `C_MerchantFrame.IsMerchantItemRefundable`, `C_MerchantFrame.IsSellAllJunkEnabled`, `C_MerchantFrame.SellAllJunkItems` | | [NameCache](docs/API.md#namecache) | `C_CreatureInfo.GetCreatureID`, `C_PlayerCache.GetPlayerInfoByName`, `C_PlayerCache.IsEnabled`, `C_PlayerCache.IsScanEnabled`, `C_PlayerCache.RememberPlayer`, `C_PlayerCache.SetEnabled`, `C_PlayerCache.SetScanEnabled`, `C_PlayerInfo.GUIDIsCreature`, `C_PlayerInfo.GUIDIsGameObject`, `C_PlayerInfo.GUIDIsPet`, `C_PlayerInfo.GUIDIsPlayer`, `GetPlayerInfoByGUID` | | [Quest](docs/API.md#quest) | `C_QuestLog.GetQuestIDForLogIndex`, `C_QuestLog.GetTitleForQuestID`, `C_QuestLog.IsOnQuest`, `C_QuestLog.IsQuestDataCachedByID`, `C_QuestLog.IsUnitOnQuest`, `C_QuestLog.RequestLoadQuestByID`, `GetQuestLogLeaderBoardID` | -| [Spell](docs/API.md#spell) | `C_Spell.CancelSpellByID`, `C_Spell.DoesSpellExist`, `C_Spell.GetSpellCooldown`, `C_Spell.GetSpellDescription`, `C_Spell.GetSpellInfo`, `C_Spell.GetSpellLink`, `C_Spell.GetSpellName`, `C_Spell.GetSpellReagents`, `C_Spell.GetSpellTexture`, `C_Spell.IsCurrentSpell`, `C_Spell.IsSpellHarmful`, `C_Spell.IsSpellHelpful`, `C_Spell.IsSpellPassive`, `C_Spell.IsSpellUsable`, `C_SpellBook.GetCurrentLevelSpells`, `C_SpellBook.GetSpellLevelLearned`, `C_SpellBook.GetSpellSkillLine`, `CancelSpellByName`, `CastSpellNoToggle`, `FindSpellBookSlotByID`, `GetCraftSpellID`, `GetSpellInfo`, `GetSpellLink`, `GetSpellSchool`, `IsHarmfulSpell`, `IsHelpfulSpell`, `IsPassiveSpell`, `IsPlayerSpell`, `IsSpellKnown`, `IsUsableSpell` | +| [Spell](docs/API.md#spell) | `C_Spell.CancelSpellByID`, `C_Spell.DoesSpellExist`, `C_Spell.GetSchoolString`, `C_Spell.GetSpellCooldown`, `C_Spell.GetSpellDescription`, `C_Spell.GetSpellInfo`, `C_Spell.GetSpellLink`, `C_Spell.GetSpellName`, `C_Spell.GetSpellReagents`, `C_Spell.GetSpellTexture`, `C_Spell.IsCurrentSpell`, `C_Spell.IsSpellHarmful`, `C_Spell.IsSpellHelpful`, `C_Spell.IsSpellPassive`, `C_Spell.IsSpellUsable`, `C_SpellBook.GetCurrentLevelSpells`, `C_SpellBook.GetSpellLevelLearned`, `C_SpellBook.GetSpellSkillLine`, `CancelSpellByName`, `CastSpellNoToggle`, `FindSpellBookSlotByID`, `GetCraftSpellID`, `GetSpellInfo`, `GetSpellLink`, `GetSpellSchool`, `IsHarmfulSpell`, `IsHelpfulSpell`, `IsPassiveSpell`, `IsPlayerSpell`, `IsSpellKnown`, `IsUsableSpell` | | [State](docs/API.md#state) | `CancelShapeshiftForm`, `Dismount`, `GetMirrorTimerInfo`, `GetMirrorTimerProgress`, `GetShapeshiftFormID`, `IsAssistingRitual`, `IsFalling`, `IsInGroup`, `IsInRaid`, `IsMounted`, `IsStealthed`, `IsSwimming` | | [Table](docs/API.md#table) | `table.wipe` | | [Talent](docs/API.md#talent) | `GetTalentIDByIndex`, `GetTalentSpellID` | diff --git a/docs/API.md b/docs/API.md index 9bb9a82b..664f1f3d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -217,6 +217,7 @@ build instructions. - [Spell](#spell) - [`C_Spell.DoesSpellExist(spellID)`](#c_spelldoesspellexistspellid) + - [`C_Spell.GetSchoolString(schoolMask)`](#c_spellgetschoolstringschoolmask) - [`GetSpellInfo(spellID)` / `GetSpellInfo(slot, bookType)`](#getspellinfospellid--getspellinfoslot-booktype) - [`C_Spell.GetSpellInfo(spellID)`](#c_spellgetspellinfospellid) - [`C_Spell.GetSpellName(spellID)`](#c_spellgetspellnamespellid) @@ -4918,6 +4919,37 @@ if C_Spell.DoesSpellExist(133) then end ``` +### `C_Spell.GetSchoolString(schoolMask)` + +Returns the localized name for a damage-school bitmask. Resolves +single-bit masks via the engine's `SPELL_SCHOOL_CAP` global +strings (`SPELL_SCHOOL0_CAP` = "Physical", `SPELL_SCHOOL2_CAP` = +"Fire", etc.). + +```lua +C_Spell.GetSchoolString(4) -- "Fire" +C_Spell.GetSchoolString(32) -- "Shadow" +``` + +Vanilla spells are single-school — the multi-school combos +("Frostfire", "Shadowflame", "Spellstorm", etc.) were TBC-and-later +additions. Any multi-bit mask returns `"Unknown"`, matching the +modern API's documented fallback for unnamed combinations. + +> Lua 5.0 doesn't support hex literals (`0x04` is a syntax error); +> pass mask values as decimals, or via `tonumber("0x04", 16)` if you +> want to keep hex notation in source. + +| Decimal | Hex | School | +|--------:|-----|--------| +| `1` | `0x01` | Physical | +| `2` | `0x02` | Holy | +| `4` | `0x04` | Fire | +| `8` | `0x08` | Nature | +| `16` | `0x10` | Frost | +| `32` | `0x20` | Shadow | +| `64` | `0x40` | Arcane | + ### `GetSpellInfo(spellID)` / `GetSpellInfo(slot, bookType)` Returns the same nine values as 3.3.5's `GetSpellInfo`, **plus a 10th diff --git a/src/spell/SchoolString.cpp b/src/spell/SchoolString.cpp new file mode 100644 index 00000000..05cb5fd9 --- /dev/null +++ b/src/spell/SchoolString.cpp @@ -0,0 +1,70 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU Lesser 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 Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License along with +// ClassicAPI. If not, see . + +// `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_CAP` global string and return "Unknown" for any +// combination — matching the modern API's documented fallback. + +#include "Game.h" +#include "Offsets.h" + +#include +#include + +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(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; +} + +static void RegisterLuaFunctions() { + Game::Lua::RegisterTableFunction("C_Spell", "GetSchoolString", + &Script_GetSchoolString); +} + +static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; + +} // namespace Spell::SchoolString