TOC format
.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
orsubfolder\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: 100206
## Title: Waiting for Godot
## Notes: Nothing to be done.
## Version: 1.0.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
- Clients also recognize legacy suffixes
-WOTLKC
and-BCC
. - The
_Classic
suffix has changed and is now used for addons that can be loaded on all Classic client flavors.- Files with this TOC suffix have a lower priority than other suffixes that target specific clients. For example, having both a
_Cata.toc
and_Classic.toc
file will result in the former being used on Cataclysm Classic clients, and the latter in all other Classic client flavors.
- Files with this TOC suffix have a lower priority than other suffixes that target specific clients. For example, having both a
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()
andPlaySoundFile()
can use images and sounds contained within the addon folder and its subfolders
Interface version
The interface field declares the version of the game client for which the addon has been made. This field guarantees that users of an addon will have a game API that is compatible with the one the author used during development.
Conversely, if addons declare an older interface than the user's current one, instability and breakages may occur because the game API changes over time. However, users may opt into this risk by ticking the "Load out of date addons" checkbox. Additionally, the omission of this field causes the game to treat the addon as always out of date.
Here is an example of how this field is declared in TOC files:
## Interface: 100206
As of Patch 10.2.7 and Patch 4.4.0, multiple Interface versions may be specified delimited by commas. The following example would declare an addon as being compatible with the latest version of all client flavors:
## Interface: 100206, 40400, 11502
Interface sources
There are a number of ways to get the current interface version.
Warcraft Wiki
This wiki maintains a set of the latest interfaces for each flavor of the game. They are displayed in the table below. Note that these values are updated by contributors, so they may occasionally be out of date.
Flavor | Patch | TOC version | |
---|---|---|---|
The War Within | 11.0.0 | 110000
| |
Mainline PTR | 10.2.7 | 100207
| |
Mainline | 10.2.6 | 100206
| |
Cataclysm Classic | 4.4.0 | 40400
| |
Wrath Classic | 3.4.3 | 30403
| |
Classic Era | 1.15.2 | 11502
|
GetBuildInfo
The GetBuildInfo API function will return data about the currently released game client that is available to players. For example, /dump (select(4, GetBuildInfo()))
will output the interface version to your chat frame.
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
## Title: Waiting for Godot
## Title-frFR: En attendant Godot
Notes
## Notes: This word is |cFFFF0000red|r
IconTexture
## IconTexture: Interface\Icons\TEMP
IconAtlas
## IconAtlas: TaskPOI-Icon
Addon compartment integration
The following directives will control the registration of the addon into the Addon compartment dropdown accessible from the minimap.
AddonCompartmentFunc
## AddonCompartmentFunc: MyAddon_OnAddonCompartmentClick
AddonCompartmentFuncOnEnter
## AddonCompartmentFuncOnEnter: MyAddon_OnAddonCompartmentEnter
AddonCompartmentFuncOnLeave
## AddonCompartmentFuncOnLeave: MyAddon_OnAddonCompartmentLeave
Loading conditions
The following directives control when an AddOn loads, and any dependencies that must or may load first.
LoadOnDemand
Dependencies
RequiredDeps
and any word beginning with Dep
.
## Dependencies: someAddOn, someOtherAddOn
OptionalDeps
## OptionalDeps: someAddOn, someOtherAddOn
LoadWith
## LoadWith: someAddOn, someOtherAddOn
LoadManagers
## 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
WTF/[account]/SavedVariables
.
## SavedVariables: MyAddOnNameFoo, MyAddOnNameBar
SavedVariablesPerCharacter
WTF/[account]/[server]/[character]/SavedVariables
.
## SavedVariablesPerCharacter: MyAddOnNameAnotherVariable
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 tags are inaccessible to third-party AddOns.
AllowLoad
Restricts loading this addon to either the GlueXML or FrameXML environments.
Value | Environment |
---|---|
Both |
Allow this addon to load without restriction in all environments. |
Game |
Only load this addon in the FrameXML environment. |
Glue |
Only load this addon in the GlueXML environment. |
AllowLoadGameType
Restricts loading this addon to specific client flavors. Multiple values may be supplied, delimited by commas.
Game Type | Flavors | |
---|---|---|
mainline |
Mainline | |
classic |
All Classic flavors | |
cata |
Cataclysm Classic | |
wrath |
Wrath of the Lich King Classic | |
tbc |
Burning Crusade Classic | |
vanilla |
Classic Era | |
standard |
Normal game mode in all client flavors | |
wowlabs |
Special game modes, such as Plunderstorm |
LoadFirst
1
if a secure addon is not permitted to be disabled and should be loaded before any other addons without this flag.
OnlyBetaAndPTR
1
if an addon should only be loadable on test realms.
SavedVariablesMachine
List of global variable names to be persisted across all accounts on the same machine.
Secure
1
with Blizzard's digital signature to indicate a secure AddOn.
SuppressLocalTableRef
1
if the addon should not be supplied a private namespace table when loaded. Removed in Patch 11.0.0, replaced by UseSecureEnvironment.
UseSecureEnvironment
1
if all files present in an addon should be loaded into a private function environment.
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
Retail
- Patch 11.0.0 (Alpha): Added the restricted UseSecureEnvironment metadata field. Removed the SuppressLocalTableRef metadata field.
- Patch 10.2.7 (2024-05-07): Added support for comma-delimited Interface versions, and the restricted AllowLoadGameType and SuppressLocalTableRef metadata fields. Renamed AllowLoadByGameMode to AllowLoadGameType, and GuardedAddOn to LoadFirst.
- Patch 10.2.6 (2024-03-19): Added the restricted AllowLoadByGameMode metadata field.
- Patch 10.1.0 (2023-05-02): Added IconAtlas, IconTexture, and Addon compartment related metadata fields. Added the restricted GuardedAddOn metadata field.
- Patch 9.1.0 (2021-06-29): Multiple TOC files are now supported using a suffix to disambiguate Classic, BCC and Retail.[1]
- Patch 9.0.1 (2020-10-13): /reload recognizes changes to TOC metadata and entirely new files in the Interface/AddOns/ directory tree.
- Patch 4.0.1 (2010-10-12): /reload recognizes changes to the file order.
- Patch 2.1.0 (2007-05-22): Added LoadManagers metadata
- Patch 1.11.0 (2006-06-19): Added Secure metadata
- Patch 1.9.0 (2006-01-03): Added LoadWith metadata
Classic
- Patch 4.4.0 (2024-04-30): Includes all changes present in patch 10.2.7. Additionally, the behavior of the _Classic TOC suffix has changed such that it now loads on all Classic clients, and not just Classic Era.
See also
- GetAddOnInfo returns basic information about an addon.
- Using the AddOn namespace describes the parameters passed to each file.
References
- ^ a b Meorawr. Multiple Interface Version Support. WoWUIBugs.
|