Addon manifest (.txt) format
From ESOUI Wiki
A basic manifest.txt file contains: three mandatory directives (Title:, AddonVersion:, APIVersion:); two situational directives (DependsOn:, OptionalDependsOn:), and one ESOUI/Minion directive (Version:). It looks something like this:
## Title: Addon Title, a character string for human display (e.g. SkyShards) ## AddOnVersion: a positive integer value (e.g. 1,2,3,etc. but not 3.4 nor -5 nor r5) ## APIVersion: a six digit value, the same value as the ESO API for each release (e.g. 100026) ## DependsOn: A space separated name list of add-ons that your add-on needs to run correctly (e.g. LibStub LibAddonMenu-2.0) ## OptionalDependsOn: A name list similar to DependsOn: but the add-ons in this list will not prevent your add-on from running ## Version: A version identifier for ESOUI and/or Minion (e.g. 2.0.2) to separate add-on releases and/or updates # blank lines are ignored # both '#' and ';' are comment characters ; the double hashmarks ('##') above are parts of the "metadata" definitions for the manifest file. You must include the '##' for a ; directive to be recognized, and you cannot have whitespace in front of them # lua files for the addon, which can come before or after XML files SomeAddonFile.lua # you can have internal folders; paths are relative to the manifest file InternalPath\whatever.lua # you can use the forward slash ('/') as a path separator too ForwardSlashPath/AlsoWorks.lua # XML files follow the same rules as the lua files, regarding folders SomeAddon/InterfaceFile.xml # Most people also include the ZOS mandated licensing boilerplate in the manifest though you are welcome to include it in any way # that meets the definition set here: [https://account.elderscrollsonline.com/add-on-terms] # The suggested disclosure is: # This Add-on is not created by, affiliated with, or sponsored by, ZeniMax Media Inc. or its affiliates. # The Elder Scrolls® and related logos are registered trademarks or trademarks of ZeniMax Media Inc. in the United States # and/or other countries. All rights reserved.
Lines beginning with two hashmarks
## define the metadata of the addon, and are often referred to as "directives". Directives specify information and metadata about the add-on. Each directive and its values are explained in the next paragraphs; one paragraph per directive.
Lines beginning with a semi-colon (
;) or hashmark (
#) are comments. ESO restricts comment lines to 1024 characters per line. Comment lines can contain any characters including hashmarks. Comments terminate at the next newline.
The rest of the lines in a manifest are simply a list of relative folder and file paths that should be loaded as part of the add-on. Relative file paths can look like this:
Or like this:
ESO loads the files in the same order in which they are listed in the manifest. Loading a .lua file executes all the code within it except for the code snippets contained within functions. The functions are created, but none of the code within them gets executed until another code snippet outside of the function invokes it.
Variables are written as a dollar sign followed by a name in parentheses. There are currently three variables that can be used in paths.
|$(language)||en, de, fr, jp||This substitution can be used to load a file depending on the current client language. Be sure to load 1 file with the "base localized strings" before loading the other language files, so there is always a kind of "fallback" available.|
|$(languageDirectory)||?||Not confirmed what it does, but my guess is it expands to the $(language) followed by a slash|
|$(APIVersion)||100011, 100012||With this variable a file can be loaded based on the API version of the game client. Useful to stay compatible with both versions when a major update is coming|
localization/$(language).lua misc_$(APIVersion)/window.xml start$(APIVersion).lua
When started on the client with API version 100012 and English client language they will point to the following files:
localization/en.lua misc_100012/window.xml start100012.lua
In case the substituted file does not exist, it will silently fail to load.
Some manifest directives are present because they document add-on information (e.g.
Version:). Other directives contain values, folder names, or metadata that ESO must have to load an addon, its libraries, and/or its dependencies correctly. All directive names are case sensitive and must be entered exactly as they are listed. Valid directives, their descriptions, and values are listed here in alphabetical order.
ESO added the
AddOnVersion: directive to support its own internal addon versioning by using the value in this directive to determine which of two identical addon, library, or dependency folders was newer; your addon folder (or a folder that is nested within your addon folder) or the folder that ESO keeps within its internal catalog.
When this directive or its manifest file is missing, the ESO loader loads addons, libraries, and dependencies, in the order listed in the dependency directives first, followed by the nested folders and/or folder directories addon files in reverse alphabetic order of folder names.
## AddOnVersion: 1
This directive is most useful for libraries which commonly get bundled with other addons but it is also necessary for any stand-alone addon. Should the author accidentally copy the manifest file, this directive will help to ensure that a stand-alone version of the library is preferred. Its value should be a positive integer because ESO uses the C language (atoi) function to perform the numeric conversion.
Note: The text to numeric value conversion (C-language atoi) actually only reads characters up to the first non digit value, so 3.1 or 3bA would both be read as 3, so they would be preferred over 2. However 3.1 and 3.2 would both be resolved to 3 which means the version that is touched first, would be loaded.
Defines the ESO API version whose function calls were used to create this add-on. This convention started at the ESO launch with API 100003. Many old Addons are still using this version. The first APIVersion change to 100004 occurred when ZOS released the Craglorn/1.1 patch. You can find the current APIVersion on the first line of this text file:
~\Documents\Elder Scrolls Online\live\AddOnSettings.txt
## APIVersion: 100010
ESO changed the APIVersion directive in APIVersion 100015 to permit the metadata to contain two, six-digit, unsigned integer, values. ZOS made this enhancement so developers (and users) could load and test the same add-on code changes in both game environments (Live and PTS).
## APIVersion: 100015 100016
Currently, the ESO addon loader disables and refuses to load any add-on, library, or dependency whose an APIVersion does not match the current ESO APIVersion. The most common work-around for APIVersion errors is for users (and developers) to check the "Allow add-ons of other client versions" box in the Addons display window. Checking this box will let you run add-ons tested with another (i.e. older) APIVersion, but checking this box will not make ESO fix broken add-ons nor will it make ESO check for broken add-ons.
An author or list of authors of this addon, to be displayed in the addon manager. Can contain spaces and other special characters.
## Author: Author(s) name(s)
Some authors have opted to list other contributors not as part of the authors list, but still add them to the manifest. There are no official directives for this, but some commonly used ones are "Contributors:" or "Credits:".
A space-separated list of subordinate add-on folder names which must be loaded before this add-on is loaded. Add-on folder names are case sensitive. If a dependency name is missing from either the ESO add-ons catalog or from the content of this add-on folder, ESO will refuse to load this add-on.
## DependsOn: AddonNameYouDependOn SecondAddonNameYouDependOn
Note: ESO has been checking add-on folders for subordinate folders that are also listed in the mandatory or optional dependency directives. You should not load subordinate library or dependency add-ons yourself from within the text area of your manifest file; either let ESO find the dependency or, if you must load a dependency yourself, add its folder to those in your ESO "Addons" directory.
A description of the addon that will be displayed in the tooltip for the addon in the addons window list. Can contain spaces and other special characters.
## Description: A long description of what your addon does.
Starting with the Murkmire Update (100025) the game periodically writes the saved variables for each loaded add-on to disk. It will attempt to write data during regular gameplay, as long as the resulting file is not bigger than 50kB and the write can be done within 4ms. Otherwise it will wait for the next loading screen. It will always wait at least two seconds between writing data to disk and 15 minutes before saving the same file again. When the DisableSavedVariablesAutoSaving is set to "1", it won't consider the saved variables of this add-on for autosaving.
## DisableSavedVariablesAutoSaving: 0
Space-separated list of add-on names which, if they are present, should be loaded before this add-on; however, unlike DependsOn, a missing, optional dependency will not prevent this add-on from being loaded.
## OptionalDependsOn: AddonNameYouDependOn SecondAddonNameYouDependOn
Note: ESO has been checking add-on folders for additional dependency folders that are also listed in the mandatory or optional dependency directives. This change means that you should not load dependency add-ons yourself from the text area of your add-on's manifest file; either let ESO find the dependency or, if you must load a dependency yourself, add its folder to those in your ESO "Addons" directory.
Space-separated list of names for data objects that will be persisted to disk in between UI loads, allowing you to save data that isn't reset when the user logs out or reloads the UI. Usually accessed via
ZO_SavedVars, but in essence it's just a series of global tables. The only requirement is that it must be created (if it doesn't already exist) in your addon's EVENT_ADD_ON_LOADED handler, otherwise it won't be properly saved. And as I understand it, don't try to access it earlier, it might not be loaded yet.
## SavedVariables: ReferenceToYourSavedVars ReferenceToYourOtherSavedVars
A descriptive title for the addon, displayed in the addon manager. It can contain spaces and other special characters. Its length is limited to 64 characters.
## Title: The title of your addon
Usually the content of this field matches the add-on folder and manifest file names selected for this add-on.
Documents this addon's version identification. The content can be numbers, characters, spaces and other special characters. This is not an official directive but it should be present for the ESOUI addon manager, Minion.
## Version: version identifier