.toc 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.
A typical .toc file
Suppose you were writing addon called "Godot". In order to get the client to recognize your addon, you'd have to create the
World of Warcraft\Interface\AddOns\Godot folder, and a
Godot.toc file within it. The contents of the .toc file could be:
## Interface: 70300 ## Title: Waiting for Godot ## Notes: Nothing to be done. ## Version: 4.2 Vladimir.xml Estragon.lua
There are two 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 Godot" communicates to the client that the addon should be called "Waiting for Godot" in the addons list, rather than simply "Godot" 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 Vladimir.xml file in the addon's folder should be loaded before Estragon.lua in the same folder.
There are a number of "official" (either used by the client or explicitly allowed access to via GetAddOnMetadata) .toc tags. The 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. Below is a list of tag names and descriptions of how their values are used:
- 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: 70300
- 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 coloring UI escape sequences.
## Title: Waiting for Godot
## Title-frFR: En attendant Godot
- 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 coloring 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
- A comma-separated list of addon (directory) names that should be loaded before this addon if they can be loaded.
## OptionalDeps: someAddOn, someOtherAddOn
- 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
- 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
- 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.
- 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
- 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
- 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
- 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.
- The AddOn author's name
- The AddOn version. Some automatic updating tools may prefer that this string begins with a numeric version number.
It is possible for addons to query values of any tags with a "X-" prefix. Some possibilities include:
- 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 are read only when the client initially starts up. Any changes made to the .toc file will be ignored by a running client until the client is restarted (more specifically, content read from .toc files is not refreshed when you reload the user interface or log out / log in. Although some changes will be picked up if you log out to the character selection screen and back in).
- As of 5.4.8, some changes take effect when user interface is reloaded
- Removing a .lua from ToC stops loading the file
- Adding a .lua that was in the addon folder at time of client start loads the new file
- Adding a .lua that was not in the addon folder at time of client start does not load the new file
- Tags are not reread when interface is reloaded
- XML files can be loaded from the ToC, if their path matches that of the ToC. XML files deeper in the path can be loaded from that XML file.
- Prefixing a line with one # will mark it as a comment, meaning that it will not be read. For example:
# This is a comment