From 930b0c6492b4779eaac20443ccd04f982769a72c Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Tue, 15 Sep 2026 10:18:36 -0500 Subject: [PATCH] Add C_LossOfControl.GetSchoolLockout Serving the school-interrupt lockout through the generic list costs a caller two full BuildList passes -- GetActiveLossOfControlDataCount runs one and GetActiveLossOfControlData runs another -- plus a Lua table per entry, and BuildList classifies up to 16 debuff slots with RecordForID on each. All of that aura work is waste for a caller that only wants the lockout, and a macro conditional reading it every frame pays it every frame. The state behind it is g_schoolLock, seven pairs of ticks. Read it directly: no table, no debuff scan, one pass. Return a mask rather than a school. Each SMSG_SPELL_COOLDOWN batch locks one school, so being kicked on fire and then frost leaves two entries active, and a caller walking the list and stopping at the first SCHOOL_INTERRUPT drops the rest. filterMask narrows the scan, which is how a caller gets one school's own remaining time instead of the aggregate. Also document that the ADDED/UPDATE events diff which effects are active, so re-locking an already-locked school extends endMs without firing either one -- that expiry cannot be cached on the events. --- README.md | 2 +- docs/API.md | 42 ++++++++++++++++++++++++++++++ src/lossofcontrol/Info.cpp | 52 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 95 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d68f9c32..4fb394de 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ reference in **[docs/API.md](docs/API.md)**. | [Item](docs/API.md#item) | `C_Item.DoesItemExist`, `C_Item.DoesItemExistByID`, `C_Item.EquipItemByName`, `C_Item.GetCurrentItemLevel`, `C_Item.GetDetailedItemLevelInfo`, `C_Item.GetEnchantInfo`, `C_Item.GetItemCount`, `C_Item.GetItemFamily`, `C_Item.GetItemGUID`, `C_Item.GetItemIcon`, `C_Item.GetItemIconByID`, `C_Item.GetItemID`, `C_Item.GetItemInfo`, `C_Item.GetItemInfoInstant`, `C_Item.GetItemInventorySlotInfo`, `C_Item.GetItemInventorySlotKey`, `C_Item.GetItemInventoryType`, `C_Item.GetItemInventoryTypeByID`, `C_Item.GetItemLink`, `C_Item.GetItemLocation`, `C_Item.GetItemMaxStackSize`, `C_Item.GetItemMaxStackSizeByID`, `C_Item.GetItemName`, `C_Item.GetItemNameByID`, `C_Item.GetItemQuality`, `C_Item.GetItemQualityByID`, `C_Item.GetItemSellPrice`, `C_Item.GetItemSellPriceByID`, `C_Item.GetItemSetID`, `C_Item.GetItemSetIDByID`, `C_Item.GetItemSetInfo`, `C_Item.GetItemSpell`, `C_Item.GetItemStatDelta`, `C_Item.GetItemStats`, `C_Item.GetItemClassInfo`, `C_Item.GetItemSubClassInfo`, `C_Item.GetItemTempEnchantInfo`, `C_Item.GetItemUniqueness`, `C_Item.GetItemUniquenessByID`, `C_Item.GetStackCount`, `C_Item.GetWeaponEnchantInfo`, `C_Item.IsBound`, `C_Item.IsConsumableItem`, `C_Item.IsEquippableItem`, `C_Item.IsEquippedItem`, `C_Item.IsItemDataCached`, `C_Item.IsItemDataCachedByID`, `C_Item.IsItemGUIDInInventory`, `C_Item.IsItemInRange`, `C_Item.IsItemOpenable`, `C_Item.IsLocked`, `C_Item.LockItem`, `C_Item.LockItemByGUID`, `C_Item.PickupItem`, `C_Item.UnlockAllItems`, `C_Item.UnlockItem`, `C_Item.RequestLoadItemData`, `C_Item.RequestLoadItemDataByID`, `C_Item.UseAtCursor`, `C_Item.UseAtUnit`, `C_Item.UseItemByName`, `GetAuctionItemID`, `GetAuctionSellItemID`, `GetAverageItemLevel`, `GetCraftReagentItemID`, `GetInboxItemID`, `GetInventoryItemDurability`, `GetInventoryItemID`, `GetInventoryItemsForSlot`, `GetInventoryItemRepairCost`, `GetItemClassInfo`, `GetItemIcon`, `GetItemSubClassInfo`, `GetLootRollItemID`, `GetLootSlotItemID`, `GetMerchantItemID`, `GetQuestItemID`, `GetQuestLogItemID`, `GetTradePlayerItemID`, `GetTradeSkillItemID`, `GetTradeSkillReagentItemID`, `GetTradeTargetItemID`, `OffhandHasWeapon` | | [Loot](docs/API.md#loot) | `C_Loot.GetNearbyLootableUnits`, `C_Loot.GetLastScanResults`, `C_Loot.IsScanInProgress`, `C_Loot.LootAllCorpses`, `C_Loot.LootUnit`, `C_Loot.LootUnitItem`, `C_Loot.ScanNearbyLoot` | | [LootHistory](docs/API.md#loothistory) | `C_LootHistory.GetNumItems`, `C_LootHistory.GetItem`, `C_LootHistory.GetPlayerInfo`, `C_LootHistory.Clear` | -| [LossOfControl](docs/API.md#lossofcontrol) | `C_LossOfControl.GetActiveLossOfControlData`, `C_LossOfControl.GetActiveLossOfControlDataCount` | +| [LossOfControl](docs/API.md#lossofcontrol) | `C_LossOfControl.GetActiveLossOfControlData`, `C_LossOfControl.GetActiveLossOfControlDataCount`, `C_LossOfControl.GetSchoolLockout` | | [Lua](docs/API.md#lua) | `collectgarbage` (5.1 options), `coroutine.create`, `coroutine.resume`, `coroutine.running`, `coroutine.status`, `coroutine.wrap`, `coroutine.yield`, `CreateFromMixins`, `math.fmod`, `math.huge`, `math.modf`, `Mixin`, `select`, `string.gmatch`, `string.gsub` (table replacement), `string.match`, `string.reverse`, `strjoin`, `strreplace`, `strrev`, `strsplit`, `strtrim`, `table.count`, `table.maxn`, `table.wipe`, `unpack` (range args), `xpcall` (argument forwarding) | | [Macros](docs/API.md#macros) | `C_Macro.CreateMacro`, `C_Macro.EditMacro`, `C_Macro.SetMacroDisplay`, `GetLooseMacroIcons`, `GetLooseMacroItemIcons`, `GetMacroIcons`, `GetMacroItem`, `GetMacroItemIcons`, `GetMacroSpell`, `StopMacro` | | [Mail](docs/API.md#mail) | `GetInboxItemLink`, `GetSendMailItemLink` | diff --git a/docs/API.md b/docs/API.md index fee8867f..db98842a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -431,6 +431,7 @@ build instructions. - [LossOfControl](#lossofcontrol) - [`C_LossOfControl.GetActiveLossOfControlDataCount()`](#c_lossofcontrolgetactivelossofcontroldatacount) - [`C_LossOfControl.GetActiveLossOfControlData(index)`](#c_lossofcontrolgetactivelossofcontroldataindex) + - [`C_LossOfControl.GetSchoolLockout([filterMask])`](#c_lossofcontrolgetschoollockoutfiltermask) - [Lua](#lua) - [Lua 5.1 syntax](#lua-51-syntax) @@ -10505,8 +10506,49 @@ Fidelity notes: `Aura::Source` cache) and are `nil` otherwise. These fields are nullable. - **`auraInstanceID`** is omitted (`nil`) — no equivalent here. +### `C_LossOfControl.GetSchoolLockout([filterMask])` + +Returns `lockedMask, secondsRemaining` for the school-interrupt lockout — the +`SCHOOL_INTERRUPT` slice of the list above, without building the list. + +```lua +local mask, remaining = C_LossOfControl.GetSchoolLockout() +if mask ~= 0 then + print(C_Spell.GetSchoolString(mask), "locked for", remaining) +end + +-- One school's own remaining time. Masks are 1 << schoolIndex: +-- physical 1, holy 2, fire 4, nature 8, frost 16, shadow 32, arcane 64. +local locked, fireRemaining = C_LossOfControl.GetSchoolLockout(4) +if locked ~= 0 and fireRemaining < 0.5 then + -- fire clears within half a second +end +``` + +| Return | Type | Notes | +|---|---|---| +| `lockedMask` | number | Every currently locked school OR'd together, as `1 << schoolIndex` — the same shape as `lockoutSchool`. `0` when nothing is locked. | +| `secondsRemaining` | number? | Until every school in `lockedMask` is clear, i.e. the lockout ending last. `nil` when `lockedMask` is `0`. | + +`filterMask` narrows the scan to those schools, so one school's own remaining +time is `GetSchoolLockout(1 << schoolIndex)`. Omitted or `0` means all schools. + +Two schools can be locked at the same time — each `SMSG_SPELL_COOLDOWN` batch +locks one, so being kicked on fire and then on frost leaves both active. That is +why this returns a mask rather than a single school, and why walking the list +above and stopping at the first `SCHOOL_INTERRUPT` entry is wrong. + +Prefer this over the list walk whenever only the school lockout matters: it +reads the lockout state directly, allocating no table and skipping the +debuff scan that every `GetActiveLossOfControlData` call performs. Cheap enough +to call per frame from a macro conditional. + The `LOSS_OF_CONTROL_ADDED` / `LOSS_OF_CONTROL_UPDATE` events fire as these effects change — see [Events](#loss_of_control_added--loss_of_control_update-events). +Note that they are driven by a diff of *which* effects are active, so +re-locking an already-locked school extends its lockout without firing either +event. Read the remaining time when you need it rather than caching it on the +events. For the effect that blocks one specific spell, shaped as a cooldown, see [`C_Spell.GetSpellLossOfControlCooldown`](#c_spellgetspelllossofcontrolcooldownspellidentifier) diff --git a/src/lossofcontrol/Info.cpp b/src/lossofcontrol/Info.cpp index ce1443b4..f60096a0 100644 --- a/src/lossofcontrol/Info.cpp +++ b/src/lossofcontrol/Info.cpp @@ -359,6 +359,56 @@ int __fastcall Script_GetActiveLossOfControlData(void *L) { return 1; } +// `C_LossOfControl.GetSchoolLockout([filterMask])` -> lockedMask, seconds. +// +// The school-interrupt slice of the active list, served without building the +// list: reads `g_schoolLock` directly, so it allocates no table and skips the +// 16-slot aura scan every `GetActiveLossOfControlData` call pays for. Sized for +// per-frame conditional evaluation, where that scan and a table per call are +// the whole cost. +// +// `lockedMask` ORs *every* currently locked school (`1 << schoolIndex`, the +// same shape as `lockoutSchool`). Two schools can be locked at once — each +// SMSG_SPELL_COOLDOWN batch locks one — so a caller that stops at the first +// SCHOOL_INTERRUPT entry silently drops the rest. +// +// `seconds` runs until every school in `lockedMask` is clear, i.e. the lockout +// ending last. It is absent (nil) when nothing is locked. +// +// `filterMask` narrows the scan to those schools, so one school's own remaining +// time is `GetSchoolLockout(1 << schoolIndex)`. Omitted or 0 means all schools. +int __fastcall Script_GetSchoolLockout(void *L) { + int filter = ~0; // every school + if (Game::Lua::IsNumber(L, 1)) { + const int arg = static_cast(Game::Lua::ToNumber(L, 1)); + if (arg != 0) + filter = arg; + } + + const uint32_t now = NowMs(); + int locked = 0; + uint32_t longest = 0; + for (int s = 0; s < Offsets::SPELL_SCHOOL_COUNT; ++s) { + const int bit = 1 << s; + if ((filter & bit) == 0) + continue; + const uint32_t endMs = g_schoolLock[s].endMs; + if (endMs == 0 || Reached(now, endMs)) + continue; + locked |= bit; + // Compare durations, never raw ticks -- see `Time::Clock`. + const uint32_t remain = Time::Clock::Remaining(now, endMs); + if (remain > longest) + longest = remain; + } + + Game::Lua::PushNumber(L, static_cast(locked)); + if (locked == 0) + return 1; // nothing locked -> no time to report + Game::Lua::PushNumber(L, static_cast(longest) * 0.001); + return 2; +} + } // namespace bool LockoutForSpell(int spellID, uint32_t *startMs, uint32_t *endMs) { @@ -396,6 +446,8 @@ static void RegisterLuaFunctions() { Game::Lua::RegisterTableFunction("C_LossOfControl", "GetActiveLossOfControlData", &Script_GetActiveLossOfControlData); + Game::Lua::RegisterTableFunction("C_LossOfControl", "GetSchoolLockout", + &Script_GetSchoolLockout); } static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};