TOC format
- ️Tue Feb 25 2025
.toc
files contain information about the addon (e.g. addon name, addon description, addon saved variables). They also specify the loading order for the addon's .lua
and .xml
files. A .toc
file is mandatory for an addon. The filename of the .toc
file must match the folder it's inside, otherwise the .toc
file won't load.
Rules
The .toc
file and folder name must match. For example ..\Interface\AddOns\MyAddon\MyAddon.toc
The .toc
file can optionally have the following elements:
- Metadata as
## Directive: Value
- Comments as
# this is a comment
- A list of files as
myFile.xml
orsubfolder\myFile.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 instead of forward slashes for paths to prevent issues with <Include>
tags.
Example .toc
file:
## Interface: 110100 ## Title: MyAddonName ## Notes: Brief description about what MyAddonName does to help people find it ## Version: 1.0.0 # This line is a comment MyFrame.xml MyCode.lua lib\MyCode.lua anotherfolder\MoreCode.xml
File loading order
The .toc
file includes a list of files to be loaded. The files are loaded in order, from top to bottom.
Not every file in your addon must appear in the .toc
file. This is because .xml
files can load files using <Script file="AnotherFile.lua" />
or <Include file="alsoLoadThis.xml" />
. Also, functions such as Texture:SetTexture()
and PlaySoundFile()
can specify image files and sound files contained within the addon folder and subfolders.
Multiple game versions (Retail, Cata Classic, WoW Classic)
Classic game versions can be supported by including multiple .toc
files in the same addon.[1] The WoW client first searches for the special file names as shown below, and if none are found, uses 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
Interface version
"Interface" is the WoW version the addon was made for. WoW uses this number to tell if an addon is out of date.
If an addon has an older interface version than the user's current WoW client version, the addon is classified as out of date. If you don't specify an Interface version, WoW will always treat the addon as out of date.
If the game version is 10.2.7, then the interface version is 100207:
You can also specify multiple versions with commas (this example targets 11.0.2, 4.4.0 and 1.15.3):
## Interface: 110002, 40400, 11503
Determining the interface version
GetBuildInfo
Type /dump (select(4, GetBuildInfo()))
in the chat box. This example shows the interface version during 9.2.7.
Warcraft Wiki
This wiki maintains a list template of the latest interfaces for each flavor of the game. The template is also shown below (these values are updated by contributors, so they may be out of date).
Expansion | Patch | TOC version | |
---|---|---|---|
![]() |
Mainline PTR | 11.1.5 | 110105
|
![]() |
Mainline | 11.1.0 | 110100
|
![]() |
Cataclysm Classic PTR | 4.4.2 | 40402
|
![]() |
Cataclysm Classic | 4.4.2 | 40402
|
![]() |
Classic Era PTR | 1.15.7 | 11507
|
![]() |
Classic Era | 1.15.6 | 11506
|
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
Category
Category name displayed in the AddOns list, displayed as a collapsible header entry.
It is strongly recommended that you stick to the translated category names found on the Addon Categories page. This will ensure that your addon is consistently located with other addons in the same category across all locales.
## Category: This is a test ## Category-deDE: Dies ist ein Test
Group
Addon used for grouping entries together in the AddOns list.
- The Group value must be the name of the main addon.
- Grouped addons are displayed in the addon list as indented sub-lists. These lists cannot be collapsed, unlike Categories.
- Nested groups are not supported by the addon list.
- If no Group has been manually specified, the client will attempt to automatically deduce membership of a group.
- Installed addons will be scanned to locate pairs of addons where the base name of one addon is a complete prefix of another, and where any form of dependency relation exists between the two in either direction.
IconTexture
Path to a texture file to be shown as the icon for this addon in the addon list. Optional.
## IconTexture: Interface\Icons\TEMP
IconAtlas
Name of a texture atlas to be shown as the icon for this addon in the addon list. Optional, and has a lower priority than IconTexture if both are set.
## 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
Name of a global function to be executed when the dropdown list button for this addon has been clicked. This field is required to have the addon be shown in the Addon Compartment list.
## AddonCompartmentFunc: MyAddon_OnAddonCompartmentClick
AddonCompartmentFuncOnEnter
Name of a global function to be executed when this dropdown list button for this addon has been highlighted. Optional.
## AddonCompartmentFuncOnEnter: MyAddon_OnAddonCompartmentEnter
AddonCompartmentFuncOnLeave
Name of a global function to be executed when this dropdown list button for this addon is no longer highlighted. Optional.
## AddonCompartmentFuncOnLeave: MyAddon_OnAddonCompartmentLeave
Loading conditions
The following directives control when an AddOn loads, and any dependencies that must or may load first.
LoadOnDemand
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.
## LoadWith: someAddOn, someOtherAddOn
LoadManagers
AddOns that, if present, trigger this one to behave as LoadOnDemand. See AddonLoader for an example.
## LoadManagers: someAddOn, someOtherAddOn
OnlyBetaAndPTR
1
if an addon should only be loadable in Beta or PTR clients.
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: MyAddOnNameFoo, MyAddOnNameBar
SavedVariablesPerCharacter
Variables saved in 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
EscalateErrorDuringLoad
Boolean directive that appears to have no effect in public clients.
LoadFirst
1
if a secure addon is not permitted to be disabled and should be loaded before any other addons without this flag.
SavedVariablesMachine
List of global variable names to be persisted across all accounts on the same machine.
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
Classic
Classic Era
Patch 1.15.4 (2024-09-24): Includes all changes present in patch 11.0.0.
See also
- GetAddOnInfo returns basic information about an addon.
- Using the AddOn namespace describes the parameters passed to each file.
References
- ^ a b Meo
rawr. Multiple Interface Version Support. WoWUIBugs.
Authoring | ||
---|---|---|
| ||
| ||
|