TOC format

.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 or subfolder\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: 110105
## 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.

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:

## Interface: 100207

For addons that support multiple client flavors with one TOC file, multiple interface versions can be specified delimited by commas:

## Interface: 110105, 40402, 11507

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 template of the latest interfaces for each flavor of the game. A table of its values is shown below (these values are updated by contributors, so they may be out of date).

Client		Interface
	Mainline Test	`110107`
	Mainline	`110105`
	Classic Beta	`50500`
	Classic Test	`40402`
	Classic	`40402`
	Classic (China)	`30404`
	TBC	`20504`
	Vanilla Test	`11507`
	Vanilla	`11507`

Per-file conditions and variables

TOC files support the use of variable expansions and conditional loading directives within parts of the file listing.

Conditions

Loading conditions of the form [Directive value...] can be used within file references. Currently, support for conditions is limited to the AllowLoad and AllowLoadGameType directives described elsewhere in this document.

Conditions can appear anywhere in a line, but for reasons of compatibility should generally only ever be used at the end of a line as follows.

## Interface: 110105
## Title: My Cool Addon

# This will only be loaded on Mainline.
MainlineOnly.lua [AllowLoadGameType mainline]

# This will only be loaded in Vanilla or TBC.
VanillaOrTBC.lua [AllowLoadGameType vanilla, tbc]

Variables

Variables of the form [Variable] can be used within file references. The following variables are currently supported by the client.

Variable	Description
[Family]	Expands out to either Mainline or Classic based upon the current active game type.
[Game]	Expands out to either Standard, Vanilla, TBC, Wrath, Cata, or Mists based upon the current active game type.

## Interface: 110105
## Title: My Cool Addon

# This will load "Mainline\File.lua" or "Classic\File.lua"
# as appropriate for the current client.
[Family]\File.lua

# This will load "Standard\File.lua", "Mists\File.lua", "Cata\File.lua", ...
# as appropriate for the current client.
[Game]\File.lua

Client-specific TOC files

Addons can ship multiple .toc files with different filename suffixes tailored for individual clients.^[1] The WoW client first searches for the special file names as shown below, and if none are found, uses AddonName.toc

Note that comma-delimited interface versions or per-file conditional loading directives should be preferred over the use of client-specific TOC files where possible.

Game Type		Suffix
`standard`	The War Within excluding Plunderstorm	`AddonName_Standard.toc`
`mists`	Mists of Pandaria Classic	`AddonName_Mists.toc`
`cata`	Cataclysm Classic	`AddonName_Cata.toc`
`wrath`	Wrath of the Lich King Classic	`AddonName_Wrath.toc`
`tbc`	Burning Crusade Classic	`AddonName_TBC.toc`
`vanilla`	Classic Era	`AddonName_Vanilla.toc`
`plunderstorm`	Plunderstorm	`AddonName_WoWLabs.toc`
`mainline`	The War Within including Plunderstorm	`AddonName_Mainline.toc`
`classic`	All classic expansions	`AddonName_Classic.toc`

Clients also recognize legacy suffixes -WOTLKC and -BCC.
The _Mainline and _Classic suffixes have a lower priority than other suffixes that target specific expasions/modes. 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 clients.

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

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.

## Group: FooAuras

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

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.

## LoadWith: someAddOn, someOtherAddOn

LoadManagers

AddOns that, if present, trigger this one to behave as LoadOnDemand. See AddonLoader for an example.

## LoadManagers: someAddOn, someOtherAddOn

AllowLoadGameType

Restricts loading this addon to specific client flavors. Multiple values may be supplied, delimited by commas. Note that game modes may be restricted to disallow loading of insecure addons.

Game Type	Expansion/Mode
`standard`		The War Within excluding Plunderstorm
`mists`		Mists of Pandaria Classic
`cata`		Cataclysm Classic
`wrath`		Wrath of the Lich King Classic
`tbc`		Burning Crusade Classic
`vanilla`		Classic Era
`plunderstorm`		Plunderstorm
`mainline`		The War Within including Plunderstorm
`classic`		All classic expansions

OnlyBetaAndPTR

1 if an addon should only be loadable in Beta or PTR clients.

## OnlyBetaAndPTR: 1

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

LoadSavedVariablesFirst

1 if SavedVariables file(s) should be loaded before all script files for this addon.

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"

Uncategorized

AllowAddOnTableAccess

1 to allow the retrieval of the namespace table of this addon via C_AddOns.GetLocalAddOnTable.

## AllowAddOnTableAccess: 1

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.

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

Patch 11.1.7 (PTR): Added the AllowAddOnTableAccess field.
Patch 11.1.5 (2025-04-22): Added support for per-file directives and variables. Added the LoadSavedVariablesFirst field. AllowLoadByGameType is now usable by insecure addons.
Patch 11.1.0 (2025-02-25): Added the Category and Group fields.
Patch 11.0.0 (2024-07-23): 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 5.5.0 (Beta): Includes all changes present in patch 11.1.7.
Patch 4.4.1 (2024-10-29): Includes all changes present in patch 11.0.0.
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.

Classic Era

Patch 1.15.4 (2024-09-24): Includes all changes present in patch 11.0.0.

References

^ ^a ^b Meorawr. Multiple Interface Version Support. WoWUIBugs.

[WoWUIBug#68-1] Meorawr. Multiple Interface Version Support. WoWUIBugs.

[1]

Navigation menu

Namespaces

Views

Search

Navigation

Warcraft

World of Warcraft

Lore

Tools