 |
The API is no longer being updated here until further notice. |
The TOC format for files defines information about each addon installed, as well as specify which .xml and/or .lua files need to be loaded. It is currently required for an addon to be recognized, show up in the addons list and be loaded. The TOC filename must match the folder name in order for it to be recognized by WoW; however, any other files can be named whatever you want as long as they have the proper extension and are listed in the TOC or in an XML file inside <Script> or <Include> tags.
WoW reads up to the first 1024 characters of each line only. Additional characters are ignored and do not cause an error.
WoW does not ever reread the TOC after it is initially read. If you change anything in the TOC, such as saved variables, you must restart WoW for those changes to take effect.
Where
World of Warcraft\Interface\AddOns\MyAddon\MyAddon.toc OR c:\users\games\World of Warcraft\Interface\AddOns\MyAddon\MyAddon.toc
Client Recognized Tags
Each tag is preceeded by ## , some postfixed with a localization label. Each occupies one line.
Title and Notes can be localized for other languages. For a complete list of localization labels, see API GetLocale.
Interface
The interface number is a way of telling WoW which version of the client it was made for. If there is a version mismatch, the AddOn is disabled by default. However, if the user explicitly turns off version checking ("Load out of date addons") the AddOn will continue to function regardless of what the interface version number in the .TOC file says. To get what # to put read HOWTO: Get Current Interface Number.
## Interface: 30100
Notes: If the Interface number is too old, you must change it in the .TOC file. Ticking "Load out of date addons" won't force it to load. This edge case will be apparent if the Addon on the Addon frame on the character select screen says "Incompatible" next to it.
Title
This text is what is displayed in the AddOns list located during user selection. It also appears when you mouseover the name of the AddOn in the WoW Addons list. Localized versions can be included by appending a hyphen followed by the localization label. The appropriate label will be shown to the user.
## Title: My Addon ## Title-deDE: Titel ## Title-frFR: Titre
Title also supports the addition of color, similar to the way item links are colored internally. This will display "-Ace2-" in a foam green color.
## Title: ag_UnitFrames |cff7fff7f -Ace2-|r
Notes
The message that appears under the AddOn name when you mouseover the name of the AddOn in the WoW AddOns list. Localized versions can be included by appending a hyphen followed by the localization label. The appropriate label will be shown to the user.
## Notes: This is my first AddOn. ## Notes-deDE: Informationen ## Notes-frFR: Texte
Notes: Like Title (above), Notes may also contain color tags.
RequiredDeps
This metatag is to force the WoW client to only load this AddOn if a functional dependency exists on the system. Some AddOns make use of 3rd party libraries and AddOns in order to function properly. If any of the required dependencies are missing, the AddOn will fail to function. The names used should be the directory names of the AddOns. The list is comma seperated.
## Dependencies: someAddOn, someOtherAddOn
Alternatively you could also use:
## RequiredDeps: someAddOn, someOtherAddOn
Note: Dependencies, RequiredDeps, and Dependancies [sic] all give the same result.
OptionalDeps
Optional dependencies are external libraries or AddOns which can be used by the AddOn to use and implement their functionality if they exist. If the optional dependencies are not found on the system, the AddOn will continue to function, however, the AddOn using Optional dependencies must be written to work without these dependencies in order for the AddOn to function without them.
## OptionalDeps: someAddOn, someOtherAddOn
LoadOnDemand
As of patch 1.7, AddOns can be loaded on demand rather than always loaded when the user first logs in. If this is enabled, this addon must be loaded by another addon at some later point. This is useful in saving memory by avoiding loading special-purpose addons.
## LoadOnDemand: 1 ## LoadOnDemand: 0
LoadWith
New since patch 1.9. Together with LoadOnDemand, this gets your AddOn loaded when one of these AddOns (which would usually be Blizzard UI modules like Blizzard_AuctionUI) is loaded.
## LoadWith: someAddOn, someOtherAddOn
LoadManagers
Added in patch 2.1. If one of the addons listed in this directive is present, your addon will be treated as LoadOnDemand (with the assumption that the other addon will take responsibility for loading yours when needed). If no addons listed here are present, your addon will load normally. For a useful application of this, see AddonLoader.
## LoadManagers: someAddOn, someOtherAddOn
SavedVariables
Used since interface version 2150, Saved Variables are now the current way of storing data in between sessions. These variables are loaded when the client is started, or when the UI is reloaded. The SavedVariables metatag now replaces the function RegisterForSave which is now no longer available to addon authors (it's protected). Note that saved variables are not completely loaded during the OnLoad event and thus must be assumed to contain nil values until the event ADDON_LOADED has been invoked with arg1 set to the name of your Addon's folder.
The value for the tag is a comma-seperated list of variables.
The file that stores SavedVariables is
/WTF/Account/<account name>/SavedVariables/<addon name>.lua
## SavedVariables: someVariable, someOtherVariable
This is more powerful than registering your variables for save in the script, since this will be honored even if your AddOn is disabled by the UI, or because of an error or version mismatch.
SavedVariablesPerCharacter
This tag behaves exactly like SavedVariables except that the variables are saved on a Per-Character basis. This tag only used to use character names to differentiate between characters, but now uses both the realm name and the character name.
The file that stores SavedVariables is
/WTF/Account/<account name>/<realm name>/<character name>/SavedVariables/<addon name>.lua
## SavedVariablesPerCharacter: somePercharVariable
- Note: SavedVariablesPerCharacter are not available to any other character. If you need them to be, then use SavedVariables instead.
DefaultState
Determines whether or not this addon is enabled by default when installed. If it is set to disabled, the user must explicitly turn it on in the AddOns interface located during user selection. If this tag is not specified the default is enabled.
## DefaultState: enabled ## DefaultState: disabled
The enabled/disabled state of all the installed addons will be written to WTF\Account\{youraccount}\AddOns.txt, and this file overrides the old DisabledAddOns.txt file, which will still be loaded for backwards compatiblity.
Secure
This header field was added to the Blizzard_ AddOns that are part of the default UI in 1.11. It's exact purpose is unknown, but one possibility is that it tells the client whether it should look for a signature for the AddOn or not.
## Secure: 1
Non-Standard Tags
It is possible to add more information using the ## directive, and some 3rd party programs even make use of some information provided. Below are some commonly used in addons.
AddOn Metadata Tags
These fields, along with Title and Notes can be retreived using GetAddOnMetadata.
Author
The name, possibly the e-mail address, of the Author(s).
## Author: MyName
Version
The version of the AddOn. Can be any string, but since tools for automatic updating parse numbers, it is best if it at least begins with a numeric version.
## Version: 1.0
X-
Any field that starts with 'X-'
## X-email: Author@Domain.com ## X-Foo: I love pancakes ## X-Foo-esES: Te quiero, mi esposa
Commonly Recognized X- Tags
These tags have been seen in multiple addons and are not specific to any specific library but may be used in-game and/or by TOC parsers.
X-Revision
Sequential non-decimal revision number
OR SVN revision keyword stamp
## X-Revision: 4025 ## X-Revision: $Rev$
X-Date
Release date of the AddOn
OR Release/creation date of the AddOn version
OR SVN date keyword stamp
## X-Date: 2006-06-01 ## X-Date: $Date$
X-Email
Email of the AddOn's author.
Known permutations: eMail, X-eMail
## X-Email: admin@cosmosui.org
X-Website
Website where more information about the AddOn can be found.
Known permutations: URL
## X-Website: http://www.cosmosui.org/addons.php?info=!ImprovedErrorFrame
X-Feedback
Website where feedback about the addon can be given or found (e.g. forum, bug tracker, comments).
## X-Feedback: http://www.cosmosui.org/forums/
X-Localizations
Locale codes representing the dialects this AddOn has been translated into.
## X-Localizations: enUS, deDE, frFR
X-CompatibleLocales
Locale codes representing the WoW clients that this AddOn is known to work on, regardless of localized readability. (e.g a function library may work on any client but may not have any readable content and therefore no localizations )
## X-CompatibleLocales: enUS, enGB, deDE, frFR, koKR, zhCN, zhTW, esES
X-Embeds
A List of the AddOn libraries embedded within this AddOn, usually within a "Libs" sub-folder.
## X-Embeds: SeaString, ChatThrottleLib
X-Category
Category of the AddOn.
## X-Category: Raid
The following tables have been proposed as a suggestion for common category names and their localized equivalent. The TOC X-Category key should be capitalized for readability in absence of the conversion table.
local CATEGORIES = {
["action bars"] = "Action Bars",
["auction"] = "Auction",
["audio"] = "Audio",
["battlegrounds/pvp"] = "Battlegrounds/PvP",
["buffs"] = "Buffs",
["chat/communication"] = "Chat/Communication",
["social"] = "Social Interaction",
["druid"] = "Druid",
["hunter"] = "Hunter",
["mage"] = "Mage",
["paladin"] = "Paladin",
["priest"] = "Priest",
["rogue"] = "Rogue",
["shaman"] = "Shaman",
["warlock"] = "Warlock",
["warrior"] = "Warrior",
["healer"] = "Healer",
["tank"] = "Tank",
["caster"] = "Caster",
["combat"] = "Combat",
["compilations"] = "Compilations",
["data export"] = "Data Export",
["development tools"] = "Development Tools",
["debug"] = "Debugging/Errors",
["guild"] = "Guild",
["frame modification"] = "Frame Modification",
["tooltips"] = "Tooltips",
["quests"] = "Quests",
["interface enhancements"] = "Interface Enhancements",
["inventory"] = "Inventory",
["library"] = "Library",
["maps"] = "Maps",
["mail"] = "Mail",
["miscellaneous"] = "Miscellaneous",
["quest"] = "Quest",
["raid"] = "Raid",
["tradeskill"] = "Tradeskill",
["unitframes"] = "UnitFrames",
}
local CATEGORY_ALIASES = {
["map"] = "maps",
["comm"] = "chat/communication",
["communication"] = "chat/communication",
["chat"] = "chat/communication",
["other"] = "miscellaneous",
["debugging"] = "debug",
["errors"] = "debug",
["debugging/errors"] = "debug",
["frames"] = "frame modification",
["social interaction"] = "social",
["bars"] = "action bars",
["unitframe"] = "unitframes"
}
Ace2 Standards
Unlike Ace, Ace2 picks up AddOn metadata directly from the TOC file. Special processing is done on certain fields, namely Version and X-Date, so that you can use CVS or Subversion keywords such as $Rev$ as their value.
In addition to the regular fields, Ace2 also looks for the following:
- X-Date
- X-eMail
- X-Website
- X-Category
The following recognized Ace2 AddOn categories are declared in AceAddon.lua.
local CATEGORIES = {
["Action Bars"] = "Action Bars",
["Auction"] = "Auction",
["Audio"] = "Audio",
["Battlegrounds/PvP"] = "Battlegrounds/PvP",
["Buffs"] = "Buffs",
["Chat/Communication"] = "Chat/Communication",
["Druid"] = "Druid",
["Hunter"] = "Hunter",
["Mage"] = "Mage",
["Paladin"] = "Paladin",
["Priest"] = "Priest",
["Rogue"] = "Rogue",
["Shaman"] = "Shaman",
["Warlock"] = "Warlock",
["Warrior"] = "Warrior",
["Healer"] = "Healer",
["Tank"] = "Tank",
["Caster"] = "Caster",
["Combat"] = "Combat",
["Compilations"] = "Compilations",
["Data Export"] = "Data Export",
["Development Tools "] = "Development Tools ",
["Guild"] = "Guild",
["Frame Modification"] = "Frame Modification",
["Interface Enhancements"] = "Interface Enhancements",
["Inventory"] = "Inventory",
["Library"] = "Library",
["Map"] = "Map",
["Mail"] = "Mail",
["Miscellaneous"] = "Miscellaneous",
["Quest"] = "Quest",
["Raid"] = "Raid",
["Tradeskill"] = "Tradeskill",
["UnitFrame"] = "UnitFrame",
}
Example .toc file
## Interface: 30100 ## Title : My AddOn ## Notes: This AddOn does nothing but display a frame with a button ## Author: My Name ## eMail: Author@Domain.com ## URL: http://www.wowwiki.com/ ## Version: 1.0 ## Dependencies: Sea ## OptionalDeps: Chronos ## DefaultState: enabled ## SavedVariables: settingName, otherSettingName MyScript.lua MyAddOn.xml MyFrame.xml MyButton.xml