Addon manifest (.txt) format

From ESOUI Wiki

Jump to: navigation, search

Contents

Example

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:

# both '#' and ';' are comment characters
; the '##' ahead is part of the "metadata" definition for the manifest file,
; and you must include them for the field to be recognised; you cannot have
; whitespace in front of them

## Title: Addon Title, a string for human display (e.g. SkyShards)
## AddOnVersion: Positive Integer (e.g. 1,2,3,etc. but not 3.4 or -5)
## APIVersion: Six digit, the same value as the ESO API for each release (e.g. 100026)
## DependsOn: Space separated names of all addon dependencies of this addon (e.g. LibStub LibAddonMenu-2.0)
## OptionalDependsOn: As with DependsOn, but it will not prevent loading if the addon is missing.
## Version: Unique Identifier for ESOUI and/or Minion (e.g. 2.0.2)

# blank lines are simply ignored

# 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
SomeAddonInterfaceFile.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
# out here: [https://account.elderscrollsonline.com/add-on-terms]

# The current 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 addon. Each directive and its values are explained in the next paragraphs; one paragraph per directive.

Lines beginning with a semi-colon (;) or hash (#) 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 addon. Relative file paths can look like this:

Dir/SomeLuaFile.lua
Dir/SomeFolder/SomeLuaFile.lua

Or like this:

SomeLuaFile.lua
SomeFolder/SomeLuaFile.lua

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.

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. 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

Examples

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.

Directives

Some manifest directives are present because they document add-on information (e.g. Author:, Contributors:, Credits:, 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.

AddOnVersion

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.

APIVersion

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.

Author

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".

DependsOn

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. When ESO finds one, ESO is loading either the folder content (if the folder content is newer) or the ESO catalog content (if the folder is older or out-of-date). You should not load subordinate library or dependency add-ons yourself from the text area of your add-on manifest file.

Description

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.

DisableSavedVariablesAutoSaving

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: 1

OptionalDependsOn

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

## OptionalDependsOn: AddonNameYouDependOn SecondAddonNameYouDependOn

Note: ESO has been checking addon folders for additional dependency folders that are also listed in the mandatory or optional dependency directives. When ESO finds one, ESO is loading either the folder content (if the folder content is newer) or the ESO catalog content (if the folder is older or out-of-date). This change means that you should not load dependency addons yourself from the text area of your addon's manifest file. All you need do is to include dependency addon folder names within the same .zip file as your addon's files. If the dependency addon folders contain the proper code and manifest content (.lua and .txt files), ESO will take care of the rest.

SavedVariables

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

Title

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.

Version

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
Personal tools
Namespaces
Variants
Actions
Menu
Wiki
Toolbox