Wikia

WoWWiki

TOC format

Talk1
101,388pages on
this wiki

Redirected from The TOC Format

WoW AddOn


This article describes the WoW TOC file format.

TOC file format Edit

There are three main line types: lines beginning with "## " designate a .toc tag, which contains 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.

## Interface: 50400
## Title: Waiting for Bob
## Notes: Nothing to be done.
## Version: 1.0
Bob.xml
Bob.lua
# comment

Addon called "Waiting for Bob".

main line types Edit

  • 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 load time

Tags Edit

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:

## TagName : tagValue

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

Files Edit

Typically after the tags come the files:

Bob.xml
Bob.lua

Comments Edit

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

# This is a comment

Details Edit

  • 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.
  • 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 Edit

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:

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.
## Interface: 50400
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.
## Title: Waiting for Godot
## Title-frFR: En attendant Godot
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.
## Notes: "Nothing to be done"
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.
 ## Dependencies: someAddOn, someOtherAddOn
OptionalDeps
A comma-separated list of addon (directory) names that should be loaded before this addon if they can be loaded.
## OptionalDeps: someAddOn, someOtherAddOn
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.
## LoadOnDemand: 1
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
## LoadWith: someAddOn, someOtherAddOn
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.
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.
## SavedVariables: foo, bar
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.
## SavedVariablesPerCharacter: somePercharVariable
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.
## DefaultState: enabled
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.
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.

Metadata tags Edit

It is possible for addons to query values of any tags with a "X-" prefix. Some possibilities include:

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

See also Edit

Around Wikia's network

Random Wiki