1. Введение

При создании статьи использовалась информация с сайта http://www.wowace.com/addons/ace3/pages/getting-started/.

2. Обозначения

1. Везде по тексту MYADDON следует заменять на название вашего аддона - оно должно быть таким, чтобы можно было создать папку с таким именем. Например, PartyAchiever, GuildRaider и так далее.

3. Предварительные действия

Для начала написания аддонов нам нужны:

1. Установленный Wow. Теоретически существуют эмуляторы для тестирования и отладки аддонов, но на данный момент нет их аналогов, поддерживающих актуальную верисю API.
2. Папка в нем: /Interface/Addons. Если ее нет, то создайте - это то место, где хранятся все модификации интерфейса.
3. В ней должна быть папка с названием MYADDON (см. выше) - это папка, в которой вы и будете писать ваш аддон.

   Примечание:
   Что представляет собой аддон с точки зрения файловой структуры. Аддон - это папка, в которой находятся:
   1) MYADDON.toc - файл, описывающий структуру аддона, говорящий программе, использующей его, где находится 
   

4. фактический код для выполнения его функциональности.
   2) Набор сторонних библиотек. Обычно никто не пишет аддон целиком с нуля из-за того, что расписывать 
   

5. одни и те же операции при написании очередного аддона довольно утомительно, кроме того повышается шанс 
   

6. допущения в нем ошибок. Сторонние библиотеки (или же ваши, написанные и отлаженные вами специально для 
   

7. упрощения создания аддонов) могут сильно помочь при их написании, как при отладке, так и предоставлением 
   

8. дополнительных возможностей. В нашем случае мы будем использовать WowAce3.0, 
   

9. скачать который можно здесь: http://www.wowace.com/addons/ace3/files/

10. Набор файлов кода вашего аддона, реализующего требуемый функционал.
11. В этой папке должна быть папка Libs, содержащая используемые библиотеки. В нашем случае это WowAce3.0.

    Примечание:
    Папка может называться и по другому, или быть не одна, ее имя будут использоваться только при установлении 
    

12. зависимостей в embeds.xml (см. ниже)

13. В папке MYADDON должен быть файл MYADDON.toc - это корневой файл, описывающий весь ваш аддон. Его содержимое:

    ## Interface: 30300 -- версия игры, на которой работает аддон (3.3 в нашем случае)
    ## Title: My Title -- Заголовок аддона, то как он будет отображаться в списке установленных аддонов 
    

14. при выборе персонажа
    ## Notes: My Description -- Краткое описание аддона, описание аддона, отображаемое в списке 
    

15. установленных аддонов при выборе персонажа
    ## Author: AuthorName -- Имя автора
    ## Version: 0.1 -- версия аддона
    embeds.xml -- имя файла, описывающего связи между файлами аддона
    Core.lua -- главный исполняемый файл аддона.

    Примечание:
    Все, что пишется в строке после "--" считается комментарием и игнорируется программой:
    -- это комментарий
    Если нужны комментарии на несколько строк, то следует пользоваться выражением:
    --[[
    это
    многострочный
    комментарий
    ]]--

16. В папке MYADDON должен быть файл embeds.toc - это файл, показывающий, какие сторонние библиотеки использует ваш аддон. Его содержимое:

    <Ui xsi:schemaLocation="http://www.blizzard.com/wow/ui/ ..\FrameXML\UI.xsd">
    <Script file="Libs\LibStub\LibStub.lua"/>
    <Include file="Libs\AceAddon-3.0\AceAddon-3.0.xml"/>
    <Include file="Libs\AceConsole-3.0\AceConsole-3.0.xml"/>
    <Include file="Libs\AceDB-3.0\AceDB-3.0.xml"/>
    <Include file="Libs\CallbackHandler-1.0\CallbackHandler-1.0.xml"/>
    <Include file="Libs\AceEvent-3.0\AceEvent-3.0.xml"/>
    <Include file="Libs\AceGUI-3.0\AceGUI-3.0.xml"/>
    </Ui>

    Примечание:
    Мы говорим в нем, что будем использовать весь основной функционал, 
    

17. даваемый WowAce3.0 и указываем, где расположены необходимые библиотеки. 
    

18. Если вы только начинаете знакомство с созданием аддонов, то просто заполните его, 
    

19. как описано выше. Если же вы уже давно разбираетесь в том, чем можно пожертвовать 
    

20. из этого списка или хотите добавить что-то свое, то спокойно можете его отредактировать. 
    

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

    Примечание:
    Существует альтернативный вариант указания зависимостей. 
    

22. Можно перечислить ссылки на данные файлы в самом файле MYADDON.toc, 
    

23. однако это приведет к уменьшению понимания, какие файлы относятся к вашему аддону, 
    

24. а какие к используемым библиотекам.

25. В папке MYADDON должен быть файл Core.lua - главный исполняемый файл аддона, может иметь другое название, но такое же, какое указано в MYADDON.toc. Его содержимое будет описано ниже в разделе написания кода аддона.

4. Отладка аддонов

1. Это отдельный вопрос. Потому как обычные ошибки в аддоне приводят к его закрытию и выдаче сообщения, что аддон упал и не более того. Однако, если у вас на компьютере стоит достаточное количество различных сторонних аддонов, то среди них наверняка есть такой, который бы выводил при это вообщение со стеком ошибки. Кажется, Grabber это делает, хотя по поводу названия я могу сильно ошибаться.
2. Если вы изменяете структуру файлов аддона или зависимости между аддонами, например *.toc, embeds.xml, добавляете что-либо в него, то вам придется перезагрузить Wow, чтобы изменения вступили в силу.
3. Если же изменения локальные, например, изменен текст кнопки или добавлен обработчик события, то достаточно в Wow написать в чат /console reloadui - он перезагрузит ваш аддон. Удобно написать для этого макрос, чтобы каждый раз не набирать текст вручную.
4. Для отладки каких-либо действий в аддоне можно поставить в нем обработчик слеш-команды и также написать на нее макрос.

5. Написание кода

Далее будет описываться содержимое файла Core.lua, что в нем необходимо использовать и что может пригодиться при написании функциональности аддона.

5.1. Минимальный проект

Чтобы ваш аддон мог запуститься и работать (хоть и не выполнять никаких полезных действий) достаточно в Core.lua написать следующее:

MYADDON = LibStub("AceAddon-3.0"):NewAddon("MYADDON")
--[[
Мы используем WowAce. В этой строке мы сообщаем ему, что хотим создать и 
использовать новый аддон MYADDON, функциональность которого будет описана ниже.
При этом библиотека сама позаботится за вас, чтобы Wow смог с ним работать.
]]--
function MYADDON:OnInitialize()
--[[
Функция будет вызвана при загрузке аддона, то есть при входе персонажа в игру.
Обычно здесь можно проинициализировать какие-либо глобальные переменные (если нужно) 
или же сделать какие-либо другие действия.
]]--
end
function MYADDON:OnEnable()
--[[
Функция будет вызвана при включении аддона, обычно при входе персонажа в игру, 
однако также аддоны можно вручную включать/выключать не выходя персонажем.
]]--
end
function MYADDON:OnDisable()
--[[
Функция будет вызвана при выключении аддона, обычно при выходе персонажа из игры, 
однако также аддоны можно вручную включать/выключать не выходя персонажем.
]]--
end

5.2. Вывод сообщений

Запускающийся аддон - это хорошо, но гораздо лучше бы было, если бы он смог бы нам об этом сообщить. Для этого нам необходимо создать объект-обертку над чатом, куда будут выводиться наши системные сообщения.

MYADDON = LibStub("AceAddon-3.0"):NewAddon("MYADDON")
local Console = LibStub("AceConsole-3.0")
--[[
Загружаем библиотеку по работе с консолью. 
Теперь мы можем использовать переменную Console, чтобы выводить в чат сообщения.
]]--
function MYADDON:OnInitialize()
end
function MYADDON:OnEnable()
Console:Print("MYADDON Loaded");
--[[
При включении аддона в чате будет выведено "MYADDON Loaded" (выведется белым цветом и видно будет только вам)
]]--
end
function MYADDON:OnDisable()
end

5.3. Слеш-команды

Итак, наш аддон умеет запускаться, а также выводить в чат сообщения. Теперь попробуем научить его понимать слеш-команды. Ето самый простой способ взаимодействия с аддоном. К слеш-командам относятся: /sit, /stand, /inviteAnybodyToGuild или какие-либо другие на ваш вкус. При создании слеш-команды для вашего аддона следует иметь в виду, что она должна быть уникальна, то есть не должна совпадать с какой-либо уже существующей. Чем короче команда, тем больше шанс, что такая уже есть, а чем длиннее - тем неудобнее будет ей пользоваться.

MYADDON = LibStub("AceAddon-3.0"):NewAddon("MYADDON")
local Console = LibStub("AceConsole-3.0")
function MYADDON:OnInitialize()
end
function MYADDON:OnEnable()
Console:RegisterChatCommand("inviteAnybodyToGuild", "InviteFunc")
--[[
При загрузке аддона мы говорим, что если игрок напишет в чате "/inviteAnybodyToGuild", 
то будет вызвана наша функция Console:InviteFunc
]]--
Console:Print("MYADDON Loaded");
end
function MYADDON:OnDisable()
end
function Console:InviteFunc(input)
Console:Print("InviteFunc was called with text: " .. input);
--[[
В чат будет выведено "InviteFunc was called with text: ", а также параметр команды.
Например, если ввели "/inviteAnybodyToGuild", то получится "InviteFunc was called with text: ",
а если "/inviteAnybodyToGuild myname", то "InviteFunc was called with text: myname".
".." - это оператор конкатенации строк.
]]--
end

5.4. Обработка событий

Управлять аддоном с помощью слеш-команд можно, но порой хочется, чтобы он сам мог реагировать на постоянно меняющуюся обстановку внутри игры. Для этого существуют события. Событие - это сообщение аддону, что что-то произошло. Например, игрок поменял цель или же перешел в новую локацию, вступил в бой или получил приглашение вступить в гильдию.
Для того, чтобы обработать такое событие, на него следует сперва подписаться и указать функцию-обработчик, которая будет всякий раз вызвана, как аддон получит сообщение о произошедшем событии.

MYADDON = LibStub("AceAddon-3.0"):NewAddon("MYADDON")
local Console = LibStub("AceConsole-3.0")
LibStub("AceEvent-3.0"):Embed(MYADDON)
--[[
Мы загружаем библиотеку по работе с событиями. Однако, вместо заведения отдельной переменной, 
как мы делали с Console, мы говорим, что ею является MYADDON.
Это альтернативный способ добавления функционала из в аддон из WowAce.
]]--
function MYADDON:OnInitialize()
end
function MYADDON:OnEnable()
Console:RegisterChatCommand("inviteAnybodyToGuild", "InviteFunc")
MYADDON:RegisterEvent("ZONE_CHANGED", "ZoneFunc")
--[[
Мы говорим, что если произойдет событие ZONE_CHANGED, возникающее при переходе между локациями, 
то будет вызвана наша функция MYADDON:ZoneFunc
]]--
Console:Print("MYADDON Loaded");
end
function MYADDON:OnDisable()
end
function Console:InviteFunc(input)
Console:Print("InviteFunc was called with text: " .. input);
end
function MYADDON:ZoneFunc()
Console:Print("Zone Changed");
--[[
Выводим сообщение о том, что текущая локация была изменена.
]]--
end

5.5. Графический интерфейс

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

MYADDON = LibStub("AceAddon-3.0"):NewAddon("MYADDON")
local Console = LibStub("AceConsole-3.0")
LibStub("AceEvent-3.0"):Embed(MYADDON)
local AceGUI = LibStub("AceGUI-3.0")
--[[
Мы загружаем библиотеку по работе с интерфейсом.
]]--
function MYADDON:OnInitialize()
end
function MYADDON:OnEnable()
Console:RegisterChatCommand("inviteAnybodyToGuild", "InviteFunc")
MYADDON:RegisterEvent("ZONE_CHANGED", "ZoneFunc")
Console:Print("MYADDON Loaded");
end
function MYADDON:OnDisable()
end
function Console:InviteFunc(input)
--[[
Теперь по слеш-команде будем открывать новое интерфейсное окно
]]--
local frame = AceGUI:Create("Frame") -- мы создаем новое окно
frame:SetTitle("Example Frame") -- устанавливаем ему заголовок
frame:SetStatusText("AceGUI-3.0 Example Container Frame") -- устанавливаем значение строки в панели состояния внизу окна
frame:SetCallback("OnClose", function() frame:Release() end) -- устанавливаем обработчик на закрытие окна 
(освободить все использованные ресурсы)
frame:SetLayout("Flow")
--[[
Устанавливаем порядок заполнения компонентами в окне.
Flow означает, что следующий будет добавляться справа от предыдущего, а когда место закончится, то начнет заполнение с новой строки.
]]--
local editbox = AceGUI:Create("EditBox") -- создаем новое поле для редактирования
editbox:SetLabel("Insert text:") -- устанавливаем ему текст описания
editbox:SetText(input) -- заполняем его текст, в нашем случае - параметр слеш-команды
editbox:SetWidth(200) -- устанавливаем ширину поля
frame:AddChild(editbox) -- добавляем поле на форму
local button = AceGUI:Create("Button") -- создаем новую кнопку
button:SetText("Click Me!") -- устанавливаем ей текст
button:SetWidth(200) -- устанавливаем ширину кнопки
button:SetCallback("OnClick", function() { Console:Print("Pressed"); } end) -- ставим обработчик нажатия на нее, 
в нашем случае печать "Pressed"
frame:AddChild(button) -- добавляем кнопку на форму
frame:Show() -- отображает окно на экране
end
function MYADDON:ZoneFunc()
Console:Print("Zone Changed");
end

5.6. Сохранение информации между запусками

Каждый раз при входе персонажем указывать всевозможные параметры аддона довольно утомительно. Гораздо лучше указать их один раз, а затем использовать сохраненные данные. Поддержкой чего мы сейчас и займемся.
Изменение в MYADDON.toc:

## Interface: 30300
## Title: My Title
## Notes: My Description
## Author: AuthorName
## Version: 0.1
## SavedVariables: MYADDONDB

embeds.xml
Core.lua

MYADDON = LibStub("AceAddon-3.0"):NewAddon("MYADDON")
local Console = LibStub("AceConsole-3.0")
LibStub("AceEvent-3.0"):Embed(MYADDON)
local AceGUI = LibStub("AceGUI-3.0")
--[[
Мы загружаем библиотеку по работе с интерфейсом.
]]--
function MYADDON:OnInitialize()
self.db = LibStub("AceDB-3.0"):New("MYADDONDB")
--[[
Инициализируем хранилище данных
MYADDONDB - название переменной, в которой все будет храниться между запусками
]]--
end
function MYADDON:OnEnable()
Console:RegisterChatCommand("inviteAnybodyToGuild", "InviteFunc")
MYADDON:RegisterEvent("ZONE_CHANGED", "ZoneFunc")
Console:Print("MYADDON Loaded");
if MYADDON.db.char.var1 then
Console:Print("Last time you set text to: " .. MYADDON.db.char.var1);
else
Console:Print("Var1 not set yet");
MYADDON.db.char.var1 = ""
end
--[[
Проверяем, была ли сохранена переменная ранее.
Инициализируем при необходимости.
]]--
end
function MYADDON:OnDisable()
end
function Console:InviteFunc(input)
Console:Print("InviteFunc was called with text: " .. input);
MYADDON.db.char.var1 = input
--[[
Сохраняем значение переменной
]]--
end
function MYADDON:ZoneFunc()
Console:Print("Zone Changed");
end

6. Полезные ссылки

1. Сообщество создателей аддонов (англ) - http://www.wowace.com/
2. Документация по WowAce (англ) - http://www.wowace.com/addons/ace3/
3. Документация API (англ) - http://www.wowwiki.com/World_of_Warcraft_API
4. Документация событий (англ) - http://www.wowwiki.com/Events_(API)