WoW:TOC format

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ UI AddOn

← WoW AddOn

This article describes the WoW TOC file format. The name of the file must match the name of the addon folder.

TOC file format

The TOC format consists of a series of lines, where each line is like a separate command. There are four main types of lines: comments, properties, files, and blank lines. Each line is examined in order, from the top of the file to bottom, one time only.

Lines beginning with "## " designate a '.toc' tag, which contain information that may be used by the client. For instance, "## Title : Waiting for Bob" communicates to the client that the addon should be called "Waiting for Bob" in the addons list, rather than simply "Bob" as its folder name would imply. The lines without this prefix specify the files that should be loaded by the client when this addon is run: in this case, the Bob.xml file in the addon's folder should be loaded before Bob.lua in the same folder.

Addon called "Waiting for Bob".

line types

• lines beginning with '#': designate a comment, and are ignored
• lines beginning with '## ': designate a .toc 'Tag' and provide metadata about the AddOn
• lines that are file names: provide the names of files to load during AddOn load time

Tags

Tags are metadata for an AddOn. Like 'Author' and 'Version'.

Lines beginning with "## " designate a .toc tag, and tags can be added to a .toc file in any order in the following format:

Both the TagName and tagValue are trimmed: excess whitespace does not prevent the tags from being recognized.

Files

Typically after the tags come the files:

Comments

Prefixing a line with a # will mark it as a comment, meaning that it will not be read. For example:

Naming the TOC file

There are special rules for naming a .toc file.

Default name

The default name for a '.toc' file is the name of the addon folder with an extension of '.toc'.

AddOns
  MyAddOn
    MyAddOn.toc
    code.lua
    frame.xml

In this example the AddOn is named 'MyAddOn'. WoW will look for a file named MyAddOn.toc as the addons toc file, because the folder name was MyAddon. They must match.

Names for WoW editions

Each WoW edition can load its own .toc file for an addon. Each addon can have more than one .toc that could be loaded by WoW. WoW will first look for a special .toc for that edition, and if not found will load the default .toc that has the same name as the addon folder, as explained above.

AddOns
  MyAddOn
    MyAddOn.toc
    MyAddOn_Classic.toc
    MyAddOn_Vanilla.toc
    code.lua
    frame.xml

In this example the AddOn has alternate .toc files for both Classic and WotLK, as well as the default .toc file. When the WotLK edition loads, it will look first for 'MyAddOn_Wrath.toc' then for 'MyAddOn.toc', if 'MyAddOn_Wrath.toc' is not found.

So if 'MyAddOn_Wrath.toc' is found, it will only load that .toc and ignore any others. If it's not found, it will load the default 'MyAddOn.toc', ignoring any others.

Why multiple .toc files

There are two big reasons:

1. Code differences

   If there were big enough differences between two editions of WoW for an addon, that it would be easier to just use two or more different sets of some of the code or XML files, then the addon would need different .toc files to load the different sets of code for each edition.

2. The 'Interface' version numbers

   Each edition has its own series of interface version numbers. Because of this and because you only have one '## Interface:' line to specify the number, you will actually need a .toc file for each supported edition. Otherwise, users will have to click the 'load outdated' checkbox to load your addon.

Edition names

Known main-use name postfixes (shown in full name context) are:

• MyAddon.toc - the default .toc file. Any edition or game mode will load this file, including retail.
• MyAddOn_Classic.toc - used for any Classic edition
• MyAddOn_Vanilla.toc - used for the original _classic_era_ edition

Other known name postfixes (shown in full name context) are:

• MyAddOn_Mainline.toc - used for Retail. Highly suggested to just use default instead
• MyAddOn_Mists.toc - used for Cataclysm. Suggested to use 'Classic' instead, and differentiate with 'Vanilla' if necessary
• MyAddOn_Standard.toc - used for any standard mode, version or edition. will be ignored when non-standard mode is loaded.
• MyAddOn_WoWLabs.toc - used for a non-standard game mode

Deprecated or unused (shown in full name context) are:

• MyAddOn_Cata.toc - used for Cataclysm. There is no longer a way to load Cataclysm
• MyAddOn_Wrath.toc - was used for WotLK. There is no longer a way to load WotLK
• MyAddOn_TBC.toc - was used for TBC. There is no longer a way to load TBC
• MyAddOn-Wrath.toc - older deprecated postfix for WotLK
• MyAddOn-WOTLKC.toc - older deprecated postfix for WotLK
• MyAddOn-TBC.toc - older deprecated postfix for TBC
• MyAddOn-BCC.toc - older deprecated postfix for TBC
• MyAddOn-Classic.toc - older deprecated postfix for Classic
• MyAddOn-Mainline.toc - older deprecated postfix for Retail
• MyAddOn_PlunderStorm.toc - used for a PlunderStorm game mode

Edition precedence

This shows the order in which TOC names are tried by the engine. Once a name is found, that will become the active TOC for the AddOn for that UI session and be the one loaded.

• Specific games are attempted first. Because of this 'Vanilla' will take precedence over 'Classic' below. Only one game can be loaded at time, so these are all equal:

• Mainline, Vanilla, TBC, Wrath, Cata

• Next, these are categories of games or modes, in precedence order. These will be searched for after the specific games above:

• WoWLabs, Classic, Standard

Details

• In order to get the client to recognize your addon, you have to create the 'World of Warcraft\Interface\AddOns\Bob' folder, and a 'Bob.toc' file within it using the same name.
• TOC files in an addon folder that do not match the AddOn folder name, will be ignored.
• WoW reads up to the first 1024 characters of each line only. Additional characters are ignored and do not cause an error.
• The .toc files for all addons are only read when the client initially starts up. Any changes made to the .toc file will be ignored by a running client until the entire client is restarted. Restarting the UI or logging in or out will not get WoW to use a new version of the file. In other words, on reload of the UI, the original version of the addons .toc file will be executed that was read when wow was started. Note: some later versions of WoW will reload the .toc when exit to loading, and some when reload UI.
• Lines in the toc can be relative paths.
• Lines can refer to Lua files and XML files.
• 'File' lines will only be trimmed on the right. A line that reads ' bob.lua ' will get processed as '\Interface\AddOns\Bob\ bob.lua', where there is still a presumably inadvertent space between '\' and 'bob.lua', and no longer a space after '.lua'.
• Lines in a TOC file that are relative paths are processed such that 'relative AddOn path' + '\' + 'file line' = 'file path'. So 'fred\bob.lua' will request exactly 'Interface\AddOns\Bob\fred\bob.lua'

Official Tags

There are a number of "official" (either used by the client or explicitly allowed access to via GetAddOnMetadata) .toc tags. Below is a list of official tag names and descriptions of how their values are used:

Common AddOn tags

Interface

Specifies which client interface version the addon was made for. If the value of this tag does not match the client interface version, the addon is loaded only if the "Load out of date addons" option is enabled. There are a number of ways to determine the current interface version.

Title

The value of this tag is displayed in the AddOns list. Localized versions can be included by appending a hyphen followed by the client locale name; the client automatically chooses a localized version if one is available. The value may also contain UI escape sequences, such as for example colors.

Author

The AddOn author's name

Version

The AddOn version. Some automatic updating tools may prefer that this string begins with a numeric version number.

Notes

Addon description that appears when the user hovers over the addon entry in the addons list. Like Title, this tag can be localized by appending a hyphen followed by locale name, and contain UI escape sequences.

SavedVariables

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.

SavedVariablesPerCharacter

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.

Other tags

RequiredDeps, Dependencies, or any word beginning with "Dep"

A comma-separated list of addon (directory) names that must be loaded before this addon can be loaded.

OptionalDeps

A comma-separated list of addon (directory) names that should be loaded before this addon if they can be loaded.

LoadOnDemand

If the 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.

LoadWith

A comma-separated list of addon (directory) names that, when loaded, will cause the client to load this LoadOnDemand addon as well. Added in Patch 1.9

LoadManagers

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. Introduced in patch 2.1; an example of a LoadManager is AddonLoader.

DefaultState

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.

Secure

If the value of this tag is 1, and the addon is digitally signed by Blizzard, its code is considered secure (as opposed to tainted, which is what all 3rd-party addons are). Introduced in Patch 1.11.

Filter tags

These tags affect the entire ToC loading, based on WoW edition or UI mode. These work similar to the TOC file name #Names for WoW editions automatic loading mechanism. See also #File markup, for the file-line specific version.

AllowLoad

A UI mode name. Restricts loading of this TOC for the current "UI realm". If this tag is missing, is empty, or set as 'Both' then the loading of the TOC is unrestricted. Not generally used with user AddOns. Values: Both, Game, Glue.

Values:

• Glue
• Game
• Both

AllowLoadGameType

Restricts loading of this TOC to a set of particular editions, classic games, or categories. For a user AddOn this can be the same as setting the TOC file name to restrict which TOC file will be used. This setting uses the exact same type monikers as the file prefixes. The main difference is that the TOC file name version is used when the engine searches for the correct TOC for an AddOn, and the version here in TOC settings is primarily used to ignore inappropriate dependencies that were already listed explicitly by another AddOn TOC file. Not generally used with user AddOns. Values: See #Edition_names.

Retail or Classic:

• Classic
• Mainline

Classic

• Vanilla
• TBC
• Wrath
• Cata
• Mists

Special Games:

• PlunderStorm
• WoWLabs
• Standard

AllowLoadTextLocale

Restricts loading of this TOC to a particular set of WoW text locales. Not generally used with user AddOns.

Values:

• enUS
• frFR
• ruRU
• zhCN
• zhTW
• ... (or whatever other text localization code the wow client is set to)

User metadata tags

It is possible to safely add your own ToC tags, which are commonly prefixed with 'X-'. Addons can query the values of any tags. See GetAddOnMetadata. See Some possibilities include:

• X-Date
• X-Website
• X-Feedback

This was more of a user created convention, rather than any part of WoW itself. The intent of the 'X' prefix was to make sure the user created tag name never conflicted with any current or future WoW TOC tag.

File markup

File lines can have special markup, placed on the same line as the file, that alter how the file is named or processed. There are two classes of markup: 1) path text replacement, and 2) file directive.

File path text replacement

The '[Game]' markup gets replaced with the name of the current game type. See the 'AllowLoadGameType' tag.

File line directive

The file line will only be used if one of the games listed '[AllowLoadGameType xx,xx]' is the current game type. This is a single file line version of the 'AllowLoadGameType' tag.

Names and values

File line directives, with values

• AllowLoad
  • Glue
  • Game
  • Both
• AllowLoadGameType

  (default UI uses all lower-case for these values)

  • vanilla
  • tbc
  • wrath
  • cata
  • mists
  • mainline
• AllowLoadTextLocale
  • enUS
  • frFR
  • ruRU
  • zhCN
  • zhTW
  • ... (or whatever other text localization code)

File path markup names, with replacement values

• Family
  • Classic
  • Mainline
• Game
  • Vanilla
  • TBC
  • Wrath
  • Cata
  • Mists
  • Mainline
• TextLocale
  • enUS
  • frFR
  • ruRU
  • zhCN
  • zhTW
  • ... (or whatever other text localization code the wow client is set to)

Examples

Automatically generates line 'Localizations_enUS.lua' during AddOn load, if the current text locale is 'enUS'

Notes

Directives

• The placement of the file directives does not matter. They can be placed in the front, the middle of the file name, or the end.
• If a file directive markup tag is recognized, the whole markup tag will be removed.
• If a markup tag is not recognized it will stay on the line exactly as is.
• Directive values are not case-sensitive.
• Directives can be placed right against the file name at the end on the right, or separated on the right by spaces and/or tabs. In this case the whitespace will be removed from the end of the file name.
• Some directive names may have extra characters at the end of the name on the right side, and still be recognized. For example 'AllowLoadGameTypee' is treated as 'AllowLoadGameType' and all values will still function as before.
• 'AllowLoadGameTyp' or 'AllowLoadFrog' will get recognized as 'AllowLoad' and the markup tag will also get removed, but will default to 'Glue'.
• However 'AllowFrogLoad' will not get recognized and the whole markup tag will remain, and effectively count toward the file name text.
• Any unrecognized directive value will get treated as though it didn't exist, and for directives with all unrecognized values, the directive markup will still be removed.

Replacements

• The placement of the replacement markup can be anywhere on the line. Even after directives.
• If a replacement markup tag is recognized, the whole markup tag will be removed and replaced with associated text.
• If a markup tag is not recognized it will stay on the line exactly as is.
• Some replacement markup names may have extra characters at the end of the name on the right side, and still be recognized. For example 'Familyy' is treated as 'Family' and the replacement values will function as before.

General

• Markup names for both directives and replacements are case-sensitive.
• Empty markup, or markup containing only tabs and/or spaces, will be treated as unrecognized, and is left in place verbatim.
• Spaces or tabs will not be trimmed between markup and text, or markup and markup.
• However, spaces or tabs will be trimmed from the right side only, after the all the markup is executed to make the final name.
• But as a reminder, spaces or tabs are never trimmed from the left side, and will be significant

See also

• GetAddOnInfo returns basic information about an addon.
• GetAddOnMetadata returns information listed in a specified .toc tag.
• GetBuildInfo returns the client's interface version.
• GetLocale returns the client's locale.