Addon manifest (.txt) format

From ESOUI Wiki

Revision as of 19:37, 14 October 2018 by Decay2 (Talk | contribs)
Jump to: navigation, search


File format

Within each addon's directory, in addition to the actual Lua and XML files, there is one file that is required to be present for an addon to be recognized. The filename of this "manifest file" defines the name of the addon which is used ingame (e.g. for EVENT_ADD_ON_LOADED) and has a .txt extension. A basic version looks something like this:

## Title: Full Addon Title
## APIVersion: 100019


; this is a comment

The lines beginning with ## are called "directives" which specify metadata about the addon, lines beginning with ; are comments. The rest of the lines are simply a list of file paths relative to the addon's directory which should be loaded as part of the addon. The order of the files determines the load order of the files. Loading a file runs all the code inside it. If some code is within a function, the function will be created, but won't be run at load time unless the main chunk calls it.

Relative paths are supported within the addon's folder.


Some variable expansions are available as explained in the next section.

Variable Expansion

Variables are written as a dollar sign followed by a name in parentheses. There are currently three variables that can be used in paths.

Variable Values Description
$(language) en, de, fr, jp This substitution can be used to load a file depending on the current client language
$(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



When started on the client with API version 100012 and English client language they will point to the following files:


In case the substituted file does not exist, it will silently fail to load.



Defines the addon API version which the addon was written against. This started at 100003 at launch (with many old Addons still using this version) and was changed to 100004 with Craglorn/1.1 patch. Addons with an APIVersion that does not match the current client's API version will be disabled unless the "Allow out of date addons" box is checked in the addons window. You can find what is the current API version on the first line of this text file: ~\Documents\Elder Scrolls Online\live\AddOnSettings.txt

## APIVersion: 100010

Since Version 100015 you can specify two versions at once to make an addon load in the live and pts version of the game at the same time.

## APIVersion: 100015 100016


This optional field is used as a tie-breaker in case two addon folders contain a manifest file with the exact same name as only one of them can be loaded. Without this, the load order is determined by dependencies and the reverse alphabetic order of folder names. The value needs to be an unsigned integer. This is mostly useful for libraries which commonly get bundled with other addons. In case an author accidentally copies the manifest file, it will help to ensure that a stand-alone version of the library is preferred.

## AddOnVersion: 1


A descriptive title for the addon, displayed in the addon manager. Can contain spaces and other special characters. Length limit is 64 characters.

## Title: The title of your addon


A description of the addon, 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.


A version of the addon. Can contain numbers, characters, spaces and other special characters.

## Version: version number


An author of the addon, displayed in the addon manager. Can contain spaces and other special characters.

## Author: Author(s) name(s)


A space-separated list of names for addons which must be present and are loaded before this addon is loaded. Any dependencies are missing, the game will refuse to load this addon. Addon names are case sensitive.

## DependsOn: AddonNameYouDependOn SecondAddonNameYouDependOn


Space-separated list of addon names which, if they are present, should be loaded before this addon. The lack of an optional dependency will not prevent this addon from being loaded, however - unlike DependsOn.

## OptionalDependsOn: AddonNameYouDependOn SecondAddonNameYouDependOn


Space-separated list of names for a 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 global table. 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


Sometimes libraries or other modules get embedded into an addon. Usually they are called by the addons manifest, though they can also have their own manifest which means they run standalone and can have their own saved variables. The maximum depth that is allowed for such nested addons is 3 levels below the AddOns folder:

Elder Scrolls Online\live\AddOns
  +-- FooAddon\
        +-- FooAddon.txt
        +-- FooAddon.lua
        +-- libs\
              +-- FooLibrary\
                    +-- FooLibrary.txt
                    +-- FooLibrary.lua
Personal tools