Differences from Ace2 to Ace3
From WowAce Wiki
Ace3 is meant to provide all essential functions provided by Ace2, and do so in a a less interdependent manner. As such nearly all Ace3 libraries can be used on their own.
In the below sections, we assume a fair understanding of how Ace2 currently functions and what it provides.
Contents |
AceLibrary
- AceLibrary is deprecated entirely and replaced by LibStub
LibStub was developed by the Ace3 designers to be minimal version handling library that is meant to be usable by ANY library without unnecessary costs.
LibStub is currently 3KB in size and considered feature complete.
What you as a developer need to know is:
- LibStub will not chase and attempt load LoD libraries.
- For libraries that are always used by your addon, a regular Optional Dependency declaration in the .toc file is enough. It's there, and it works as intended.
- For standalone libraries that you may or may not want to load runtime, a simple LoadAddon("SomeLibrary-1.0") call is all that is required before attempting to access the library via LibStub.
- LibStub will not attempt to enable disabled libraries.
- Mixins work a little bit differently in the LibStub model. The library itself is expected to track its mixin locations and upgrade them. This is roughly 5 lines of Lua per library. See the examples section of LibStub on WoWWiki.
AceAddon and AceModuleCore
- AceModuleCore is deprecated. AceAddon-3.0 is constructed in such a way that addons and modules are the same thing, and they can be nested in multiple levels.
- AceAddon no longer does about dialogs.
- AceAddon no longer does donation dialogs.
- AceAddon no longer attempts to parse all its toc metadata fields and store in the addon object. If an addon wants to access these (they are very few), they can simply use the Blizzard API: GetAddonMetaData("AddonName", "X-TocFieldName")
It is entirely possible that authors want about & donation dialog support, but we feel that this belongs in a standalone library, not in AceAddon proper.
AceEvent
- AceEvent is split up into three main libraries and one embedded support library:
- AceTimer - single-shot and repetitive timers. A new bucketed approach to timers is used which outperforms the previous implementation by several times when the number of timers in the system grows.
- AceEvent - handle blizzard event registration and inter-process communication. Events and "messages" have been split to two APIs -- it is no longer possible to fire fake blizzard events.
- AceBucket - handle bucketing of events. Depends on AceEvent.
In addition to this, there is a "CallbackHandler" library, which AceEvent embeds. The reason for the split is that we do not want libraries to do signalling via AceEvent, since that would then requires addons to know about AceEvent. AceEvent messages are better used for inter-addon communication where the source is not necessarily known. CallbackHandler contains shared functionality to register and fire callbacks, and is simply mixed into the using library. Addons need never know that it exists.
AceDB
AceDB has been rewritten and redesigned from scratch, being more flexible and independent then before.
- New: Support for registering arbitrary databases on any table.
- Changed: AceDB is no longer a mixin, but a pure standalone library. Therefore all functions for interfacing with the Database are now exported onto the DB Object, and not the addon object.
- Changed: Callbacks need to be explicitly registered using the API provided by the CallbackHandler-1.0 mini-library.
- Changed: Default-tables have to contain subkeys for specific profiles now.
Example in the old Ace2 style:
local defaults = {
profile = {
entry = "value",
subkey = {
subentry = "value",
}
}
}
function addon:OnInitialize()
self.db = AceDB:New("MyAddonDB", defaults)
self.db:SetProfile("Ace3TestProfile")
end
Support for the old "magic"-defaults ( * and ** keys ) is still available.
Check the detailed API Documentations ( yet to come ) for further information on the changes.
AceConsole
- AceConsole, which handles slash command registration, provides string utilities, and console output functions.
- AceConfig, which embeds the following libraries:
- AceConfigCmd - console config access
- AceConfigDialog - dialog-driven config
- AceConfigDropdown - dropdown config access
- AceConfigRegistry - the glue between addons and config handlers
AceConfig is split in this manner to enable authors to choose which config interfaces they want. We believe that most want all of them however, and therefore provide the "AceConfig" package as an easy way of getting them all in without pulling several libraries.
AceConfigRegistry is provided as a very small separate lib so that e.g. standalone modules that expect their configurations to be handled by another addon can register their configurations without having to include AceConfig in its entirety.
AceGUI
AceGUI no longer attempts to be the end-all of UI design on its own - that purpose is no longer meaningful as of 1.10 when Blizzard gave us CreateFrame().
It is now more geared towards configuration dialogs, but its widgets can certainly be used outside of dialog-looking frames. Base AceGUI will only contain widgets relevant for basic configuration handing, but it is extensible with custom widget types supplied by the addon or extra libraries for those that need more than the base.
AceConfigDialog will use AceGUI to display the contents of an AceOptions table as a dialog.
AceLocale
AceLocale has been optimized greatly. Instead of registering every locale and scrapping unneeded ones, only ones actually used are processed.
This is done by emulating LibStub - if we are interested in a language, we return a table to be filled in. If not, nil is returned, and you would have to jump through a lot of stupid hoops to manage to do unnecessary processing.
Dynamic locales, reverse translation tables, etc are not supported, and neither will they be. This belongs in separate libraries.
! We would also like to take this opportunity to point out that locale files should be placed in a separate subfolder, e.g. "MyAddon/Locales". When user-tweakable SVN permissions arrive, this means that translators can easily be given access to the translation files only, which should avoid some nasty situations we've seen in the past. You probably want to have a "MyAddon/Locales/Locales.xml" file that pulls the individual lua files in -- translators wouldn't be able to edit your .toc file any more after a permission change.
AceComm
We feel that AceComm-2 attempts to do too much, at too high a cost in stability (some integers still can't be transmitted after one year) and CPU load, with too little gain in decreased network load from integer packing and memoizations and the like.
- AceComm-3.0 on its own only does splitting of too-large messages and bandwidth management (via ChatThrottleLib). If a message is small enough to not be split, it looks no different from a standard message.
- AceComm-3.0 only does transmission over designated addon channels (i.e. the SendAddonMessage API), not custom chat channels. We realize that some may want communication over other channels, but this can be done in a separate library or directly by the addon. The vast majority of addons only want the designated addon channels.
- AceComm-3.0 empathetically does not do anything on its own, something which AceComm-2.0 / RockComm does (transmit loot events, talent builds, whatnot..)
For serializing complex data types, a separate library has been developed: AceSerializer-3.0. It will take any number of any transmittable data type and serialize to a string. It is not tied to the communications library and can be used for any purpose (can we say "cut&paste configurations across chat/mail/forums", anyone?). It is of course also usable for addons that want to do communication over nonstandard channels.
More to come
- AceHook will remain, with some changes to make "safe" hooks (ones that do not modify the arguments or returns) easier and risk-free. The design is believed to be complete and code is in the works.
- AceTab will remain. (For those of you that do not know what it does, try hitting tab more often in slash commands. It rocks!) There are no major changes from v2.
Is there something you want to know more about in comparing Ace2 to Ace3? Please comment in the Ace3 forum thread or on the wiki discussion page!
