Ace3 for Dummies

Ace3 is an addon framework for World of Warcraft to make writing addons easier. It's however not required for writing addons and it's recommended to understand the basics first before using Ace3.

We'll begin with creating a folder and a .TOC file inside with the same name:

<font color="#DDA0DD">WelcomeHome.toc Core.lua

• 1) Interface:
• 2) Version: 1.0.0
• 3) Title: WelcomeHome
• 4) Notes: Displays a welcome message when you get to your home zone
• 5) Author: YourName

Then create an empty text file called <font color="#DDA0DD">Core.lua in the same directory and start up WoW. After logging in, you should be able to see that your AddOn is being recognized by the game.

Download Ace3 from https://www.wowace.com/projects/ace3/files and unzip it into a subfolder called

There are lots of Ace3 libraries for you to use, but for this tutorial we only need to keep the following libs and you can delete the rest:

We also need to tell WoW to load the Ace3 files when it loads your addon.

<font color="#4ec9b0">## SavedVariables: WelcomeHomeDB <font color="#ecbc2a">Libs\LibStub\LibStub.lua Libs\CallbackHandler-1.0\CallbackHandler-1.0.xml Libs\AceAddon-3.0\AceAddon-3.0.xml Libs\AceEvent-3.0\AceEvent-3.0.xml Libs\AceDB-3.0\AceDB-3.0.xml Libs\AceDBOptions-3.0\AceDBOptions-3.0.xml Libs\AceConsole-3.0\AceConsole-3.0.xml Libs\AceGUI-3.0\AceGUI-3.0.xml Libs\AceConfig-3.0\AceConfig-3.0.xml Core.lua

• 1) Interface:
• 2) Version: 1.0.0
• 3) Title: WelcomeHome
• 4) Notes: Displays a welcome message when you get to your home zone
• 5) Author: YourName
• 1) OptionalDeps: Ace3

• 📝 Note 1: depends on and but otherwise the load order does not matter. Just copy it from the Ace3 TOC if you want to be sure.

• 📝 Note 2:, and are not included in this tutorial.

We've included the SavedVariables TOC field which we will need eventually. The OptionalDeps field is in case a user of your addon wants to use Ace3 as a standalone addon instead of the embedded libraries in your Libs folder.

Open the <font color="#DDA0DD">Core.lua file and add the following:

This is the basic structure of an Ace3 addon. The first line creates an instance of the AceAddon class using the NewAddon method.

Since we will also be printing to the chat window and accepting slash commands, we include the mixin which e.g. includes the Print method.

Following that are three method overrides:, , and respectively. The first is executed only once when the UI loads and the next two are executed when the addon is enabled and disabled. You can and Ace addons at will.

Open or /reload the game client, you should be able to see your chat message! Before we go any further, go back over to your code and remove the print message. It is generally considered bad form for your addon to toss a bunch of text into the chat window just because it has loaded. Too many addons do this already. You can also remove the method since we won't be using it.

This addon will give a welcome message to the player when they arrive in their home zone. How will we know they are in their home zone? Simple, we will respond to the game event which the game fires when the player enters a new (sub)zone.

Before we can register an event, we need to include the AceEvent mixin into our addon. WelcomeHome = LibStub("AceAddon-3.0"):NewAddon("WelcomeHome", "AceConsole-3.0", <font color="#ecbc2a">"AceEvent-3.0" )

Once we've done that, we can use RegisterEvent to respond to the ZONE_CHANGED event.

We also need to add the handler for that event. There we can compare our hearthstone location from with.

You might be wondering if we should call UnregisterEvent from our OnDisable override, but we don't have to do that because already does it for us.

Now have your character leave the area he/she is presently in. You should see your message in the chat when you change zone and if you're in the same subzone as your hearthstone location it should give you a friendly message.

Now let's add support for slash commands with RegisterChatCommand.

But why stop at chat commands? All cool addons have a Graphical User Interface these days so WelcomeHome shouldn't be any different!

First we define our options table. And the getters/setters for our message. It knows where to look since is defined. 📝 Note: the info table is an advanced topic, so you can ignore that for now.

Now to include our addon options to the "AddOns" tab, all we need to do is call RegisterOptionsTable and AddToBlizOptions. The latter method returns a frame we need for opening our options panel, so we save it in

We want the addon to open a GUI for our options if there's no other input and otherwise we'll handle it like a normal chat command.

Now let's add display the message somewhere that is a bit more prominent, for example the with. We'll also add an option for it.

local options = { name = "WelcomeHome", handler = WelcomeHome, type = "group", args = { msg = { type = "input", name = "Message", desc = "The message to be displayed when you get home.", usage = "<Your message>", get = "GetMessage", set = "SetMessage", }, <font color="#ecbc2a">showOnScreen = { type = "toggle", name = "Show on Screen", desc = "Toggles the display of the message on the screen.", get = "IsShowOnScreen", set = "ToggleShowOnScreen" }, }, }

function WelcomeHome:OnInitialize LibStub("AceConfig-3.0"):RegisterOptionsTable("WelcomeHome", options) self.optionsFrame = LibStub("AceConfigDialog-3.0"):AddToBlizOptions("WelcomeHome", "WelcomeHome") self:RegisterChatCommand("wh", "SlashCommand") self:RegisterChatCommand("welcomehome", "SlashCommand") -- default values self.message = "Welcome Home!" <font color="#ecbc2a">self.showOnScreen = true end

function WelcomeHome:ZONE_CHANGED if GetBindLocation == GetSubZoneText then <font color="#ecbc2a">if self.showOnScreen then UIErrorsFrame:AddMessage(self.message, 1, 1, 1) else self:Print(self.message) end end end

You may have noticed is that your settings aren't persisted between sessions. When you logout and back in, you will have the default settings again. WoW provides a way to save your settings with SavedVariables, but there is an Ace way to do it with AceDB:New.

function WelcomeHome:OnInitialize <font color="#ecbc2a">self.db = LibStub("AceDB-3.0"):New("WelcomeHomeDB", defaults, true) LibStub("AceConfig-3.0"):RegisterOptionsTable("WelcomeHome", options) self.optionsFrame = LibStub("AceConfigDialog-3.0"):AddToBlizOptions("WelcomeHome", "WelcomeHome") self:RegisterChatCommand("wh", "SlashCommand") self:RegisterChatCommand("welcomehome", "SlashCommand") end

• refers to our SavedVariables entry in the TOC.
• We pass for the third argument of so all characters will share the same "Default" profile. Otherwise if you don't specify anything, all characters will get their own specific profile. See the AceDB docs for more information on data types like.

After that we need to update our old variables to the new ones, e.g. to function WelcomeHome:ZONE_CHANGED if GetBindLocation == GetSubZoneText then if self.db.profile.showOnScreen then UIErrorsFrame:AddMessage(self.<font color="#ecbc2a">db.profile .message, 1, 1, 1) else self:Print(self.<font color="#ecbc2a">db.profile .message) end end end

function WelcomeHome:GetMessage(info) return self.<font color="#ecbc2a">db.profile .message end function WelcomeHome:SetMessage(info, value) self.<font color="#ecbc2a">db.profile .message = value end function WelcomeHome:IsShowOnScreen(info) return self.<font color="#ecbc2a">db.profile .showOnScreen end function WelcomeHome:ToggleShowOnScreen(info, value) self.<font color="#ecbc2a">db.profile .showOnScreen = value end

Reload your UI and nothing should change. Except now if you change any of the settings, they will be persisted across restarts.

The profiles tab lets users change and reset profiles. function WelcomeHome:OnInitialize self.db = LibStub("AceDB-3.0"):New("TestDB", defaults, true) LibStub("AceConfig-3.0"):RegisterOptionsTable("WelcomeHome_options", options) self.optionsFrame = LibStub("AceConfigDialog-3.0"):AddToBlizOptions("WelcomeHome_options", "WelcomeHome") <font color="#ecbc2a">local profiles = LibStub("AceDBOptions-3.0"):GetOptionsTable(self.db) LibStub("AceConfig-3.0"):RegisterOptionsTable("WelcomeHome_Profiles", profiles) LibStub("AceConfigDialog-3.0"):AddToBlizOptions("WelcomeHome_Profiles", "Profiles", "WelcomeHome")

You have started from nothing and created an addon that uses chat commands, responds to events and provides feedback to the user in a couple of different ways. Here is the final version in case you want to cheat and go right to the end.

<font color="#DDA0DD">WelcomeHome.toc Libs\LibStub\LibStub.lua Libs\CallbackHandler-1.0\CallbackHandler-1.0.xml Libs\AceAddon-3.0\AceAddon-3.0.xml Libs\AceEvent-3.0\AceEvent-3.0.xml Libs\AceDB-3.0\AceDB-3.0.xml Libs\AceDBOptions-3.0\AceDBOptions-3.0.xml Libs\AceConsole-3.0\AceConsole-3.0.xml Libs\AceGUI-3.0\AceGUI-3.0.xml Libs\AceConfig-3.0\AceConfig-3.0.xml Core.lua

• 1) Interface:
• 2) Version: 1.0.0
• 3) Title: WelcomeHome
• 4) Notes: Displays a welcome message when you get to your home zone
• 5) Author: YourName
• 6) SavedVariables: WelcomeHomeDB
• 7) OptionalDeps: Ace3

<font color="#DDA0DD">Core.lua

• Follow-up: Using the BigWigs Packager with GitHub Actions

See also

• WelcomeHome: Your first Ace3 Addon - Original tutorial
• https://github.com/ketho-wow/HelloAce - Example Ace3 template

References