Wowpedia
Advertisement

.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 file and addon folder name need to match, e.g. ..\Interface\AddOns\MyAddon\ and MyAddon.toc

The file may contain the following elements:

  • Metadata as ## Directive: Value
  • Comments as # this is a comment
  • A list of files as myFile.xml or subfolder\anotherFile.lua

Whitespace before # will be interpreted as the start of a filename. However, the client trims whitespace around metadata values (after the colon).

Backslashes (\) are recommended for subdirectories to prevent issues with <Include> tags.

## Interface: 90205
## Title: Waiting for Godot
## Notes: Nothing to be done.
## Version: 1.0

# This line is a comment
Vladimir.xml
Estragon.lua
libs\SomeLibrary.lua

Multiple client flavors

Classic and retail versions of the game can be properly supported by including multiple TOC files in the same addon.[1] The client first searches for the respective suffix and otherwise falls back to AddonName.toc

Flavor Suffix
Shadowlands Retail AddonName_Mainline.toc
Wrath of the Lich King Wrath of the Lich King Classic AddonName_Wrath.toc
Bc icon.gif Burning Crusade Classic AddonName_TBC.toc
WoW Icon update.png Classic Era AddonName_Vanilla.toc
  • Clients also recognize legacy suffixes -WOTLKC, -BCC, and -Classic.
  • It's recommended to simply use AddonName.toc for retail since CurseForge otherwise will not accept the zip.

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
  • SomeLibrary.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: 90205

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 90205 (retail), 20504 (bc classic) or 11403 (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.
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.

Prior to patch 8.2.0:

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.
View FrameXML.toc online
For instance at wowcompares.

AddOns list formatting

The following directives change how an AddOn appears in the AddOns list. Both may be coloured using UI escape sequences (e.g. |c########|r), or localized by appending a hyphen and the locale code (e.g.Title-enGB). Later entries overwrite earlier ones, so the non-localized fallback should go first.

Title

Name displayed in the AddOns list.
## Title: Waiting for Godot
## Title-frFR: En attendant Godot

Notes

Tooltip displayed in the AddOns list.
## Notes: This word is |cFFFF0000red|r

Loading conditions

The following directives control when an AddOn loads, and any dependencies that must or may load first.

LoadOnDemand

1 to delay loading until LoadAddOn().
## LoadOnDemand: 1

Dependencies

AddOns that must load first. Aliases include RequiredDeps and any word beginning with Dep.
## Dependencies: someAddOn, someOtherAddOn

OptionalDeps

AddOns that should load first if available.
## OptionalDeps: someAddOn, someOtherAddOn

LoadWith

AddOns that, once loaded, trigger this one to load. Implies LoadOnDemand. Warning Warning: Currently broken on Classic - Issue #223.
## LoadWith: someAddOn, someOtherAddOn

LoadManagers

AddOns that, if present, trigger this one to behave as LoadOnDemand. See AddonLoader for an example.
## LoadManagers: someAddOn, someOtherAddOn

DefaultState

disabled to require the user to explicitly enable the AddOn in the AddOns list.
## DefaultState: disabled

Saved variables

Main article: Saving variables between game sessions

SavedVariables

Variables saved in WTF/[account]/SavedVariables.
## SavedVariables: foo, bar

SavedVariablesPerCharacter

Variables saved in WTF/[account]/[server]/[character]/SavedVariables.
## SavedVariablesPerCharacter: anotherVariable

Informational

The following metadata may be accessed using GetAddOnMetadata().

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

Restricted

The following tag is inaccessible to third-party AddOns.

Secure
1 with Blizzard's digital signature to indicate a secure AddOn.

Details

  • WoW reads up to the first 1024 characters of each line only. Additional characters are ignored and do not cause an error.
  • Starting from Patch 9.0, 1.14.0 and 2.5.3, newly created/added files and even complete addons, are also detected when doing a /reload after the game started.

Patch changes

  • Shadowlands Patch 9.1.0 (2021-06-29): Multiple TOC files now possible using a suffix to disambiguate Classic, BCC and Retail.[1]
  • Shadowlands Patch 9.0.1 (2020-10-13): /reload recognizes changes to TOC metadata and entirely new files.
  • Cataclysm Patch 4.0.1 (2010-10-12): /reload recognizes changes to the file order.
  • Bc icon.gif Patch 2.1.0 (2007-05-22): Added LoadManagers metadata
  • WoW Icon update.png Patch 1.11.0 (2006-06-19): Added Secure metadata
  • WoW Icon update.png Patch 1.9.0 (2006-01-03): Added LoadWith metadata

See also

References

 
  1. ^ a b MeoInv g fishingbobber 05.pngrawr. Multiple Interface Version Support. WoWUIBugs.
Advertisement