AceAddon-3.0

AceAddon-3.0 provides a template for creating addon objects. It gives you a set of lifecycle callbacks (OnInitialize, OnEnable, OnDisable) that simplify the loading process of your addon; see Callbacks.

Usage

Creating an addon object

Once LibStub and AceAddon-3.0 are referenced, your main Lua file creates an addon instance:

MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon")

You can mix in other libraries by listing them; for example, adding AceConsole for chat/slash-command abilities:

MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon", "AceConsole-3.0")

Mixins vs. on-demand libraries

The extra arguments to :NewAddon (and :NewModule) are libraries to mix in (embed). Embedding copies that library's methods onto your addon object, so you call them on self:

local MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon", "AceEvent-3.0", "AceConsole-3.0")

function MyAddon:OnEnable()
    self:RegisterEvent("PLAYER_REGEN_DISABLED")  -- from AceEvent, now a method on MyAddon
    self:Print("Enabled!")                        -- from AceConsole
end

The library uses your addon as its self, so it tracks registrations per addon, and AceAddon automatically cleans them up when your addon is disabled (events unregistered, hooks removed, timers cancelled).

Contrast this with grabbing a library on demand via LibStub, which returns the single shared library object:

local AceEvent = LibStub("AceEvent-3.0")
-- not embedded: you must supply your own 'self' and manage cleanup yourself
AceEvent.RegisterEvent(MyAddon, "PLAYER_REGEN_DISABLED")

The :Embed method

Every embeddable library has an :Embed(target) method that copies its methods onto the table you pass, so you can then call them on that table.

You normally never call it yourself. Listing a library in :NewAddon or :NewModule calls :Embed on your addon for you, and the copying is identical either way. The reason to let AceAddon do it is **cleanup **: AceAddon knows when your addon is enabled and disabled, so it can tell each embedded library to tear down its registrations (events, hooks, timers) when the addon is disabled. A table you embed into by hand is not an addon AceAddon manages, so nothing cleans it up.

In short: use :NewAddon/:NewModule to embed; call :Embed directly only to add a library's methods to an object that isn't an Ace addon.

Use mixins for the embeddable libraries you call throughout your addon (AceConsole, AceEvent, AceBucket, AceHook, AceComm, AceTimer, AceSerializer): it's less typing and you get automatic cleanup. Libraries that produce their own objects or tables (AceDB, AceConfig/AceConfigDialog, AceGUI, AceLocale, AceDBOptions) are not embeddable; fetch them with LibStub(...) when you need them.

TIP

For modules, :SetDefaultModuleLibraries lets you embed the same set of libraries into every module the addon creates, without repeating them on each :NewModule call.

Standard methods

AceAddon calls up to three lifecycle callbacks on your addon object: OnInitialize, OnEnable and OnDisable. OnInitialize runs once at load; OnEnable/OnDisable may run multiple times without a full UI reload. The Example below uses all three.

Example

-- A small (but complete) addon, that doesn't do anything,
-- but shows usage of the callbacks.
local MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon")

function MyAddon:OnInitialize()
    -- do init tasks here, like loading the Saved Variables,
    -- or setting up slash commands.
end

function MyAddon:OnEnable()
    -- Do more initialization here, that really enables the use of your addon.
    -- Register Events, Hook functions, Create Frames, Get information from
    -- the game that wasn't available in OnInitialize
end

function MyAddon:OnDisable()
    -- Unhook, Unregister Events, Hide frames that you created.
    -- You would probably only use an OnDisable if you want to
    -- build a "standby" mode, or be able to toggle modules on/off.
end

API Reference

Disable

method#

MyAddon:Disable()

Disables the addon if possible. Returns true or false depending on whether it succeeded. This internally calls AceAddon:DisableAddon(), thus dispatching a OnDisable callback and disabling all modules of the addon. :Disable() also sets the internal enabledState variable to false.

Returns

Type	Description
boolean	true or false depending on whether the addon was successfully disabled.

Example

-- Disable MyAddon
MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
MyAddon:Disable()

DisableModule

method#

MyAddon:DisableModule(name)

Disables the module if possible. Returns true or false depending on whether it succeeded. Short-hand function that retrieves the module via :GetModule and calls :Disable on the module object.

Parameters

Parameter	Type	Default	Description
name	string		Unique name of the module to disable.

Returns

Type	Description
boolean	true or false depending on whether the module was successfully disabled.

Example

-- Disable MyModule using :GetModule
MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
MyModule = MyAddon:GetModule("MyModule")
MyModule:Disable()

-- Disable MyModule using the short-hand
MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
MyAddon:DisableModule("MyModule")

Enable

method#

MyAddon:Enable()

Enables the addon if possible. Returns true or false depending on whether it succeeded. This internally calls AceAddon:EnableAddon(), thus dispatching a OnEnable callback and enabling all modules of the addon (unless explicitly disabled). :Enable() also sets the internal enabledState variable to true. If the addon is still queued for initialization, enabling is deferred until after the init process completes.

Returns

Type	Description
boolean	true or false depending on whether the addon was successfully enabled (nil if enabling was deferred because the addon is still queued for initialization).

Example

-- Enable MyModule
MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
MyModule = MyAddon:GetModule("MyModule")
MyModule:Enable()

EnableModule

method#

MyAddon:EnableModule(name)

Enables the module if possible. Returns true or false depending on whether it succeeded. Short-hand function that retrieves the module via :GetModule and calls :Enable on the module object.

Parameters

Parameter	Type	Default	Description
name	string		Unique name of the module to enable.

Returns

Type	Description
boolean	true or false depending on whether the module was successfully enabled.

Example

-- Enable MyModule using :GetModule
MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
MyModule = MyAddon:GetModule("MyModule")
MyModule:Enable()

-- Enable MyModule using the short-hand
MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
MyAddon:EnableModule("MyModule")

GetModule

method#

MyAddon:GetModule(name, silent?)

Return the specified module from an addon object. Throws an error if the addon object cannot be found (except if silent is set)

Parameters

Parameter	Type	Default	Description
name	string		Unique name of the module.
silent (optional)	boolean		If true, the module is optional, silently return nil if its not found.

Returns

Type	Description
table	The module object, or nil if it could not be found and silent is set.

Example

-- Get the Addon
MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
-- Get the Module
MyModule = MyAddon:GetModule("MyModule")

GetName

method#

MyAddon:GetName()

Returns the real name of the addon or module, without any prefix. For modules this returns the module's own name rather than the internal parent_module composite name.

Returns

Type	Description
string	The name of the addon or module.

IsEnabled

method#

MyAddon:IsEnabled()

Query the enabledState of an addon.

Returns

Type	Description
boolean	The current enabledState (true if enabled, false if disabled).

Example

if MyAddon:IsEnabled() then
    MyAddon:Disable()
end

IterateModules

method#

MyAddon:IterateModules()

Return an iterator of all modules associated to the addon.

Returns

Type	Description
function	A pairs iterator over the addon's modules (yielding name, module).

Example

-- Enable all modules
for name, module in MyAddon:IterateModules() do
    module:Enable()
end

IterateEmbeds

method#

MyAddon:IterateEmbeds()

Returns an iterator of all libraries embedded in the addon.

Returns

Type	Description
function	A pairs iterator over the list of library names embedded in the addon.

Example

for _, lib in MyAddon:IterateEmbeds() do
    print("Embedded: " .. lib)
end

NewModule

method#

MyAddon:NewModule(name, prototype|lib?, ...)

Create a new module for the addon. The new module can have its own embedded libraries and/or use a module prototype to be mixed into the module. A module has the same functionality as a real addon, it can have modules of its own, and has the same API as an addon object.

Parameters

Parameter	Type	Default	Description
name	string		Unique name of the module.
`prototype	lib` (optional)	table | string
...	string		Additional libraries to embed into the module.

Returns

Type	Description
table	The newly created module object.

Example

-- Create a module with some embeded libraries
MyModule = MyAddon:NewModule("MyModule", "AceEvent-3.0", "AceHook-3.0")

-- Create a module with a prototype
local prototype = { OnEnable = function(self) print("OnEnable called!") end }
MyModule = MyAddon:NewModule("MyModule", prototype, "AceEvent-3.0", "AceHook-3.0")

SetDefaultModuleLibraries

method#

MyAddon:SetDefaultModuleLibraries(...)

Set the default libraries to be mixed into all modules created by this object. Note that you can only change the default module libraries before any module is created.

Parameters

Parameter	Type	Default	Description
...	string		Names of libraries to embed into every module created by this object.

Example

-- Create the addon object
MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon")
-- Configure default libraries for modules (all modules need AceEvent-3.0)
MyAddon:SetDefaultModuleLibraries("AceEvent-3.0")
-- Create a module
MyModule = MyAddon:NewModule("MyModule")

SetDefaultModulePrototype

method#

MyAddon:SetDefaultModulePrototype(prototype)

Set the default prototype to use for new modules on creation. Note that you can only change the default prototype before any module is created.

Parameters

Parameter	Type	Default	Description
prototype	table		Default prototype for the new modules.

Example

-- Define a prototype
local prototype = { OnEnable = function(self) print("OnEnable called!") end }
-- Set the default prototype
MyAddon:SetDefaultModulePrototype(prototype)
-- Create a module and explicitly Enable it
MyModule = MyAddon:NewModule("MyModule")
MyModule:Enable()
-- should print "OnEnable called!" now

See also: [NewModule]

SetDefaultModuleState

method#

MyAddon:SetDefaultModuleState(state)

Set the default state in which new modules are being created. Note that you can only change the default state before any module is created.

Parameters

Parameter	Type	Default	Description
state	boolean		Default state for new modules, true for enabled, false for disabled.

Example

-- Create the addon object
MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon")
-- Set the default state to "disabled"
MyAddon:SetDefaultModuleState(false)
-- Create a module and explicitly enable it
MyModule = MyAddon:NewModule("MyModule")
MyModule:Enable()

SetEnabledState

method#

MyAddon:SetEnabledState(state)

Set the state of an addon or module. This sets the internal enabledState and should only be called before any enabling actually happens, e.g. in/before OnInitialize.

Parameters

Parameter	Type	Default	Description
state	boolean		The state of an addon or module (enabled=true, disabled=false).

Example

function MyAddon:OnInitialize()
    -- start disabled until the user opts in
    self:SetEnabledState(false)
end

GetAddon

method#

AceAddon:GetAddon(name, silent?)

Get the addon object by its name from the internal AceAddon registry. Throws an error if the addon object cannot be found (except if silent is set).

Parameters

Parameter	Type	Default	Description
name	string		Unique name of the addon object.
silent (optional)	boolean		If true, the addon is optional, silently return nil if its not found.

Returns

Type	Description
table	The addon object, or nil if it could not be found and silent is set.

IterateAddonStatus

method#

AceAddon:IterateAddonStatus()

Get an iterator over the internal status registry.

Returns

Type	Description
function	A pairs iterator over the status registry (yielding name, status).

Example

-- Print a list of all enabled addons
for name, status in AceAddon:IterateAddonStatus() do
    if status then
        print("EnabledAddon: " .. name)
    end
end

IterateAddons

method#

AceAddon:IterateAddons()

Get an iterator over all registered addons.

Returns

Type	Description
function	A pairs iterator over all registered addons (yielding name, addon).

Example

-- Print a list of all installed AceAddon's
for name, addon in AceAddon:IterateAddons() do
    print("Addon: " .. name)
end

NewAddon

method#

AceAddon:NewAddon(object?, name, ...)

Create a new AceAddon-3.0 addon. Any libraries you specified will be embedded, and the addon will be scheduled for its OnInitialize and OnEnable callbacks. The final addon object, with all libraries embedded, will be returned.

object is not a true positional argument: the first argument is used as the base object only if it is a table, otherwise it is taken as the name and a fresh object is created. So NewAddon("MyAddon", ...) and NewAddon(myTable, "MyAddon", ...) are both valid.

Parameters

Parameter	Type	Default	Description
object (optional)	table		Table to use as a base for the addon.
name	string		Name of the addon object to create.
...	string		Names of libraries to embed into the addon.

Returns

Type	Description
table	The new addon object, with all specified libraries embedded.

Example

-- Create a simple addon object
MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon", "AceEvent-3.0")

-- Create a Addon object based on the table of a frame
local MyFrame = CreateFrame("Frame")
MyAddon = LibStub("AceAddon-3.0"):NewAddon(MyFrame, "MyAddon", "AceEvent-3.0")

Callbacks

AceAddon calls these lifecycle methods on your addon (and module) objects if you define them. They aren't fired through CallbackHandler; you simply declare them as methods on the object returned by :NewAddon/:NewModule.

OnInitialize

callback#

MyAddon:OnInitialize()

Called once, directly after the addon is fully loaded, after its SavedVariables are available. The place to create your database, register options, set up slash commands, and do other one-time setup. Runs exactly once per session.

OnEnable

callback#

MyAddon:OnEnable()

Called when the addon is enabled: the first time during the PLAYER_LOGIN event, when most game data is available. Register events, apply hooks, create frames and read game state here. May run more than once if the addon is toggled off and on (it is not tied to a UI reload).

OnDisable

callback#

MyAddon:OnDisable()

Called when the addon is disabled. Undo what OnEnable did: unregister events, remove hooks, hide frames. Only happens when the addon (or module) is explicitly disabled, so most addons that are never disabled won't need it.

OnModuleCreated

callback#

MyAddon:OnModuleCreated(module)

Called on the parent addon each time it creates a module (via :NewModule), if the addon defines it. Handy for applying shared setup to every module as it is created.

Parameters

Parameter	Type	Default	Description
module	table		The newly created module object.