(Further work) Tag: WoW API docs |
m (Not case-insensitive on all file systems.) Tag: WoW API docs |
||
(20 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
{{uitech}} |
{{uitech}} |
||
− | '''.toc |
+ | '''.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 == |
== Basic rules == |
||
+ | <code>...\Interface\AddOns\MyAddon</code> must contain <code>MyAddon.toc</code> or one of the alternatives below.<ref name="WoWUIBug#68" /> |
||
− | The game client searches each subfolder of <code>__client__\Interface\AddOns\</code> (only one level deep) for .toc files having the same name as the subfolder. This .toc file has instructions of the following format: |
||
+ | {| class="darktable zebra |
||
+ | |- |
||
+ | ! Suffix !! Description |
||
+ | |- |
||
+ | | MyAddon'''-Classic'''.toc || {{wow-inline}} Classic Era |
||
+ | |- |
||
+ | | MyAddon'''-BCC'''.toc || {{bc-inline}} Burning Crusade Classic |
||
+ | |- |
||
+ | | MyAddon'''-Mainline'''.toc || Retail |
||
+ | |- |
||
+ | | MyAddon.toc || Fallback when one of the above are not found. |
||
+ | |} |
||
+ | |||
+ | The file may contain the following elements: |
||
* Metadata printed as <code>## TagName : tagValue</code>, where whitespace is trimmed (except at the start of a line) |
* Metadata printed as <code>## TagName : tagValue</code>, where whitespace is trimmed (except at the start of a line) |
||
* Comments printed as <code># this is a comment</code> ignored by the client |
* Comments printed as <code># this is a comment</code> ignored by the client |
||
* A list of files to be loaded as <code>myFile.xml</code> or <code>subfolder/anotherFile.lua</code> |
* A list of files to be loaded as <code>myFile.xml</code> or <code>subfolder/anotherFile.lua</code> |
||
− | <div style="clear:left"><!-- this example will begin below the table of contents --></div> |
||
## Interface: {{API LatestInterface}} |
## Interface: {{API LatestInterface}} |
||
## Title: Waiting for Godot |
## Title: Waiting for Godot |
||
Line 16: | Line 30: | ||
Vladimir.xml |
Vladimir.xml |
||
Estragon.lua |
Estragon.lua |
||
− | libs |
+ | libs\SomeEmbeddedLibrary.lua |
# This is a comment |
# This is a comment |
||
+ | |||
+ | When loading files present in subdirectories backslashes (<code>\</code>) should be as directory separators. This prevents issues with path resolution if a referenced file itself includes other files relative to its own directory. |
||
== File load order == |
== File load order == |
||
Line 38: | Line 54: | ||
There are a number of ways to get the current interface version: |
There are a number of ways to get the current interface version: |
||
− | :; It probably is {{API LatestInterface}}: But |
+ | :; It probably is {{API LatestInterface}} (retail) or {{API LatestInterface|classic}} (classic): But these numbers are [[Template:API LatestInterface|maintained locally]], so they ''might'' be out of date. |
:; Use {{api|GetBuildInfo}} : In particular, <code>/dump select(4, GetBuildInfo())</code> should output the correct version to your chat frame. |
:; Use {{api|GetBuildInfo}} : In particular, <code>/dump select(4, GetBuildInfo())</code> 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 tag. |
:; 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 tag. |
||
+ | Prior to [[patch 8.2.0]]: |
||
⚫ | |||
⚫ | |||
⚫ | |||
== Display in the addon list == |
== Display in the addon list == |
||
− | The following metadata change how an addon appears in the addon list |
+ | The following metadata change how an addon appears in the addon list. |
+ | |||
+ | These tags support localization, which may written by appending a hyphen and the locale code to the tag name, such as <code>Title-enGB</code>. See [[Localization]] for a full list of current locale codes. |
||
+ | |||
+ | Coloring is possible via [[UI escape sequences]] <code>|c########</code>. |
||
; Title : String - The name to display on the AddOns list (default: name of the addon's folder). |
; Title : String - The name to display on the AddOns list (default: name of the addon's folder). |
||
Line 58: | Line 79: | ||
The following metadata changes when and how an addon loads: |
The following metadata changes when and how an addon loads: |
||
− | ; RequiredDeps, Dependencies, or any word beginning with "Dep" : String - A comma |
+ | ; RequiredDeps, Dependencies, or any word beginning with "Dep" : String - A comma or space separated list of addon (directory) names that must be loaded before this addon can be loaded. <pre> ## Dependencies: someAddOn, someOtherAddOn</pre> |
− | ; OptionalDeps : String - A comma |
+ | ; OptionalDeps : String - A comma or space separated list of addon (directory) names that should be loaded before this addon if they ''can'' be loaded. <pre>## OptionalDeps: someAddOn, someOtherAddOn</pre> |
; LoadOnDemand : Number - 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.<pre>## LoadOnDemand: 1</pre> |
; LoadOnDemand : Number - 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.<pre>## LoadOnDemand: 1</pre> |
||
; LoadWith : String - A comma-separated list of addon (directory) names that, when loaded, will cause the client to load this LoadOnDemand addon as well. <pre>## LoadWith: someAddOn, someOtherAddOn</pre> |
; LoadWith : String - A comma-separated list of addon (directory) names that, when loaded, will cause the client to load this LoadOnDemand addon as well. <pre>## LoadWith: someAddOn, someOtherAddOn</pre> |
||
Line 79: | Line 100: | ||
== Notes == |
== Notes == |
||
* WoW reads up to the first 1024 characters of each line only. Additional characters are ignored and do not cause an error. |
* WoW reads up to the first 1024 characters of each line only. Additional characters are ignored and do not cause an error. |
||
− | * |
+ | * Prior to [[Patch 9.0.1/API changes|Patch 9.0.1]], the list of files may be edited while the game is open (taking effect after <code>/reload</code>), but changing metadata would have no effect and any files must have already been inside the AddOns folder. |
== Patch changes == |
== Patch changes == |
||
+ | * {{Patch 9.1.0|note=Multiple TOC files now possible using a suffix to disambiguate Classic, BCC and Retail.<ref name="WoWUIBug#68">{{Ref web|author=Meo[[File:Inv g fishingbobber 05.png|12px]]rawr|url=https://github.com/Stanzilla/WoWUIBugs/issues/68#issuecomment-830351390|title=Multiple Interface Version Support|publisher=WoWUIBugs}}</ref>}} |
||
− | {{Patch 5.4.8|note=Changes to how files load when modifying a .toc and typing /reload}} |
||
− | {{Patch |
+ | * {{Patch 9.0.1|note=[[MACRO reload|/reload]] recognizes changes to TOC metadata and entirely new files.}} |
− | {{Patch |
+ | * {{Patch 4.0.1|note=[[MACRO reload|/reload]] recognizes changes to the file order.}} |
− | {{Patch |
+ | * {{Patch 2.1.0|note=Added LoadManagers metadata}} |
+ | * {{Patch 1.11.0|note=Added Secure metadata}} |
||
+ | * {{Patch 1.9.0|note=Added LoadWidth metadata}} |
||
== See also == |
== See also == |
||
Line 91: | Line 114: | ||
* {{api|GetAddOnMetadata}} returns information listed in a specified .toc tag. |
* {{api|GetAddOnMetadata}} returns information listed in a specified .toc tag. |
||
* {{api|GetBuildInfo}} returns the client's interface version |
* {{api|GetBuildInfo}} returns the client's interface version |
||
+ | |||
+ | == References == |
||
+ | {{Reflist}} |
Revision as of 15:03, 20 May 2021
The API is no longer being updated here until further notice. |
.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
...\Interface\AddOns\MyAddon
must contain MyAddon.toc
or one of the alternatives below.[1]
Suffix | Description |
---|---|
MyAddon-Classic.toc | Classic Era |
MyAddon-BCC.toc | Burning Crusade Classic |
MyAddon-Mainline.toc | Retail |
MyAddon.toc | Fallback when one of the above are not found. |
The file may contain the following elements:
- Metadata printed as
## TagName : tagValue
, where whitespace is trimmed (except at the start of a line) - Comments printed as
# this is a comment
ignored by the client - A list of files to be loaded as
myFile.xml
orsubfolder/anotherFile.lua
## Interface: 100206 ## Title: Waiting for Godot ## Notes: Nothing to be done. ## Version: 4.2 Vladimir.xml Estragon.lua libs\SomeEmbeddedLibrary.lua # This is a comment
When loading files present in subdirectories backslashes (\
) should be as directory separators. This prevents issues with path resolution if a referenced file itself includes other files relative to its own directory.
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
- SomeEmbeddedLibrary.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: 100206
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 100206 (retail) or 11501 (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 tag.
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 typeExportInterfaceFiles code
to extract FrameXML files into World of Warcraft\BlizzardInterfaceCode. - View FrameXML.toc online
- For instance at wowcompares.
Display in the addon list
The following metadata change how an addon appears in the addon list.
These tags support localization, which may written by appending a hyphen and the locale code to the tag name, such as Title-enGB
. See Localization for a full list of current locale codes.
Coloring is possible via UI escape sequences |c########
.
- Title
- String - The name to display on the AddOns list (default: name of the addon's folder).
## Title: Waiting for Godot ## Title-frFR: En attendant Godot
- Notes
- String - The description displayed when the user hovers over the addon entry in the AddOns list.
## Notes: This word is |cFFFF0000red!
Loading conditions
The following metadata changes when and how an addon loads:
- RequiredDeps, Dependencies, or any word beginning with "Dep"
- String - A comma or space separated list of addon (directory) names that must be loaded before this addon can be loaded.
## Dependencies: someAddOn, someOtherAddOn
- OptionalDeps
- String - A comma or space separated list of addon (directory) names that should be loaded before this addon if they can be loaded.
## OptionalDeps: someAddOn, someOtherAddOn
- LoadOnDemand
- Number - 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
- LoadWith
- String - A comma-separated list of addon (directory) names that, when loaded, will cause the client to load this LoadOnDemand addon as well.
## LoadWith: someAddOn, someOtherAddOn
- LoadManagers
- String - 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. An example of a LoadManager is AddonLoader.
- SavedVariables
- String - 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
- SavedVariablesPerCharacter
- String - 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
- DefaultState
- String - 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
Informational
The following metadata do not change how an addon behaves, but may be accessed using GetAddOnMetadata:
- Author
- String - The AddOn author's name, displayed
- Version
- String - The AddOn version. Some automatic updating tools may prefer that this string begins with a numeric version number.
- X-_____
- String - Any custom metadata prefixed by "X-", such as "X-Date", "X-Website" or "X-Feedback"
Restricted
- Secure
- Number - If the value of this tag is 1 and the addon is digitally signed by Blizzard, its code is considered secure.
Notes
- WoW reads up to the first 1024 characters of each line only. Additional characters are ignored and do not cause an error.
- Prior to Patch 9.0.1, the list of files may be edited while the game is open (taking effect after
/reload
), but changing metadata would have no effect and any files must have already been inside the AddOns folder.
Patch changes
- Patch 9.1.0 (2021-06-29): Multiple TOC files now possible 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.
- 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 LoadWidth metadata
See also
- GetAddOnInfo returns basic information about an addon.
- GetAddOnMetadata returns information listed in a specified .toc tag.
- GetBuildInfo returns the client's interface version
References
- ^ a b Meorawr. Multiple Interface Version Support. WoWUIBugs.