AddonScript

The official AddonScript specification is available in the master branch of the addonscript-spec repository and on spec.addonscript.org.

What is AddonScript?

AddonScript is a format to distribute Minecraft addons. An addon could be anything, which is installed into the Minecraft game, like a mod, modpack, modloader, texturepack or even a world. AddonScript can be used for example to define how addons are installed, or to specify dependencies for addons. This way, addon creators just have to publish the AddonScript file for their addon and let AddonScript compatible tools (for example launchers) install them.

The values of AddonScript

Open

AddonScript can be used by everyone. There is no company or economic interest behind AddonScript. It is intended to be an open standard, which can be implemented by anyone who likes to. Anyone can contribute ideas to the AddonScript specification.

Independent

AddonScript depends on nothing, except Minecraft itself (and Java). This means that the specification does not depend on existing APIs and formats like Curseforge. It also does not reference any specific modloader like Forge or Fabric, instead they are themselves addons, which can be defined using AddonScript. This means, that AddonScript is not bound to a specific set of modloaders, instead you can use any modloader.

Universal

AddonScript is not bound to any specific use case like just for modpacks or just for mods. Instead it is considered to be a universal format, which can handle anything, that is installed into the Minecraft game. AddonScript can handle modloaders, mods, modpacks, texturepacks and even worlds and maybe other things as well.

The AddonScript API

The Index Endpoint

GET {base URL}

The index endpoint can be used to get basic information about which API versions an API instance implements. The response object of this endpoint contains a versions property, which is an array containing all API versions available on this instance.

Example response body:

{
    "versions": ["v2"]
}

GET {base URL}/{API version}

Each API version also has an index endpoint with information specifically about that version. The response of that index MAY differ across different API versions. If an API version is not implemented on an instance, the corresponding index endpoint MUST return a 400 Bad Request or 404 Not Found status code.

API Version v2:

This version of the AddonScript specification only specifies API version v2, which is currently the only existing version.

GET {base URL}/v2

The v2 version index endpoint can be used to retrieve the API features supported by this API instance on version v2. The response object of this endpint contains a features property, which is an array containing all API features supported on this instance. It also contains a manifest_version property, which is the latest manifest version available on this API instance. This version MUST be part of AddonScript major version 2. The manifest version of all manifests (and other objects using the manifest version), returned by enpoints of this API version on this instance, MUST be equal or less than this property, but MUST also be part of AddonScript major version 2 (manifest version must be greater or equal to 2). If a client does not support the manifest version returned by this endpoint, it SHOULD try to request addons from other API instances, as this instance MAY return manifests which are unsupported by the client.

Example response body:

{
    "features": ["addons", "env", "com.example.customfeature"],
    "manifest_version": 2
}

Features

API features can be either part of the specification itself or are specified by third parties. Third-party API features SHOULD be in a namespace-like format (reversed domain name).

These API features are part of the AddonScript specification itself:

addons: Addon repository
files: File repository
builder: Environment builder

Addon repository

Endpoints

Get addon

GET {base URL}/v2/addons/:namespace/:addon

This endpoint can be used to retrieve information about a specific addon, including metadata, all available versions and the canonical namespace of the addon.

Path variales:

namespace: The namespace of a repository which contains the addon
addon: The ID of the addon

Responses:

200 OK: The addon is available on this API instance. The response body MUST be an API Addon Object.
404 Not Found: The addon is not available on this API instance.

Get addon manifest

GET {base URL}/v2/addons/:namespace/:addon/:version

This endpoint can be used to retrieve the manifest of a specific version of an addon.

Path variables:

namespace: The namespace of a repository which contains the addon
addon: The ID of the addon
version: The version number of the requested version

Responses:

200 OK: This version of the addon is available on this API instance. The response body MUST be an Addon Manifest.
404 Not Found: This version of the addon is not available on this API instance.

File Repository

Endpoints

Get a file by identifier

GET {base URL}/v2/files/:namespace/:addon/:version/:qualifier

This endpoint can be used to retrieve information about a specific file. If the instance don't know this file, it MUST respond with status code 404.

Path variables:

namespace: The canonical namespace of the addon to which the file belongs to
addon: The addon ID of the addon to which the file belongs to
version: The addon version to which the file belongs to
qualifier: The qualifier of the file

Responses:

200 OK: The file is available in this file repository. The response body MUST be an API File Object.
404 Not Found: The file is not available in this file repository.

Get a file by hash

GET {base URL}/v2/files/:algorithm/:hash

This endpoint can be used to retrieve information about a file from the hash value of the file. If the instance can't find the file by the hash or does not know the specified hash algorithm, it MUST respond with status code 404.

Path variables:

algorithm: The hash algorithm of the hash
hash: The hash value of the file

Responses:

200 OK: The file is available in this file repository. The response body MUST be an API File Object.
404 Not Found: The file is either not available in this file repository or the hash algorithm is unknown to the API instance.

Environment builder

Endpoints

Build launch environment

POST {base URL}/v2/builder

This endpoint can be used to build the launch environment for an instance addon.

If an instance addon, which has to provide a launch configuration, has use_builder set to true, AddonScript will send a request to this endpoint of an API instance, on which the repository of the namespace of this addon can be found. This request contains information about the AddonScript schema version, which will be used in the request and about which addon this request is for. Moreover it contains for both sides a list of addons, including their version, which will be part of the addon in this environment on that side. The manifest of this addon uses the expected relation flag to tell AddonScript, which related addons MAY and which MUST be requested on this endpoint and which versions of them are valid. Which exact version of them and which optional addons will be requested is either decided by the user, if the instance addon is installed manually, or by another instance addon, which inherits the launch configuration from this addon. In later case, that instance addon uses the env relation flag to specify an exact version for each addon, that will be requested. Each required expected addon MUST be covered this way while only those optional expected addons will be requested, which are covered this way. Lastly the request also contains for each side a list of all related addons of this one, which are or will be installed into this instance, including their version. This does not include relations with the expected relation flag.

Since the API instance MAY download files or build/compile things to build the launch environment, this request MAY take some time so the client implementation SHOULD set the request timeout for this endpoint rather high. It is RECOMMENDED to have a timeout of at least 5 minutes, better about 10 minutes.

After the launch environment was build by the API instance, this endpoint will respond with a list of file objects, the AddonScript schema version for the response and the launch configuration for this addon. These files MUST be considered to be part of the files of the addon, from which the request was send and can then be installed. The launch configuration will override the entirely.

Request Body:

The request body MUST be an Environment Builder Request Object.

Responses:

200 OK: The launch environment was successfully build. The response body MUST be an Environment Builder Response Object.
400 Bad Request: The server was not able to build the launch environment because of invalid information send by the client. The client SHOULD NOT try this request on another API instance, since the request is invalid.
404 Not Found: The launch environment can't be build for this addon, because no information about it was found on this API instance. The client SHOULD try to use another API instance to build the environment.
500 Internal Server Error: The server was not able to build the launch environment because of an internal error. The client MAY try to request the environment on another API instance.

Addon Manifest Object

{
  "addonscript": {},
  "id": "myaddon",
  "namespace": "com.example",
  "version": "1.0.0",
  "files": [],
  "relations": [],
  "flags": {},
  "repositories": [],
  "instance": false,
  "use_builder": false,
  "patches": [],
  "meta": {}
}

Required properties

addonscript

This is an AddonScript object containing information about the version of AddonScript used in this file.

id

This is the ID of the addon.

It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the kebab-case format.

version

This is the AddonScript version number of this version.

namespace

This is the canonical namespace of the addon.

flags

This is an flags object which contains manifest flags for both sides for this manifest.

Optional properties

files

This is an array of file objects including the files belonging to this addon.

relations

This is an array of relation objects which represent addons in relation to this one.

repositories

This is an array of repository objects. Each repository object defines one repository from which files or addons can be retrieved. Each AddonScript manifest SHOULD have a repository for the canonical namespace of that manifest, from which AddonScript implementations MAY check for updates for this addon. If use_builder is true, this addon MUST have such a repository to provide API instances, which can be used to request the launch environment.

instance

This is a boolean which specifies, if this addon is an instance addon. If this property is not present, it defaults to false.

use_builder

This is a boolean which specifies, if this addon will use the environment builder. Only valid if instance is true. If this property is not present, it defaults to false. (DEPRECATED)

patches

This is an array of patch object which can be used to modify t he launch configuration of this instance. Only available for instance addons.

meta

This is a meta object containing metadata about the addon.

AddonScript Object

{
  "version": 2
}

Future fields may be added.

Required properties

version

This is the version of the addonscript format the file is written in.

The specification you are reading is for version 2. Version 1 is an old version which is deprecated, and doesn't have to be (and shouldn't be) implemented by tools using addonscript.

File Object

{
  "qualifier": "modfile",
  "link": ["https://example.com/mymod.jar", "./mymod.jar"],
  "flags": {},
  "install": [],
  "hashes": {
    "sha1": "somesha1checksum"
  },
  "meta": {}
}

Required properties

qualifier

This is the qualifier of this file. It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the kebab-case format. The qualifier has to be unique to this addon version. The namespace, addon ID, version and qualifier can together be used to uniquely identify a file.

link

This is an array of links, which are pointing to the actual file. All of these links must have the same file type. Since AddonScript treats directories and zip files equally, they can be mixed in the same link array. When downloading the file, the first link in this array SHOULD be used with the other links as fallback, if the first doesn't work. If none of the specified links works or the array is empty, the file link SHOULD be retrieved by it's identifier from one of the repositories, but only, if a sha1 hash is specified, so that it can be verified, that the downloaded file is correct.

Optional properties

install

This is an array of install objects. They describe how the file will be installed to the game. The order in the array corresponds to the order in which the installation steps will be applied.

flags

This is an flags object which contains relational flags for both sides for this file. If a file has no flag for a side, the file will be ignored for that side.

hashes

This is an object with checksums for this file. The object contains key-value-pairs where the key is the hash algorithm and the value is the checksum.

Supported hash algorithms:

sha1

meta

This is a meta object containing metadata about the file. it SHOULD only contain additional metadata.

Install Object

{
  "action": "move",
  "args": ["./mods"],
  "side": "both"
}

Required properties

action

This is the install action, which will be used at this installation step.

Optional properties

args

This is an array of arguments for the install action. Each of them takes other arguments.

side

This specifies, for which side this install action should be performed. Valid values are client, server and both. If this property is not present, it defaults to both.

Relation Object

{
  "id": "othermod",
  "namespace": "com.example",
  "version": "[1.0]",
  "repositories": ["repo1"],
  "flags": {}
}

Required properties

id

This is the ID of the addon this relation refers to.

version

This is an AddonScript version range that specifies, which versions of the related addon are targeted by this relation.

Optional properties

namespace

This is the canonical namespace of the related addon. If this property is not set, AddonScript will resolve the namespace via the addon endpoint of a repository.

repositories

This is an array of repository namespaces. These are the repositories, from which AddonScript will try to get this relation from, in the order as they are specified in the array. If this property is not set or the array is empty, AddonScript will try to resolve the relation from the repository described by the manifest namespace. The repository described the the canonical namespace of this relation has always precedence before these repositories.

flags

This is an flags object which contains relational flags for both sides for this relation. If a relation has no flag for a side, the relation will be ignored for that side. This behavior is different from the incompatible flag, since the related addon can still be installed on that side without any conflict.

Flags object

{
    "client": ["optional"],
    "server": ["required"],
    "both": ["included"]
}

Optional properties

client

This is an array of flags which only apply on the client side.

server

This is an array of flags which only apply on the server side.

both

This is an array of flags which apply on both sides. AddonScript will treat each flag in this array as if it was in the client array and the server array.

Repository Object

{
  "namespace": "net.addonscript",
  "instances": ["https://api.addonscript.net"]
}

Required properties

namespace

This is the namespace, which describes this repository.

instances

This is an array of base URLs of AddonScript API instances, on which this repository can be found. To get an addon from this repository, AddonScript will try to get it from the addon endpoint of these API instances in the order, in which they are specified in this array. Instances in this array with the builder feature will be used by AddonScript, to request the launch environment for an addon with a canonical namespace equal to the namespace of this repository. The first API instance with the builder feature will be used in this case with the others as fallback.

Meta Object

{
  "addon": {
    "name": "My cool addon name",
    "icon": "./icon.png",
    "description": "./README.md",
    "summary": "My Addon",
    "website": "https://example.com",
    "source": "https://gitea.com/user/myaddon",
    "issues": "https://gitea.com/user/myaddon/issues",
    "type": "mod",
    "contributors": [{"name": "Alice", "email": "[email protected]"}, {"name": "Bob", "email": "[email protected]"}]
  },
  "version": {
    "changelog": "./CHANGELOG.md",
    "timestamp": 1594753200
  },
  "additional": {}
}

Optional properties

addon

An addon mata object.

version

A version mata object.

additional

This object can contain any arbitrary data,

Addon Meta Object

Optional Properties

name

The full, human-readable name of the addon. This is what a program such as a launcher SHOULD display to the user.

icon

A link to the icon of the addon. This path SHOULD point to an image file of small resolution which is ideally square. It MAY be dispayed to users in programs.

description

A link to a description file for the addon. The file SHOULD be in CommonMark markdown.

summary

A short description of the addon, to be shown in lists and menus where the addon is shown aside others.

website

A URL to a website about the addon

source

A URL to the source code of the addon.

issues

A URL to an issue tracker for the addon.

type

The type of the addon, for example mod, modpack or resourcepack.

contributors

An array of people who have contributed to the addon. Each contributor is represented by an object, which MUST have a name and a email property.

Version Meta Object

Optional properties

changelog

A link to a changelog file for the addon.

timestamp

A unix timestamp of the time and date of the version's release.

Launch Patch Object

{
    "side": "client",
    "main_class": "com.example.SomeClass",
    "arguments": [],
    "jvm_arguments": ["-Djvmargument"],
    "replace_jvm_arguments": false,
    "java_version": 8
}

Required properties

side

This specifies, for which side this patch should be applied. Valid values are client, server and both.

Optional properties

main_class

This is the main class for this instance, which will be used to launch the game. It will override any main class from other patches for this side. Setting this to an empty string will indicate, that the main class specified in of manifest of the main jar file should be used.

arguments

This is an array of game argument objects, which will be used to launch the instance in addition to arguments from other patches.

jvm_arguments

This is an array of JVM arguments, which will be used to launch the instance in addition to inherited JVM arguments. They will be appended after JVM arguments from other patches.

replace_jvm_arguments

This is a boolean which indicates, if the JVM arguments from this patch should replace all other JVM arguments from other patches instead of appending them. Defaults to false.

java_version

This is the recommended major Java version for this instance. It MAY work on other Java versions, but there is no guarantee for that. This overrides java_version settings from other patches.

Game Argument Object

{
    "mode": "replace", //replace, append, expand, override
    "key": "tweakerClass",
    "value": "net.anvilcraft.SomeTweaker",
    "raw": "--some ArguemtnString"
}

Required properties

mode

This is the mode, which defines how the argument is added to the other arguments. Possible values are:

replace Removes all arguments with the same key as this one and adds this argument instead. Prevents other arguments with the same key to be added laster, except they are also using the replace mode. Requires key to be set.
append Appends the argument to the previous ones.
expand Appends the argument to the previous ones, if none with the same key was already added. Requires key to be set.
override Overrides all previous arguments with those specified in raw Requires raw to be set.

Optional properties

key

This is the key of the argument, which MUST be a string. If used together with value the resulting game argument will be in the form --<key> <value>. If raw is not set, this property is required.

value

This is the value of the argument, which MUST be a string. It is used together with key to generate the resulting game argument. Defaults to an empty string.

raw

This is a string, which can override the resulting game argument. If this is set, the resulting game argument will be equal to this string instead of the generated argument. key MAY still be used in conjunction with this and MUST be considered by the mode.

API Addon Object

{
    "id": "myaddon",
    "namespace": "com.example",
    "meta": {
        "addon": {},
        "additional": {}
    },
    "versions": [
        "1.0"
    ]
}

Required properties

id

This is the ID of the addon.

It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the kebab-case format.

namespace

This is the canonical namespace of the addon.

versions

This is an array of all version numbers of this addon, which are available on this API instance.

Optional properties

meta

This is a meta object containing metadata about the addon. It does not contain any version specific metadata.

API File Object

{
    "link": ["https://example.com/file.jar"],
    "hashes": {
        "sha1": "somesha1checksum"
    },
    "meta": {
        "additional": {}
    }
}

Required properties

link

This is an array of links, which are pointing to the actual file. These MUST be a http(s) links. All of these links MUST have the same file type.

Optional properties

hashes

This is an object with checksums for this file. The object contains key-value-pairs where the key is the hash algorithm and the value is the checksum.

Supported hash algorithms:

sha1

meta

This is a meta object containing metadata about the file. it SHOULD only contain additional metadata.

Environment Builder Request Object

{
    "addonscript": {},
    "addon": {},
    "client": {},
    "server": {}
}

Required properties

addonscript

This is an AddonScript object containing information about the version of AddonScript used in this request. It SHOULD be equal to the addonscript Property of the manifest from which the request was send.

addon

This is an addon descriptor object, which contains the addon ID, canonical namespace and version of the addon, for which the launch environment will be build.

Optional properties

client

This is an environment object containing information about the client environment.

server

This is an environment object containing information about the server environment.

Environment Object

{
    "requested": [],
    "provided": []
}

Optional properties

requested

This is an array of addon descriptor objects which contains all addons, that will be part of the launch environment, including their version.

provided

This is an array of addon descriptor objects which contains all addons from the relations of the addon, from which the request was send, that will be installed in the instance, including their version

Addon Descriptor Object

{
    "id": "addonid",
    "namespace": "com.example",
    "version": "1.0.0"
}

Required properties

id

This is the ID of the addon which this object describes.

namespace

This is the namespace of the addon which this object describes. It MUST be the canonical namespace.

version

This is the version of the addon.

Environment Builder Response Object

{
    "addonscript": {},
    "files": [],
    "launch_client": {},
    "launch_server": {},
}

Required properties

addonscript

This is an AddonScript object containing information about the version of AddonScript used in this response. It MUST be equal to the addonscript Property of the request.

files

This is an array of File objects. These files will be concidered to be files of the addon, for which the launch environment was build, and MUST be treated equal to the files in the manifest.

Optional properties

launch_client

This is a Launch Config object for the client, which can be used, to modify the launch configuration of the instance.

launch_server

This is a Launch Config object for the server, which can be used, to modify the launch configuration of the instance.

Minecraft

Minecraft itself can be used as a relation in AddonScript manifests. This way addons MAY define, with which versions of Minecraft they are compatible. Instances MUST be based on a Minecraft version. Instance addons MAY apply patches to the Minecraft version of the instance. The version of Minecraft, which will be used, MUST be defined by the instance addon by using the required relational flag with either an exact version or a version range, in which case the user SHOULD be asked to select a version, which fulfills all version restrictions in the instance. There is no AddonScript manifest for Minecraft, AddonScript implementations MUST know the ID and namespace of Minecraft and how to handle it as specified below.

ID and Namespace

The addon ID of Minecraft, which will be used for relations is minecraft and the namespace is net.minecraft.

Versions

The AddonScript version number of a Minecraft version is equal to the version ID from the piston-meta API of Mojang and the official version manifests used by the Minecraft launcher, except for the difference that characters, which are invalid in AddonScript versioning (whitespace and non-ASCII characters), will be replaced with an underscore (_).

Release

Release versions of Minecraft are SemVer compatible. Addons, which only use release versions as relations SHOULD use SemVer version ranges instead of Maven version ranges. Release versions are correctly ordered according to both, SemVer and Maven.

Alpha and Beta

Alpha and beta versions are all Minecraft versions before the initial release 1.0. They are not SemVer compatible. Most alpha and beta versions are correctly ordered according to Maven, except for some early alpha versions. AddonScript implementations SHOULD be careful when ordering alpha versions and SHOULD rather trust the information from piston-meta than the Maven order.

Snapshot

Snapshot versions are mostly neither SemVer compatible nor do they fit into Maven version ordering. AddonScript implementations SHOULD use piston-meta to order snapshot versions. When installing an addon into an instace, which is based on a snapshot version, AddonScript implementations SHOULD NOT trust the version range for Minecraft of that addon, as it might be incorrect due to version ordering. Instead the user SHOULD be asked, if the installation should be proceeded, and warned about possible incompatibilities.

Launch configuration

AddonScript implementations, which are meant to install or launch AddonScript instances MUST know the launch configuration for Minecraft itself. For the server side, the launch configuration only consists of the server jar as the main jar, which already includes the required libraries and a manifest with the main class. For the client side the launch configuration SHOULD be retrieved from the piston-meta API in form of the version manifest. This manifest includes information about the main jar, the main class, all required libraries and launch arguments. In contrast to patches done by instance addons, arguments in the version manifest can include variables, which MUST be replaced with the correct values when launching the game and both, libraries and arguments, can be operating system or architecture specific, which MUST also be considered by implementations. Moreover it also provides an asset index, which SHOULD be used by implementations to retrieve game assets (if they are not already cached).

File installing

Install actions

move

args:

<location>

move moves the file to the given location.

extract

args:

<location>

extract can be used with zip files, to extract the contents of the zip file to the given location.

rename

args:

<new name>

rename renames the file to the new given filename.

library

args:

<namespace>
<name>
<version>

library can be used with jar files, to add them to the classpath of the game. If a library with the same <namespace> and <name>, as specified in the arguments of this action, was already added to the classpath, it will be replaced by this one. This install action can only be used by instance addons.

inject

inject can be used with zip or jar files, to inject the contents of that file into the server launch jar on server side or into the client jar on client side. In contrast to libraries, inject will not add just that file to the classpath, but will also overwrite classes, which are already contained in the game jar, if they are also in injected file. This install action can only be used by instance addons.

Locations

Locations are specified as a relative path from the Minecraft directory to which the file will be installed. For example ./mods would point to the mods directory of the Minecraft instance.

Directories

If the file is a directory, then it is treated like a zip file, which means, that you can move and rename it like a normal file, but also use the extract install action to move all contents of the directory to the specified location.

Flags

Flags are side-specific information about a manifest, file or relation. There are two types of flags: manifest flags and relational flags. Manifest flags provide information about an addon manifest, including for which side it is available and for which side it is an instance addon. Relational flags provide information about how a file or relation is related to the addon.

Manifest flags

required This flag specifies, that the addon of the manifest is required on the side which has this flag set, meaning, that if the other side has this addon installed, this side also required this addon to be compatible. If the other side has the incompatible flag set, this flags behaves exactly like the optional flag, but required is the prefered flag in this case.
optional This flag specifies, that the addon of the manifest is optional on the side which has the flag set, meaning, that this addon is not required on this side to be compatible, even if the other side has this addon installed.
incompatible This flag specifies, that the manifest is not compatible with the side which has this flag set. If a side has this flag, this side will completly be ignored for the manifest.

Relational flags

required This flag specifies, that the related addon or file is required for the addon. If the addon gets installed, then any relation or file, which has this flag set, also has to be installed.
optional This flag specifies, that the related addon or file is optional for this addon. If the addon gets installed, the user SHOULD be able to choose, whether he wants to install the relation or file with this flag, or not.
included This flag is only valid for relations. It specifies, that the related addon is included in this one. This also means, that if some addon requires the related addon, it can also be installed with this addon instead. Relations with this flag MUST have an exact version specified, a version range, which includes multiple versions is not allowed. If this flag is used together with required or optional, the files of the related addon will be installed like if the relation wouldn't have this flag, transistive relations will however be ignored since AddonScript assumes, that they are already covered by this addon.
incompatible This flag specifies for a relation, that the related addon is incompatible to this one, which means, that they can't be installed together in the same instance. For a file this flag specifies, that the file can't be installed on the side which has this flag set.
launch This flag is only valid for relations and files of instance addons. For relations, it specifies, that the launch patches from the related addon (which MUST also be an instance addon) will also be applied for this addon, including those inherited by other addons using the patch flag or the launch flag. This flag will also inherit the main file of the relation, if it has any. launch only applies for one relation. If multiple relations have the launch flag, it only applies for the first of them, which will be installed in the instance. For files, it specifies, that the file will be the main jar for this instance. launch only applies for one file. If multiple files have the launch flag, it only applies for the first of them, which will be installed in the instance.
env (DEPRECATED) This flag is only valid for relations of instance addons. An addon, that is inheriting the launch configuration from one, which uses the environment builder, uses this flag to tell AddonScript, which version of the expected addons will be requested for the environment by setting an exact version for the relation. It also tells AddonScript, which optional expected addons will be part of the environment and which not.
expected (DEPRECATED) This flag is only valid for relations of instance addons, which use the environment builder. This flag speficies, that this addon expects the related addon to be requested as a part of the launch environment. It is used together with the required or optional flag to specify, which addons are required for the launch environment, which are optional and which versions of them are valid. If an addon, which uses the environment builder, gets manually installed, meaning not as a dependency, the user SHOULD be asked, which optional expected addons and which version of each expected addon will be requested.
patch This flag is only valid for relations of instance addons. It specifies, that the launch patches from the related addon (which MUST also be an instance addon) will be also be applied for this addon. This flag is not transistive, patch flags of the related addon will be ignored. If used in conjunction with optional, this flag will only take effect, if the relation will be installed.

Instance addons

Instance addons represent instances of Minecraft itself, while non-instance addons have to be installed into an existing instance of Minecraft. An instance addon MAY have launch patches for each side by applying launch patches of other instance addons using the patch flag or by patching the Minecraft launch configuration directly using a launch patch object. Moreover they MAY override the main jar file using the launch flag or inherit the launch configuration, including main jar overrides and patches, from another instance addon using the the launch flag. The launch flag is recursive which means, that an instance addon MAY inherit it's launch configuration from another addon, which itself inherits it. Instance addons MAY modify inherited launch configurations using a launch patch object or override the main jar file. Inheriting a launch configuration with the launch flag also includes any modifications to it.

Launch configurations

Instance launch configurations are always based on a Minecraft launch config and MAY have patches applied to it. Patches are done by launch patch objects, which can override the main class and include additional arguments. Moreover instance addons MAY also add libraries to the classpath using the library install action. When launching a Minecraft instance, AddonScript implementations SHOULD take the Minecraft launch configuration as specified here of the version, on which the instance is based on, and then apply all patches of instance addons in the instance to it. Patches are applied in the order specified below. Patches, which are applied later, MAY override settings from earlier patches.

Patch apply order

Patches are applied in the following order:

Patches inherited from the another instance addon using the launch flag. The patches of that instance addon are applied according to the same order rules
Patches inherited from the another instance addon using the patch flag in the order, in which the addons are specified in the relations array
Patches done directly by the instance addon using the patches array in the order, in which they are specified in the array.

Main file

Instance addons MAY have a main jar file for each side. The main file MAY be specified for a side using the launch flag or MAY be inherited from another instance addon or from Minecraft itself using the launch flag. If it is neither specified nor inherited, the instance doesn't have a main jar file.

Namespaces

Namespaces are used in conjunction with addon IDs to uniquely identify an addon as well as an identifier for repositories.

Format

Namespaces MUST only contain lowercase alphanumeric characters, hyphens (SHOULD be avoided) and dots. They SHOULD be in a reversed domain name format. A namespace SHOULD specify the distribution source (i.e. com.example.repository) or the author (i.e. com.author.website) of the addon and optionally also the addon type (i.e. com.example.repository.mods, com.author.website.modpacks).

Repository Namespaces

A repository namespace describes an addon repository across API instances. A repository contains different addons and MAY be hosted on multiple API instances (mirrors). The ID of an addon MUST be unique in a repository, so an addon can be resolved by the addon ID in conjuction with the repository namespace. Since the same addon MAY be contained in multiple repositories, it MUST have a canonical namespace, so it can be identified globally. The repository described by the canonical namespace of an addon MUST also contain that addon. If different API instances return contradicting information about a repository, for example an addon with the same ID in the same repository has different canonical namespaces on different instances, the AddonScript implementation decides, which instance is more trustworthy. This MAY be done by comparing the repository namespace to the API URL or by asking the user.

Canonical Namespaces

While an addon MAY be included in multiple repository namespaces, it MUST have exactly one canonical namespace, which is defined in the addon manifest. An API instance MUST also return the canonical namespace of the addon on the addon endpoint even if the addon was requested from another repository namespace. To check, if two addons are the same addon, their canonical namespace and their ID MUST be equal.

AddonScript Versioning

AddonScript Version Numbers

AddonScript version numbers MUST only contain non-whitespace ASCII characters. They SHOULD follow the SemVer specifications. AddonScript version numbers are ordered according to the Maven version order specification.

SemVer Compatible Versions

If an AddonScript version number is valid SemVer, that version of the addon is SemVer compatible and implies all semantics according to SemVer. AddonScript implementations MAY provide specific behavior based on the semver semantics, for example warning the user before updating to a next major version.

AddonScript Version Ranges

An AddonScript version range can either be a SemVer version range or a Maven version range. If a version range starts with one of SemVer primitive operators (<, <=, >, >=, =) it will be considered as a SemVer version range, otherwise it will be a Maven version range. SemVer version ranges can only include SemVer compatible versions. If the version range is required to include an exact version, for example when using the included relational flag, it MUST be a Maven soft requirement, which is equal to the targeted version. In all other cases it is highly RECOMMENDED to use SemVer version ranges, as long as the targeted addon uses SemVer compatible versions.

Maven Versioning Specification

Version Order Specification

The Maven coordinate is split in tokens between dots ('.'), hyphens ('-') and transitions between digits and characters. The separator is recorded and will have effect on the order. A transition between digits and characters is equivalent to a hyphen. Empty tokens are replaced with "0". This gives a sequence of version numbers (numeric tokens) and version qualifiers (non-numeric tokens) with "." or "-" prefixes.

Splitting and Replacing Examples:

1-1.foo-bar1baz-.1 -> 1-1.foo-bar-1-baz-0.1

Then, starting from the end of the version, the trailing "null" values (0, "", "final", "ga") are trimmed. This process is repeated at each remaining hyphen from end to start.

Trimming Examples:

1.0.0 -> 1
1.ga -> 1
1.final -> 1
1.0 -> 1
1. -> 1
1- -> 1
1.0.0-foo.0.0 -> 1-foo
1.0.0-0.0.0 -> 1

The version order is the lexicographical order on this sequence of prefixed tokens, the shorter one padded with enough "null" values with matching prefix to have the same length as the longer one. Padded "null" values depend on the prefix of the other version: 0 for '.', "" for '-'. The prefixed token order is:

if the prefix is the same, then compare the token:
- Numeric tokens have the natural order.
- Non-numeric tokens ("qualifiers") have the alphabetical order, except for the following tokens which come first in this order: "alpha" < "beta" < "milestone" < "rc" = "cr" < "snapshot" < "" = "final" = "ga" < "sp"
  - the "alpha", "beta" and "milestone" qualifiers can respectively be shortened to "a", "b" and "m" when directly followed by a number.
else ".qualifier" < "-qualifier" < "-number" < ".number"

End Result Examples:

"1" < "1.1" (number padding)
"1-snapshot" < "1" < "1-sp" (qualifier padding)
"1-foo2" < "1-foo10" (correctly automatically "switching" to numeric order)
"1.foo" < "1-foo" < "1-1" < "1.1"
"1.ga" = "1-ga" = "1-0" = "1.0" = "1" (removing of trailing "null" values)
"1-sp" > "1-ga"
"1-sp.1" > "1-ga.1"
"1-sp-1" < "1-ga-1" = "1-1" (trailing "null" values at each hyphen)
"1-a1" = "1-alpha-1"

Note: Contrary to what was stated in some design documents, for version order, snapshots are not treated differently than releases or any other qualifier.

Dependency Version Requirement Specification

Version requirements have the following syntax:

1.0: Soft requirement for 1.0. Use 1.0 if no other version appears earlier in the dependency tree.
[1.0]: Hard requirement for 1.0. Use 1.0 and only 1.0.
(,1.0]: Hard requirement for any version <= 1.0.
[1.2,1.3]: Hard requirement for any version between 1.2 and 1.3 inclusive.
[1.0,2.0): 1.0 <= x < 2.0; Hard requirement for any version between 1.0 inclusive and 2.0 exclusive.
[1.5,): Hard requirement for any version greater than or equal to 1.5.
(,1.0],[1.2,): Hard requirement for any version less than or equal to 1.0 than or greater than or equal to 1.2, but not 1.1. Multiple requirements are separated by commas.
(,1.1),(1.1,): Hard requirement for any version except 1.1; for example because 1.1 has a critical vulnerability.

Maven picks the highest version of each project that satisfies all the hard requirements of the dependencies on that project. If no version satisfies all the hard requirements, the build fails.

Packaging

Packaging is a way to distribute an AddonScript file and associated files together in a single file. Currently, the only specified ackaging way is zip-based packaging.

Zip Packaging

With zip packaging, the AddonScript file and the associated files are contained in a zip file. The AddonScript file MUST be named manifest.json and MUST be placed at the root of the zip file. All files and directories inside the zip file can be accessed from AddonScript using the file links. The path from the file URL is relative to the location of the AddonScript file.