Wowpedia

We have moved to Warcraft Wiki. Click here for information and the new URL.

READ MORE

Wowpedia
Don't have an account?
Register
Register
Wowpedia
Wowpedia
274,795
pages
in: UI technical details

Changes: TOC format

Back to page
Sign in to edit
(Updating to latest WoW version number)
mNo edit summary
(38 intermediate revisions by 19 users not shown)
Line 1: Line 1:
 
{{uitech}}
  
{{uitech}}
  +
'''.toc''' (Table of Contents) files contain information about a particular addon (such as its name, description, saved variables, etc), as well as instructions on how the addon should be loaded by the client (for example, the order in which lua and xml files should be loaded). The file must be present, and have the same name (plus extension) as its parent folder for the addon to be recognized by the client.
   
  +
== Basic rules ==
−
The '''TOC format''' for files defines information about each [[AddOn]] installed, as well as specifies 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.
  
   
  +
The game client searches each subfolder of <code>...\Interface\AddOns\</code> (only one level deep) for .toc files having the same name as the subfolder. This .toc file has instructions of the following format:
−
WoW reads up to the first 1024 characters of each line only. Additional characters are ignored and do not cause an error.
  
  +
* Metadata printed as <code>## TagName : tagValue</code>, where whitespace is trimmed (except at the start of a line)
  +
* Comments printed as <code># this is a comment</code> ignored by the client
  +
* A list of files to be loaded as <code>myFile.xml</code> or <code>subfolder/anotherFile.lua</code>
   
  +
## Interface: {{API LatestInterface}}
−
== Where ==
  
  +
## Title: Waiting for Godot
−
World of Warcraft\Interface\AddOns\''MyAddon''\''MyAddon''.toc
  
  +
## Notes: Nothing to be done.
−
OR
  
  +
## Version: 4.2
−
c:\users\games\World of Warcraft\Interface\AddOns\''MyAddon''\''MyAddon''.toc
  
  +
Vladimir.xml
  +
Estragon.lua
  +
libs/SomeEmbeddedLibrary.lua
  +
  +
# This is a comment
   
−
== Client Recognized Tags ==
 +
== File load order ==
−
Each tag is preceeded by <code>## </code>, some postfixed with a localization label. Each occupies one line.
  
   
  +
The .toc file provides an ordered list of files to be loaded by the client. In the earlier example:
−
<code>Title</code> and <code>Notes</code> can be localized for other languages. For a complete list of localization labels, see [[API GetLocale]].
  
  +
* Vladimir.xml loads first, and is in the same folder as the .toc file
  +
* Estragon.lua loads second, and is in the same folder as the .toc file
  +
* SomeEmbeddedLibrary.lua loads third, and is in a subfolder called libs
   
  +
Not every file must appear in a .toc list:
−
=== Interface ===
  
  +
* xml files may contain [[XML elements#NonWidgets|<Script file="nameOfAnotherFile.lua" />]] or <Include file="alsoLoadThis.xml"/>
−
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]].
  
  +
* {{api|Texture SetTexture}} and {{api|PlaySoundFile}} can use images and sounds contained within the addon folder and its subfolders
   
  +
== Interface version ==
−
## Interface: 30200
  
   
  +
## Interface: {{API LatestInterface}}
−
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.
  
   
  +
The interface metadata specifies which version of the game client the addon has been made for. This field prevents users from experiencing errors by loading out-of-date addons or mixing Retail and Classic; unless they explicity ignore warnings and choose "Load out of date addons". Omitting this field causes the game to treat the addon as always out of date.
−
=== 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.
  
   
  +
There are a number of ways to get the current interface version:
−
## Title: My Addon
  
  +
:; It probably is {{API LatestInterface}} (retail) or {{API LatestInterface|classic}} (classic): But these numbers are [[Template:API LatestInterface|maintained locally]], so they ''might'' be out of date.
−
## Title-deDE: Titel
  
  +
:; Use {{api|GetBuildInfo}} : In particular, <code>/dump select(4, GetBuildInfo())</code> should output the correct version to your chat frame.
−
## Title-frFR: Titre
  
  +
:; Extract FrameXML and check FrameXML.toc: Launch wow with the <code>-console</code> flag, then at the login screen, activate the console using the `/~ key, and type <code>ExportInterfaceFiles code</code> to extract FrameXML files into World of Warcraft\BlizzardInterfaceCode.
  +
:; Steal it from another AddOn : Recently updated AddOns, which are not listed as "out of date" by the client contain the latest Interface version in their toc tag.
  +
Prior to [[patch 8.2.0]]:
  +
:; View FrameXML.toc online: For instance at [https://github.com/Gethe/wow-ui-source/blob/ea161a9537edcc5f5429640af3c5a1370912c6f5/FrameXML/FrameXML.toc wowcompares].
   
  +
== Display in the addon list ==
−
<code>Title</code> also supports the addition of color, similar to the way [[ItemLink|item links]] are colored internally. This will display "-Ace2-" in a foam green color.
  
   
  +
The following metadata change how an addon appears in the addon list.
−
## Title: ag_UnitFrames |cff7fff7f -Ace2-|r
  
   
  +
These tags support localization, which may written by appending a hyphen and the locale code to the tag name, such as <code>Title-enGB</code>. See [[Localization]] for a full list of current locale codes.
−
=== 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.
  
   
  +
Coloring is possible via [[UI escape sequences]] <code>|c########</code>.
−
## Notes: This is my first AddOn.
  
−
## Notes-deDE: Informationen
  
−
## Notes-frFR: Texte
  
   
  +
; Title : String - The name to display on the AddOns list (default: name of the addon's folder).
−
Notes: Like [[TOC format#Title|Title]] (above), Notes may also contain color tags.
  
  +
## Title: Waiting for Godot
  +
## Title-frFR: En attendant Godot
  +
; Notes : String - The description displayed when the user hovers over the addon entry in the AddOns list.
  +
## Notes: This word is |cFFFF0000<span style="color:red">red<span>!
   
−
=== RequiredDeps ===
 +
== Loading conditions ==
−
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.
  
   
  +
The following metadata changes when and how an addon loads:
−
## Dependencies: someAddOn, someOtherAddOn
  
−
Alternatively you could also use:
  
−
## RequiredDeps: someAddOn, someOtherAddOn
  
   
  +
; RequiredDeps, Dependencies, or any word beginning with "Dep" : String - A comma-separated list of addon (directory) names that must be loaded before this addon can be loaded. <pre> ## Dependencies: someAddOn, someOtherAddOn</pre>
−
'''Note''': ''Dependencies'', ''RequiredDeps'', and ''Dependancies'' [sic] all give the same result.
  
  +
; OptionalDeps : String - A comma-separated list of addon (directory) names that should be loaded before this addon if they ''can'' be loaded. <pre>## OptionalDeps: someAddOn, someOtherAddOn</pre>
  +
; LoadOnDemand : Number - If this value of this tag is "1", the addon is not loaded when the user first logs in, but can be loaded by another addon at a later point. This can be used to avoid loading situational addons.<pre>## LoadOnDemand: 1</pre>
  +
; LoadWith : String - A comma-separated list of addon (directory) names that, when loaded, will cause the client to load this LoadOnDemand addon as well. <pre>## LoadWith: someAddOn, someOtherAddOn</pre>
  +
; LoadManagers : String - A comma-separated list of addon (directory) names; if no addons on this list are loaded, the client will load your addon when the user logs in; if at least one addon on this list is loaded, your addon is treated as LoadOnDemand. An example of a LoadManager is [http://www.wowace.com/addons/addon-loader/ AddonLoader].
  +
; SavedVariables : String - A comma-separated list of variable names in the global environment that will be saved to disk when the client exits, and placed back into the global environment when your addon is loaded; the variables are not available before the {{api|t=e|ADDON_LOADED}} event fires for your addon. See [[Saving variables between game sessions]]. <pre>## SavedVariables: foo, bar</pre>
  +
; SavedVariablesPerCharacter : String - A comma-separated list of variable names in the global environment that will be saved to disk when the client exits, and placed back into the global environment when your addon is loaded for a particular character. Note that PerCharacter saved variables are only loaded for the character for which they were saved.<pre>## SavedVariablesPerCharacter: somePercharVariable</pre>
  +
; DefaultState : String - Determines whether the addon is enabled by default when first installed. If the value of this tag is "disabled", the user must explicitly enable the addon in the addons list before it is loaded.<pre>## DefaultState: enabled</pre>
   
−
=== OptionalDeps ===
 +
== Informational ==
  +
The following metadata do not change how an addon behaves, but may be accessed using {{api|GetAddOnMetadata}}:
−
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.
 
   
  +
; Author : String - The AddOn author's name, displayed
−
## OptionalDeps: someAddOn, someOtherAddOn
  
  +
; Version: String - The AddOn version. Some automatic updating tools may prefer that this string begins with a numeric version number.
  +
; X-_____: String - Any custom metadata prefixed by "X-", such as "X-Date", "X-Website" or "X-Feedback"
   
−
=== LoadOnDemand ===
 +
== Restricted ==
  +
; Secure : Number - If the value of this tag is 1 and the addon is digitally signed by Blizzard, its code is considered [[Secure Execution and Tainting|secure]].
−
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.
  
   
  +
== Notes ==
−
## LoadOnDemand: 1
  
  +
* WoW reads up to the first 1024 characters of each line only. Additional characters are ignored and do not cause an error.
−
## LoadOnDemand: 0
  
  +
* The list of files may be edited while the game is open (taking effect after <code>/reload</code>), but changing metadata has no effect and any files must have already been inside the AddOns folder
   
−
=== LoadWith ===
 +
== Patch changes ==
  +
* {{Patch 9.0.1|note=[[MACRO reload|/reload]] recognizes changes to TOC metadata and entirely new files.}}
−
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.
  
  +
* {{Patch 4.0.1|note=[[MACRO reload|/reload]] recognizes changes to the file order.}}
−  
  +
* {{Patch 2.1.0|note=Added LoadManagers metadata}}
−
## LoadWith: someAddOn, someOtherAddOn
  
  +
* {{Patch 1.11.0|note=Added Secure metadata}}
−  
  +
* {{Patch 1.9.0|note=Added LoadWidth metadata}}
−
=== 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 [http://www.wowace.com/projects/addon-loader 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|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 <code>WTF\Account\{youraccount}\AddOns.txt</code>, and this file overrides the old <code>DisabledAddOns.txt</code> 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|Title]] and [[#Notes|Notes]] can be retreived using [[API GetAddOnMetadata|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-<data> ====
  
−
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-<data> 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<br/>
  
−
OR SVN revision keyword stamp
  
−  
−
## X-Revision: 4025
  
−
## X-Revision: $Rev$
  
−  
−
==== X-Date ====
  
−
Release date of the AddOn<br/>
  
−
OR Release/creation date of the AddOn version<br/>
  
−
OR SVN date keyword stamp
  
−  
−
## X-Date: 2006-06-01
  
−
## X-Date: $Date$
  
−  
−
==== X-Email ====
  
−
Email of the AddOn's author.<br/>
  
−
Known permutations: eMail, X-eMail
  
−  
−
## X-Email: admin@cosmosui.org
  
−  
−
==== X-Website ====
  
−
Website where more information about the AddOn can be found.<br/>
  
−
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.
  
−  
−
<pre>
  
−
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"
  
−
}</pre>
  
−  
−
=== 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.
  
−  
−
<pre>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",
  
−
}</pre>
  
−  
−  
−
== 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
  
−  
−
== Maintaining AddOns ==
  
−
You can update your AddOns while the client is running by making changes to your LUA and XML files and reloading the UI (<code>/console ReloadUI</code>), but there are some important things to note:<br />
  
−
<span style="color: #ff0000">''all of the following require a full restart''</span>
  
−
* Changing the TOC, such as adding or removing saved variables and/or dependencies and referencing script files.
  
−
* Adding media files such as audio files, fonts, and graphics.
  
−
* Adding script files (even if you reference them in an XML file that was already seen and loaded by the client and if they are referenced in the TOC, but not present in the folder, before running the client).
  
   
 
== See also ==
  
== See also ==
  +
* {{api|GetAddOnInfo}} returns basic information about an addon.
−
* [[API GetAddOnDependencies]]
  
  +
* {{api|GetAddOnMetadata}} returns information listed in a specified .toc tag.
−
* [[API GetAddOnInfo]]
  
  +
* {{api|GetBuildInfo}} returns the client's interface version
−
* [[API GetAddOnMetadata]]
  
−
* [[API GetBuildInfo]]
  

Revision as of 22:36, 9 April 2021

HinaSalute The API is no longer being updated here until further notice.

.toc (Table of Contents) files contain information about a particular addon (such as its name, description, saved variables, etc), as well as instructions on how the addon should be loaded by the client (for example, the order in which lua and xml files should be loaded). The file must be present, and have the same name (plus extension) as its parent folder for the addon to be recognized by the client.

Basic rules

The game client searches each subfolder of ...\Interface\AddOns\ (only one level deep) for .toc files having the same name as the subfolder. This .toc file has instructions of the following format:

  • Metadata printed as ## TagName : tagValue, where whitespace is trimmed (except at the start of a line)
  • Comments printed as # this is a comment ignored by the client
  • A list of files to be loaded as myFile.xml or subfolder/anotherFile.lua
## Interface: 100206
## Title: Waiting for Godot
## Notes: Nothing to be done.
## Version: 4.2
Vladimir.xml
Estragon.lua
libs/SomeEmbeddedLibrary.lua

# This is a comment

File load order

The .toc file provides an ordered list of files to be loaded by the client. In the earlier example:

  • Vladimir.xml loads first, and is in the same folder as the .toc file
  • Estragon.lua loads second, and is in the same folder as the .toc file
  • SomeEmbeddedLibrary.lua loads third, and is in a subfolder called libs

Not every file must appear in a .toc list:

  • xml files may contain <Script file="nameOfAnotherFile.lua" /> or <Include file="alsoLoadThis.xml"/>
  • Texture SetTexture and PlaySoundFile can use images and sounds contained within the addon folder and its subfolders

Interface version

## Interface: 100206

The interface metadata specifies which version of the game client the addon has been made for. This field prevents users from experiencing errors by loading out-of-date addons or mixing Retail and Classic; unless they explicity ignore warnings and choose "Load out of date addons". Omitting this field causes the game to treat the addon as always out of date.

There are a number of ways to get the current interface version:

It probably is 100206 (retail) or 11501 (classic)
But these numbers are maintained locally, so they might be out of date.
Use GetBuildInfo
In particular, /dump select(4, GetBuildInfo()) should output the correct version to your chat frame.
Extract FrameXML and check FrameXML.toc
Launch wow with the -console flag, then at the login screen, activate the console using the `/~ key, and type ExportInterfaceFiles code to extract FrameXML files into World of Warcraft\BlizzardInterfaceCode.
Steal it from another AddOn
Recently updated AddOns, which are not listed as "out of date" by the client contain the latest Interface version in their toc tag.

Prior to patch 8.2.0:

View FrameXML.toc online
For instance at wowcompares.

Display in the addon list

The following metadata change how an addon appears in the addon list.

These tags support localization, which may written by appending a hyphen and the locale code to the tag name, such as Title-enGB. See Localization for a full list of current locale codes.

Coloring is possible via UI escape sequences |c########.

Title
String - The name to display on the AddOns list (default: name of the addon's folder).
## Title: Waiting for Godot
## Title-frFR: En attendant Godot
Notes
String - The description displayed when the user hovers over the addon entry in the AddOns list.
## Notes: This word is |cFFFF0000red!

Loading conditions

The following metadata changes when and how an addon loads:

RequiredDeps, Dependencies, or any word beginning with "Dep"
String - A comma-separated list of addon (directory) names that must be loaded before this addon can be loaded. 
 ## Dependencies: someAddOn, someOtherAddOn
OptionalDeps
String - A comma-separated list of addon (directory) names that should be loaded before this addon if they can be loaded. 
## OptionalDeps: someAddOn, someOtherAddOn
LoadOnDemand
Number - If this value of this tag is "1", the addon is not loaded when the user first logs in, but can be loaded by another addon at a later point. This can be used to avoid loading situational addons.
## LoadOnDemand: 1
LoadWith
String - A comma-separated list of addon (directory) names that, when loaded, will cause the client to load this LoadOnDemand addon as well. 
## LoadWith: someAddOn, someOtherAddOn
LoadManagers
String - A comma-separated list of addon (directory) names; if no addons on this list are loaded, the client will load your addon when the user logs in; if at least one addon on this list is loaded, your addon is treated as LoadOnDemand. An example of a LoadManager is AddonLoader.
SavedVariables
String - A comma-separated list of variable names in the global environment that will be saved to disk when the client exits, and placed back into the global environment when your addon is loaded; the variables are not available before the ADDON_LOADED event fires for your addon. See Saving variables between game sessions. 
## SavedVariables: foo, bar
SavedVariablesPerCharacter
String - A comma-separated list of variable names in the global environment that will be saved to disk when the client exits, and placed back into the global environment when your addon is loaded for a particular character. Note that PerCharacter saved variables are only loaded for the character for which they were saved.
## SavedVariablesPerCharacter: somePercharVariable
DefaultState
String - Determines whether the addon is enabled by default when first installed. If the value of this tag is "disabled", the user must explicitly enable the addon in the addons list before it is loaded.
## DefaultState: enabled

Informational

The following metadata do not change how an addon behaves, but may be accessed using GetAddOnMetadata:

Author
String - The AddOn author's name, displayed
Version
String - The AddOn version. Some automatic updating tools may prefer that this string begins with a numeric version number.
X-_____
String - Any custom metadata prefixed by "X-", such as "X-Date", "X-Website" or "X-Feedback"

Restricted

Secure
Number - If the value of this tag is 1 and the addon is digitally signed by Blizzard, its code is considered secure.

Notes

  • WoW reads up to the first 1024 characters of each line only. Additional characters are ignored and do not cause an error.
  • The list of files may be edited while the game is open (taking effect after /reload), but changing metadata has no effect and any files must have already been inside the AddOns folder

Patch changes

See also

Community content is available under CC BY-SA 3.0 unless otherwise noted.
More Fandoms