Addon manifest (.txt) format
From ESOUI Wiki
To prevent issues, make sure the file is UTF-8 w/o BOM. UTF-8-BOM and ANSI can lead to some different issues during AddOn loading etc.. Also make sure that each line is not longer than 301 bytes. Anything that goes beyond that will be ignored by the game.
A basic manifest.txt file contains: three mandatory directives (Title:, AddonVersion:, APIVersion:); three situational directives (DependsOn:, IsLibrary: true, OptionalDependsOn:), and one ESOUI/Minion directive (Version:). It looks something like this:
## Title: Addon title, a character string for human display (e.g. SkyShards) ## Author: The author name String of the addon ## APIVersion: a six digit value, the same value as the ESO API for each release (e.g. 100026). In the same line there can be up to 2 APIVersions after another, separated by a space, to support both of them (e.g. 100026 100027 ## AddOnVersion: a positive integer value (e.g. 1,2,3,etc. but not 3.4 nor -5 nor r5) ## Version: A version identifier for ESOUI and/or Minion (e.g. 2.0.2) to separate add-on releases and/or updates ## DependsOn: A space separated name list of add-ons/libraries that your add-on needs to run correctly (e.g. LibAddonMenu-2.0 LibDialog). If any addon/library in this line is missing your adon won't load! ## OptionalDependsOn: A name list similar to DependsOn: but the add-ons in this list will not prevent your add-on from running. Use this to assure other addons listed here are loaded before your addon (e.g. AddonName1 AddonName2) ## IsLibrary: false or not present : if this add-on is not a library or support add-on; true : if this add-on is a library or support add-on # 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. Be very careful to leave a space after the trailing colon delimiter (e.g. ": "). If you don't, the game's parser will not find the directive's metadata values.
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.
A total example of an AddOn's manifest txt file could be:
## Title: MyAddon - Sample addon ## Author: Your name ## APIVersion: 100026 100027 ## AddOnVersion: 001 ## Version: 0.0.1 ## IsLibrary: false ## DependsOn: LibAddonMenu-2.0 ## OptionalDependsOn: MyOtherAddon Skyshards #Load constant values MyAddon_Constants #Load language texts depending on the client's language /lang/en.lua ; Standard language file, always loaded /lang/$(language).lua ; de.lua/fr.lua, ...: Loaded if the client is using this language #Addon base functions and code MyAddon.lua #Addon functions depending on the APIVersion of the server MyAddon_functions$(APIVersion).lua ; Will load the file MyAddon_functions100026.lua for APIversion 100026 and MyAddon_functions100028.lua for APIversion 100028 #Addon XML MyAddon_XML.lua #Keybindings /keybindings/keybindings.lua /keybindings/keybindings.xml # 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.
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. Listing the same directive multiple times will also make the game interpret it multiple times, but the results may vary depending on the type. 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 ZOS fix broken add-ons nor will it make the game 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 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 folder names 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
Starting with the Elsweyr Update (100027) the game will use this directive to identify library and support add-ons and to determine which of the two sections, Add-On or Library, to list these add-ons. You should include this directive in the manifest files for library add-ons (e.g. those add-ons catalogued and loaded by using the LibStub(r5) add-on, or intended to be a library without LibStub usage (using a global variable Lib*)) and/or support add-ons (e.g. those standalone add-ons catalogued by the game but loaded by using their own loading methodology).
## IsLibrary: true
Space-separated list of add-on folder 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 folder names 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. However, because they are global tables, their data object names are not specific to, nor are they associated with, any one particular add-on.
The first requirement is that you not duplicate the Saved Variables name of any other add-on. If you do something silly, as I did, and use the same Saved Variables name in the manifests for two different add-ons, you will quickly find confusion in that particular data object because the game will help both add-ons update the contents of that same table at random intervals with different information. May I suggest that you include the name of your add-on in every Saved Variables data object name that your add-on uses to prevent unforeseen and unplanned events from happening when you least expect them to occur.
The other requirement is that Saved Variable data objects must be created (if they don't already exist) in the EVENT_ADD_ON_LOADED event handler for your add-on; otherwise, they may not be saved properly. And as I understand it, you should not try to access the data objects any earlier either, as they 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