Шпаргалка по API аддонов WoW Forever для интерфейса 16001

Исчезнувшие глобальные функции

WoW Forever Builds обнаружил отсутствие этих глобальных функций эпохи Classic в сборке 69913. Модели, обученные на старом коде, продолжают их использовать:

Заклинания и предметы

Поиск может не вернуть результат. C_Spell.GetSpellInfo или C_Item.GetItemInfo для записи, которую клиент еще не загрузил, могут вернуть nil.

local info = C_Spell.GetSpellInfo(spellID)
if not info then
    C_Spell.RequestLoadSpellData(spellID)
    return
end
-- A field can still be secret. Guard before you print it.

local itemName, itemLink = C_Item.GetItemInfo(itemID)
if not itemName then
    C_Item.RequestLoadItemDataByID(itemID)
    return
end

Listen for SPELL_DATA_LOAD_RESULT (spellID, success) and ITEM_DATA_LOAD_RESULT (itemID, success). A nil can mean the record has not loaded or was not found. If the load event returns success false, treat the ID as not found.

Юниты и секретные значения

Blizzard сообщила, что на Forever действуют секретные значения Midnight. Арифметические операции с секретным значением и сравнение с ним вызывают ошибку:

Столбец «Может быть секретным» для названий и логических значений основан на заметках беты Warcraft Forever. Данные о здоровье получены из тестов WoW Forever Builds. Выполните эту проверку перед тем, как использовать значение в условии или показывать его:

local function Sealed(value)
    return type(issecretvalue) == "function" and issecretvalue(value)
end

В шаблонах кода и примере Forever Beacon есть примеры индикаторов состояния с проверкой. Проверьте их на текущей сборке.

События вместо боевого журнала

В Midnight регистрация COMBAT_LOG_EVENT_UNFILTERED вызывает ошибку (Warcraft Wiki, изменения API в патче 12.0.0). Warcraft Forever сообщает, что на Forever чтение боевого журнала недоступно. Вместо этого регистрируйте события юнитов:

Поделиться изображением: заметки к релизу Guidelime v6.000 на GitHub, среди них Initial work to support WoW Forever и пункт Add arrow ETA and TomTom option

Фреймы, время и чат

Фреймы, которым нужен фон, наследуют BackdropTemplate. Для таймеров используйте C_Timer:

local f = CreateFrame("Frame", nil, UIParent, "BackdropTemplate")
f:SetSize(240, 48)
f:SetPoint("CENTER")
f:SetScript("OnEvent", function(self, event, ...) end)

C_Timer.NewTimer(2, function() end)      -- cancellable
C_Timer.After(2, function() end)         -- returns nothing

SLASH_MYADDON1 = "/myaddon"
SlashCmdList["MYADDON"] = function(msg) end

DEFAULT_CHAT_FRAME:AddMessage(text, 0.83, 0.66, 0.35)

Порядок параметров SetTexCoord

SetTexCoord принимает left, right, top, bottom, а не left, top, right, bottom. Передавайте доли от 0 до 1, а не пиксели.

Вызовы, которые не срабатывают без сообщения об ошибке

Warcraft Forever's page, captured September 28, lists these calls as protected on the Forever beta but names no client build:

Важные поля TOC

В аддоне только для Forever в бете укажите интерфейс 16001:

## Interface: 16001
## Title: My Addon
## Notes: What it does in one line
## Author: YourName
## Version: 0.1.0
## SavedVariables: MyAddonDB
## SavedVariablesPerCharacter: MyAddonCharDB
## IconTexture: Interface\Icons\INV_Misc_Note_01
## Category: Miscellaneous
## AddonCompartmentFunc: MyAddon_OnCompartmentClick

Обратные вызовы раздела аддонов должны быть настоящими глобальными функциями, поскольку клиент находит их по имени. Все остальное в файлах объявляйте как локальные переменные на уровне файла. Имена SavedVariables тоже глобальные. Клиент загружает их после выполнения файлов, а затем вызывает ADDON_LOADED для вашего аддона.

API настроек

API настроек заменил старую панель параметров интерфейса и входит в код Mainline, которым пользуется Forever. Если нужны только флажки и ползунки, выберите его вместо собственного окна параметров. Если создаете собственное окно, наследуйте BackdropTemplate, сохраняйте положение при завершении перетаскивания и не перемещайте защищенные фреймы во время блокировки в бою.

InterfaceOptions_AddCategory это старый вызов настроек, который модели все еще часто используют. Вместо него запросите API настроек.

Выбор современного API вместо Classic

Во время сессии вопросов и ответов с разработчиками 17 сентября разработчика спросили, будет ли Forever использовать ограничения для аддонов из Midnight, API Classic или что-то другое. Он ответил: «we did opt for the modern API approach.» («мы все же выбрали современный подход к API»). Подтверждено записью World of Warcraft Developer Q&A на отметке 01:20:52.

По сообщению Wowhead об объявлении Blizzard в Discord для интерфейса WoW, те же изменения API "caused WeakAuras to stop development before Midnight and almost every addon to update." («привели к остановке разработки WeakAuras перед Midnight и заставили обновиться почти все аддоны»). Сообщается. При переносе начните со сборки аддона для Midnight, в которой эти правила уже учтены, а не с ветки Classic Era. Так делают и крупные проекты: в CurseForge для аддона с гайдами RestedXP указан файл «WoW Forever».

Что Blizzard встроила вместо этого

Во время того же стрима участники панели сказали, что в Forever есть собственный счетчик урона и Cooldown Manager. Подтверждено для обоих. Таймер взмахов упомянули только как возможное будущее дополнение. Прежде чем выпускать дубликат, проверьте, не выполняет ли встроенная панель нужную задачу.

Определение Forever из собственного кода

Проверка вида if WOW_PROJECT_ID == WOW_PROJECT_CLASSIC then не определит эту игру. В более раннем тесте WoW Forever Builds на сборке 69913 сообщалось о 1, том же значении, что у WOW_PROJECT_MAINLINE. Сохраненная проверка в игре на сборке 70338 от 12 октября, напротив, записала WOW_PROJECT_ID = 18, WOW_PROJECT_MAINLINE = 1 и WOW_PROJECT_CLASSIC = 2. Константы проекта Camelot от Blizzard задают WOW_PROJECT_CAMELOT = 18. Сообщается о наблюдении в клиенте: прежнее число относится к прошлому и не является текущим правилом определения.Источник: константы проекта Camelot от Blizzard, изучены в сохраненных файлах клиента 70338 13 окт. 2026; проверка в игре записана 12 окт..

Для аддона, работающего в нескольких клиентах, сравните именованную константу, если она существует, затем проверьте конкретный API, нужный вашей функции. Аддон только для Forever может работать непосредственно с Forever:

local isForever = WOW_PROJECT_CAMELOT ~= nil
    and WOW_PROJECT_ID == WOW_PROJECT_CAMELOT
local canReadPreset = C_GameRules
    and type(C_GameRules.GetForeverExperiencePreset) == "function"
if isForever and canReadPreset then
    -- Read the preset; do not infer combat permissions from a project ID.
end

На той же странице приведен еще один способ — через TOC: объявите ## X-Family: [Family] и ## X-Game: [Game], а затем прочитайте их с помощью C_AddOns.GetAddOnMetadata. В примере Wiki сочетание семейства Mainline и игры Camelot означает Forever.

<details><summary>Технические примечания: прежние примеры определения клиента</summary>

Сохраненный пример Warcraft Wiki за сентября сочетал WOW_PROJECT_MAINLINE с LE_EXPANSION_LEVEL_CURRENT == LE_EXPANSION_CLASSIC и называл эту ветку "camelot/forever." Это условие ID проекта Mainline ложно в записанном клиенте 70338. Архитектура интерфейса Mainline не означает ID проекта Mainline. Библиотека, загружаемая только в Classic, молча не загрузится, и никакая ошибка не объяснит причину.

</details>

Получите текущие игровые правила через API интерфейса

Для запросов о режиме игры используйте C_GameRules. Текущие игровые правила — другой вопрос, чем ID проекта клиента, флаг Hardcore или выбранный игроком вариант Classic/Modern. Выбирайте значение, которое действительно нужно вашей функции:

Эти сигнатуры приведены в сгенерированной документации клиента Blizzard; их не угадали по руководствам для Classic.Источник: документация GameRules от Blizzard и документация ChatInfo, сохраненная сборка клиента 70338, изучено 13 окт. 2026.

Для быстрой диагностики после входа в мир введите /dump C_GameRules.GetCurrentGameModeRecordID(). Чтобы прочитать выбранный вариант игры Forever из кода аддона:

local function ReadExperiencePreset()
    if not C_GameRules
        or type(C_GameRules.GetForeverExperiencePreset) ~= "function" then
        return "API unavailable"
    end
    local preset = C_GameRules.GetForeverExperiencePreset()
    if preset == nil then return "Preset unavailable" end
    if preset == Enum.ForeverExperiencePreset.Classic then return "Classic" end
    if preset == Enum.ForeverExperiencePreset.Modern then return "Modern" end
    return "Unknown preset"
end

print(ReadExperiencePreset())

В перечислении Classic имеет значение 0, а Modern — 1. Этот пример читает настройку и ничего не меняет. GAME_RULES_CHANGED и ACTIVE_GAME_MODE_UPDATED — документированные события для обновления отображения игровых правил и активного режима. Их наличие не доказывает, что каждое изменение варианта игры вызывает одно из них. Список функций из записанной проверки включает эти функции; проверка не измеряла возвращаемые ими ID режимов игры и не запускала этот пример.

Шпаргалка по ID звуков

Для встроенного звука интерфейса используйте PlaySound(SOUNDKIT.IG_MAINMENU_OPTION_CHECKBOX_ON). SoundKitConstants.lua от Blizzard в сборке 70338 содержит следующие ID звуковых наборов:

Это ID звуковых наборов, а не заклинаний или аудиофайлов FileDataID. В файлах аддона предпочитайте именованные константы. Чтобы вручную прослушать один из звуков, введите /run PlaySound(SOUNDKIT.IG_MAINMENU_OPTION_CHECKBOX_ON). Мы изучили ID в исходном коде клиента, но не слушали эти звуки.Источник: константы звуковых наборов Blizzard, сохраненная сборка клиента 70338, изучено 13 окт. 2026.

В этой сборке Blizzard делает PlaySound псевдонимом C_Sound.PlaySound. Сгенерированная сигнатура использует UISoundSubType как второй аргумент. Пример с одним аргументом позволяет не копировать в этот клиент старую сигнатуру с каналом-строкой "Master" или "SFX". Отсутствие звука при прослушивании может быть связано с настройками; не включайте звук игрока и не увеличивайте громкость автоматически.Источник: Sound.lua от Blizzard и документация Sound API, сохраненная сборка клиента 70338, изучено 13 окт. 2026.

Функции с несколькими операциями, псевдонимы команд через косую черту, локальную команду сообщения и всплывающее сообщение ищите в практических шаблонах кода.

Почему защищенные фрагменты кода могут не компилироваться

WoW Forever Builds обнаружил еще одну поломку в собственном коде Blizzard с ограниченным выполнением. RestrictedExecution.lua вызывает функцию движка loadstring_untainted, которой нет в сборке 69913. /run print(type(loadstring_untainted)) выводит nil, и все защищенные фрагменты кода завершаются ошибкой вызова nil. Сообщается. По мнению WoW Forever Builds, дело не в политике ограничений, а в недостающей части: код Blizzard ожидает эту функцию.

Аддоны используют защищенные фрагменты для действий, безопасных в бою: переключения страниц панели действий, защищенных заголовков групп и каста по клику. Если появляется именно эта ошибка, в вашей сборке не работает система фрагментов, а не ваш код. Проверяйте ее в каждой новой сборке.

Счетчик ошибок при выполнении действия

A protected call like ChatFrame_OpenChat does not raise a Lua error you can catch on this client, so pcall will not warn you. Warcraft Forever's page, captured September 28 with no build named, reports that the client posts "Interface action failed because of an AddOn" and bumps a counter in the AddOns panel, which clears only on a full restart, not /reload. Unverified community report. A rising counter means you should check your protected calls.

Что зараженный код может делать с секретным значением

В таблице «Юниты и секретные значения» описаны арифметические операции и сравнения. Правила Wiki охватывают больше случаев, причем некоторые операции разрешены, а некоторые — нет. Зараженный код может сохранить секретное значение в переменной, внешней локальной переменной (upvalue) или значении таблицы и передать его функциям Lua. Функции C принимают его, только если Blizzard разрешила им это. Зараженный код также может объединять секретные строки и числа и передавать их в string.format, string.concat или string.join.

Зараженный код не может выполнять арифметические операции над секретным значением, сравнивать его, применять к нему оператор длины, сохранять его как ключ таблицы, обращаться по индексу или вызывать его. Условие на истинность работает для секретной строки или числа, поскольку скрыто только значение, но не для секретного логического значения. type(secret) при этом возвращает настоящий тип. Любая запрещенная операция немедленно вызывает ошибку, поэтому проверяйте значение до ветвления.

Порядок загрузки SavedVariables и ошибка восстановления в бете

Клиент выполняет файлы аддона, затем загружает его SavedVariables и SavedVariablesPerCharacter и вызывает для него ADDON_LOADED — по одному аддону за раз. PLAYER_LOGIN вызывается после загрузки всех аддонов, не требующих загрузки по запросу. Чтобы внести последнее изменение перед записью файла, используйте PLAYER_LOGOUT — последнее событие перед сохранением.

В сообщении об ошибке на форуме Blizzard от 21 сентября показано, что настройки Soundtrack правильно записались в папку WTF, но пропали при следующем запуске. Другие авторы аддонов в теме сообщили о той же проблеме. Не подтверждено, сообщения сообщества. 25 сентября другой автор сообщил, что SavedVariables снова загружались в сборке 1.60.1.70009. Проверьте свой аддон, прежде чем полагаться на исправление.

Две ловушки при переносе, описанные в одном сообщении

Сначала перенос Soundtrack завершился ошибкой в AceDB-3,0: regionKey имел значение nil. На бете GetCurrentRegion() вернул идентификатор региона, который встроенная библиотека не распознала; после изменения AceDB для обработки неизвестных идентификаторов ошибка исчезла. Автор также разделил один флаг IsRetail на два, поскольку в Forever «использовать современный API» и «включить контент только для Retail» — разные вещи.

Моменты срабатывания событий табличек имен в клиенте беты

Warcraft Forever сообщает, что NAME_PLATE_UNIT_ADDED срабатывает до заполнения данных юнита, а у фреймов табличек имен нет namePlateUnitToken. Не подтверждено. Как сообщается, проблему можно обойти, повторно проверив юнита чуть позже или самостоятельно перебрав юнитов от nameplate1 до nameplate40.

Раздел аддонов: регистрация без полей TOC

Поля TOC выше подходят для кнопки раздела аддонов, которая никогда не меняется. Если ее значок или подпись выбираются во время выполнения, Warcraft Wiki описывает ручной вызов:

AddonCompartmentFrame:RegisterAddon({
    text = "My Addon",
    icon = "Interface\\Icons\\TEMP.blp",
    notCheckable = true,
    func = function(button, menuInputData)
        print("Clicked " .. menuInputData.buttonName)
    end,
})

Это взято из документации Mainline, а не из теста Forever, поэтому проверьте, срабатывает ли вызов в вашей сборке. Если вы пишете код с помощью системного промпта ИИ, библиотека промптов для кода аддонов содержит эти ограничения в одном месте. Для игроков на странице аддонов, работающих в Forever указано, что еще запускается.