use patches array instead of side patches

will be part of another api feature in the future

README.md

@@ -2,7 +2,7 @@
 
 The official AddonScript specification is available in the master branch of the 
 [addonscript-spec](https://git.tilera.org/AddonScript/addonscript-spec) repository
-and on [docs.addonscript.org](https://docs.addonscript.org/).
+and on [spec.addonscript.org](https://spec.addonscript.org/).
 
 ## What is AddonScript?
 

docs/SUMMARY.md

@@ -7,7 +7,7 @@
 - [AddonScript API](api/README.md)
   - [Addon repository](api/features/addons.md)
   - [File repository](api/features/files.md)
-  - [Environment builder](api/features/env.md)
+  - [Environment builder](api/features/builder.md)
 
 # Schema
 
@@ -19,14 +19,16 @@
   - [Flags Object](schema/flags.md)
   - [Repository Object](schema/repository.md)
   - [Meta Object](schema/meta.md)
+  - [Launch Patch Object](schema/patch.md)
 - [API Addon Object](schema/api_addon.md)
 - [API File Object](schema/api_file.md)
-- [Environment Builder Request Object](schema/api_env_request.md)
+- [Environment Builder Request Object](schema/api_builder_request.md)
   - [Addon Descriptor Object](schema/api_addon_descriptor.md)
-- [Environment Builder Response Object](schema/api_env_response.md)
+- [Environment Builder Response Object](schema/api_builder_response.md)
 
 # Concepts
 
+- [Minecraft](concepts/minecraft.md)
 - [Installing](concepts/install.md)
 - [Flags](concepts/flags.md)
 - [Instance addons](concepts/instance.md)

docs/api/README.md

@@ -4,30 +4,59 @@
 
 `GET {base URL}`
 
-The index endpoint can be used to get basic information about an API
-instance, including the API versions and features supported by that
-instance and the [default namespace](../concepts/namespaces.md#default-namespaces) of the instance. 
-The response object of this endpoint contains a `versions` property, which is an object with API
-version numbers as keys and the configuration objects for the specific API version as values.
-For API version `v2` (AddonScript major release 2) the configuration object contains a `default_namespace`
-property, which is the [default namespace](../concepts/namespaces.md#default-namespaces) of the API
-instance, and a `features` property, which is an array containing all [API features](#features)
-available on this API instance.
+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:
 
 ``` json
 {
-    "versions": {
-        "v2": {
-            "default_namespace": "com.example",
-            "features": ["listing", "filters", "com.example.customfeature"]
-        }
-    }
+    "versions": ["v2"]
 }
 ```
 
-## Features
+`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](#features) supported on this instance. It also contains
+a `manifest_version` property, which is the latest 
+[manifest version](../schema/addonscript.md#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:
+
+``` json
+{
+    "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
@@ -37,4 +66,4 @@ These API features are part of the AddonScript specification itself:
 
 - `addons`: [Addon repository](./features/addons.md)
 - `files`: [File repository](./features/files.md)
-- `env`: [Environment builder](./features/env.md)
+- `builder`: [Environment builder](./features/builder.md)

docs/api/features/addons.md

@@ -12,14 +12,14 @@ of the addon.
 
 #### Path variales:
 
-- `namespace`: A [namespace](../../concepts/namespaces.md) which contains the addon
+- `namespace`: The [namespace](../../concepts/namespaces.md#repository-namespaces) of a repository which contains the addon
 - `addon`: The ID of the addon
 
 #### Responses:
 
-- `200 OK`: The addon is available in this addon repository. 
+- `200 OK`: The addon is available on this API instance. 
 The response body MUST be an [API Addon Object](../../schema/api_addon.md).
-- `404 Not Found`: The addon is not available in this addon repository.
+- `404 Not Found`: The addon is not available on this API instance.
 
 ### Get addon manifest
 
@@ -29,12 +29,12 @@ This endpoint can be used to retrieve the manifest of a specific version of an a
 
 #### Path variables:
 
-- `namespace`: The namespace which contains the addon
+- `namespace`: The [namespace](../../concepts/namespaces.md#repository-namespaces) of a repository which contains the addon
 - `addon`: The ID of the addon
 - `version`: The [version number](../../concepts/versioning.md) of the requested version
 
 #### Responses:
 
-- `200 OK`: This version of the addon is available in this addon repository.
+- `200 OK`: This version of the addon is available on this API instance.
 The response body MUST be an [Addon Manifest](../../schema/manifest.md).
-- `404 Not Found`: This version of the addon is not available in this addon repository.
+- `404 Not Found`: This version of the addon is not available on this API instance.

docs/api/features/builder.md

@@ -0,0 +1,58 @@
+# 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](../../concepts/instance.md).
+
+If an [instance addon](../../concepts/instance.md), which has to provide a launch configuration, has
+[`use_builder`](../../schema/manifest.md#use_builder) set to `true`, AddonScript will send a request to this
+endpoint of an API instance, on which the [repository](../../schema/repository.md) of the
+[namespace](../../schema/manifest.md#namespace) of this addon can be found.
+This request contains information about the AddonScript [schema version](../../schema/api_builder_request.md#addonscript),
+which will be used in the request and about which [addon](../../schema/api_builder_request.md#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](../../schema/api_builder_request.md#addon) in this environment on that side. The [manifest](../../schema/manifest.md) 
+of this [addon](../../schema/api_builder_request.md#addon) uses the `expected` [relation flag](../../concepts/flags.md#relational-flags)
+to tell AddonScript, which [related addons](../../schema/relation.md) MAY and which MUST be requested on this endpoint
+and which [versions](../../schema/relation.md#version) 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](../../concepts/instance.md), which inherits the launch configuration from this addon. In later case,
+that [instance addon](../../concepts/instance.md) uses the `env` [relation flag](../../concepts/flags.md#relational-flags)
+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](../../schema/relation.md) of this one, which are or will be installed
+into this instance, including their version. This does not include [relations](../../schema/relation.md) with the 
+`expected` [relation flag](../../concepts/flags.md#relational-flags). 
+
+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](../../schema/api_builder_response.md#files), the AddonScript 
+[schema version](../../schema/api_builder_response.md#addonscript) for the response and the 
+[launch configuration](../../concepts/instance.md#launch-configurations) for this addon. 
+These files MUST be considered to be part of the [files](../../schema/manifest.md#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](../../schema/api_builder_request.md).
+
+#### Responses:
+
+- `200 OK`: The launch environment was successfully build.
+The response body MUST be an [Environment Builder Response Object](../../schema/api_builder_response.md).
+- `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.

docs/api/features/env.md

@@ -1,51 +0,0 @@
-# Environment builder 
-
-## Endpoints
-
-### Build launch environment
-
-`POST {base URL}/v2/env`
-
-This endpoint can be used to build the launch environment for an [instance addon](../../concepts/instance.md).
-
-If an [instance addon](../../concepts/instance.md), which has to provide a launch configuration, has the
-`env` [manifest flag](../../concepts/flags.md#manifest-flags), AddonScript will send a request to this
-endpoint if the API instance [specified in the manifest](../../schema/manifest.md#envapi) of that addon.
-This request contains information about the AddonScript [schema version](../../schema/api_env_request.md#addonscript),
-which will be used in the request and about which [addon](../../schema/api_env_request.md#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](../../schema/api_env_request.md#addon) in this environment on that side. The [manifest](../../schema/manifest.md) 
-of this [addon](../../schema/api_env_request.md#addon) uses the `env` [relation flag](../../concepts/flags.md#relational-flags)
-to tell AddonScript, which [related addons](../../schema/relation.md) MAY and which MUST be requested on this endpoint
-and which [versions](../../schema/relation.md#version) 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](../../concepts/instance.md), which delegates the launch configuration to this addon. In latetr case,
-that [instance addon](../../concepts/instance.md) uses the `env` [relation flag](../../concepts/flags.md#relational-flags)
-to specify an exact version for each addon, that will be requested. Each required `env` addon MUST be covered this way
-while only those optional `env` addons will be requested, which are covered this way. Lastly the request also contains
-for each side a list of all [related addons](../../schema/relation.md) of this one, which are or will be installed
-into this instance, including their version. This does not include [relations](../../schema/relation.md) with the 
-`env` [relation flag](../../concepts/flags.md#relational-flags). 
-
-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](../../schema/api_env_response.md#files) and the AddonScript 
-[schema version](../../schema/api_env_response.md#addonscript) for the response. These files MUST be considered
-to be part of the [files](../../schema/manifest.md#files) of the addon, from which the request was send
-and can then be installed.
-
-#### Request Body:
-
-The request body MUST be an [Environment Builder Request Object](../../schema/api_env_request.md).
-
-#### Responses:
-
-- `200 OK`: The launch environment was successfully build.
-The response body MUST be an [Environment Builder Response Object](../../schema/api_env_response.md).
-- `400 Bad Request`: The server was not able to build the launch environment because of
-invalid information sned by the client.
-- `500 Internal Server Error`: The server was not able to build the launch environment
-because of an internal error.

docs/concepts/flags.md

@@ -16,42 +16,43 @@ addon manifest, including for which side it is available and for which side it i
   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.
-- `instance` This flag specifies, that this is a manifest of an [instance addon](instance.md).
-- `env` This flag is only valid for [instance addons](instance.md). It specifies, that the 
-  [environment builder API](../api/features/env.md) will be used to bet the launch files for this addon.
-  An addon with this flag MUST have the [env_api](../schema/manifest.md#envapi) property. 
 
 ## Relational flags
 
 - `required` This flag specifies, that the related addon or file is required for the addon. If the addon gets installed,
-  than any relation or file, which has this flag set, also has to be 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, relations of the related addon will however be ignored 
+  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 [instance addons](instance.md). For a relation this flag specifies, that the launch 
-  configuration will be delegated to the related addon. The related addon MUST also be an instance addon on that side. 
-  For a file this flag specifies, that the file will be the launch file of this addon. On the client side the launch 
-  file MUST be a [client JSON file](https://minecraft.fandom.com/wiki/Client.json) which contains the client launch 
-  configuration. On the server side the launch file MUST be an executable jar file, which will be executed to start 
-  the server. This jar file will implicitly be installed by being moved to the root of the server directory. 
-  This flag always also implies any effect of `required`.
-- `env` This flag is only valid for relations of [instance addons](instance.md). It MUST only be used for instance
-  addons, that either have the `env` [manifest flag](#manifest-flags) or are delegating the launch configuration
-  to such an addon. This flag speficies, that the related addon will be [requested](../schema/api_env_request.md#requested)
-  to be part of the [launch environment](../api/features/env.md#build-launch-environment). For the addon, for
-  which the launch environment will be build, 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. An addon, that is delegating the launch configuration to one, which has the `env` 
-  [manifest flag](#manifest-flags), uses this flag to tell AddonScript, which version of the addons will be requested
-  for the environment by setting an exact [version](../schema/relation.md#version) for the relation. It also tells
-  AddonScript, which optional `env` addons will be part of the environment. If an addon with the `env`
-  [manifest flag](#manifest-flags) gets manually installed, meaning not as a dependency, the user SHOULD be asked,
-  which optional `env` addons and which version of each `env` addon will be requested.
+- `launch` This flag is only valid for relations and files of [instance addons](instance.md). For relations, it specifies, 
+  that the [launch patches](../schema/patch.md) 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](instance.md). 
+  An addon, that is inheriting the launch configuration from one, which uses the 
+  [environment builder](../api/features/builder.md), uses this flag to tell AddonScript, which version of the `expected` 
+  addons will be requested for the environment by setting an exact [version](../schema/relation.md#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](instance.md), which use the 
+  [environment builder](../api/features/builder.md). This flag speficies, that this addon expects the related addon 
+  to be [requested](../schema/api_builder_request.md#requested) as a part of the 
+  [launch environment](../api/features/builder.md#build-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](../api/features/builder.md), 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](instance.md). It specifies, that the 
+  [launch patches](../schema/patch.md) 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.

docs/concepts/install.md

@@ -6,7 +6,7 @@
 
 args:
 
-- `[location]`
+- `<location>`
 
 `move` moves the file to the given location.
 
@@ -14,7 +14,7 @@ args:
 
 args:
 
-- `[location]`
+- `<location>`
 
 `extract` can be used with zip files, to extract the contents of the zip file
 to the given location.
@@ -23,17 +23,30 @@ to the given location.
 
 args:
 
-- `[new name]`
+- `<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](./instance.md).
+
 ### 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. 
+are also in injected file. This install action can only be used by [instance addons](./instance.md).
 
 ## Locations
 

docs/concepts/instance.md

@@ -1,16 +1,47 @@
 # 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 MUST have
-a launch configuration for each side for which it is available. This means, that an instance
-addon MUST have exactly one [file](../schema/file.md) or [relation](../schema/relation.md)
-for each side, which has the `launch` [flag](flags.md) flag. A file MUST NOT have this flag 
-on both sides, since the file type is different for each side, while a relation MAY have
-it on both sides, as long as the related addon is itself an instance addon for both sides.
+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](flags.md) or by patching the [Minecraft](./minecraft.md)
+launch configuration directly using a [launch patch object](../schema/patch.md).
+Moreover they MAY override the main jar file using the `launch` [flag](flags.md)
+or inherit the launch configuration, including main jar overrides and patches,
+from another instance addon using the the `launch` [flag](flags.md).
+The `launch` [flag](flags.md) 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](../schema/patch.md) or override the main jar file. Inheriting a 
+launch configuration with the `launch` [flag](flags.md) also includes any
+modifications to it.
 
-## Instance addons as relations
+## Launch configurations
 
-If an instance addon is a relation of another instance addon, each side of that
-relation MUST have at least one of the [flags](flags.md) `included`, `launch`
-or `incompatible`. Non-instance addons MAY have instance addons as relations without
-this restrictions.
+Instance launch configurations are always based on a 
+[Minecraft launch config](./minecraft.md#launch-configuration) and MAY have patches
+applied to it. Patches are done by [launch patch objects](../schema/patch.md), 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](./install.md#library).
+When launching a Minecraft instance, AddonScript implementations SHOULD take the Minecraft
+launch configuration as specified [here](./minecraft.md#launch-configuration) 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](#patch-apply-order). Patches, which 
+are applied later, MAY override settings from earlier patches.
+
+### Patch apply order
+
+Patches are applied in the following order:
+
+1. Patches inherited from the another instance addon using the `launch` [flag](flags.md). The
+   patches of that instance addon are applied according to the same order rules
+2. Patches inherited from the another instance addon using the `patch` [flag](flags.md) in the order,
+   in which the addons are specified in the [relations array](../schema/manifest.md#relations)
+3. Patches done directly by the instance addon using the [patches array](../schema/manifest.md#patches) 
+   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](flags.md) or MAY be inherited from another instance addon or from
+[Minecraft](./minecraft.md) itself using the `launch` [flag](flags.md). If it is neither specified
+nor inherited, the instance doesn't have a main jar file.

docs/concepts/minecraft.md

@@ -0,0 +1,69 @@
+# Minecraft
+
+Minecraft itself can be used as a [relation](../schema/relation.md) in AddonScript
+[manifests](../schema/manifest.md). This way addons MAY define, with which versions
+of Minecraft they are compatible. Instances MUST be based on a Minecraft version.
+[Instance addons](./instance.md) MAY apply [patches](../schema/patch.md) to the
+Minecraft version of the instance. The version of Minecraft, 
+which will be used, MUST be defined by the [instance addon](./instance.md) by 
+using the `required` [relational flag](./flags.md#relational-flags) 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](#id-and-namespace) of Minecraft and how to
+handle it as specified below.
+
+## ID and Namespace
+
+The [addon ID](../schema/manifest.md#id) of Minecraft, which will be used for
+[relations](../schema/relation.md) is `minecraft` and the 
+[namespace](namespaces.md#canonical-namespaces) is `net.minecraft`.
+
+## Versions
+
+The AddonScript [version number](./versioning.md) 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](../schema/relation.md) 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](../schema/patch.md) done by [instance addons](./instance.md),
+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).

docs/concepts/namespaces.md

@@ -1,6 +1,7 @@
 # Namespaces
 
-Namespaces are used in conjunction with addon IDs to uniquely identify an addon.
+Namespaces are used in conjunction with addon IDs to uniquely identify an addon as well as
+an identifier for repositories.
 
 ## Format
 
@@ -9,18 +10,24 @@ They SHOULD be in a reversed domain name format. A namespace SHOULD specify the
 (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](../api/). 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](#canonical-namespaces), 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 have multiple namespaces, it MUST have exactly one canonical
-namespace, which is defined in the [addon manifest](../schema/manifest.md#namespace).
+While an addon MAY be included in multiple repository namespaces, it MUST have exactly 
+one canonical namespace, which is defined in the [addon manifest](../schema/manifest.md#namespace).
 An [API instance](../api/) MUST also return the canonical namespace of 
 the addon on the [addon endpoint](../api/features/addons.md#get-addon)
-even if the addon was requested from another namespace. To check, if two addons
-are the same addon, their canonical namespace and their ID MUST be equal.
-
-## Default Namespaces
-
-Each [API instance](../api/) has a default namespace. Addons in the 
-repository of that API instance SHOULD have that namespace, as long as there
-are no ID conflicts in the repository. The default namespace does not need
-to be the canonical namespace of these addons. 
+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.

docs/concepts/versioning.md

@@ -1,7 +1,28 @@
 # AddonScript Versioning
 
-Version numbers in AddonScript are based on Maven version numbers. The only difference to the Maven versioning specification is,
-that AddonScript version numbers MUST only contain non-space ASCII characters.
+## AddonScript Version Numbers
+
+AddonScript version numbers MUST only contain non-whitespace ASCII characters. They SHOULD follow the
+[SemVer specifications](https://semver.org/spec/v2.0.0.html). AddonScript version numbers are ordered
+according to the [Maven version order specification](#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](https://github.com/semver/semver/pull/584)
+or a [Maven version range](#dependency-version-requirement-specification). 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](#semver-compatible-versions). If the version range is required to include
+an exact version, for example when using the `included` [relational flag](./flags.md#relational-flags),
+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](#semver-compatible-versions).
 
 ## Maven Versioning Specification
 
@@ -50,7 +71,7 @@ End Result Examples:
 
 Note: Contrary to what was stated in some design documents, for version order, snapshots are not treated differently than releases or any other qualifier.
 
-### Dependancy Version Requirement Specification
+### Dependency Version Requirement Specification
 
 Version requirements have the following syntax:
 

docs/packaging/zip.md

@@ -1,8 +1,7 @@
 # Zip Packaging
 
 With zip packaging, the AddonScript file and the associated files are contained in
-a zip file. The AddonScript file MUST be named `addon.json` and MUST either be placed
-at the root of the zip file or, if there is just one directory in the root of the zip file,
-in this directory. All files and directories inside the zip file can be accessed from AddonScript
-using the [file links](../concepts/links.md#file). The path from the file URL is relative to the location of
-the AddonScript file.
+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](../concepts/links.md#file). 
+The path from the file URL is relative to the location of the AddonScript file.

docs/schema/api_addon_descriptor.md

@@ -17,7 +17,7 @@ This is the [ID](manifest.md#id) of the addon which this object describes.
 ### namespace
 
 This is the [namespace](../concepts/namespaces.md) of the addon which this object describes.
-It SHOULD be the [canonical namespace](../concepts/namespaces.md#canonical-namespaces).
+It MUST be the [canonical namespace](../concepts/namespaces.md#canonical-namespaces).
 
 ### version
 

docs/schema/api_builder_response.md

@@ -0,0 +1,32 @@
+# Environment Builder Response Object
+
+```json
+{
+    "addonscript": {},
+    "files": [],
+    "launch_client": {},
+    "launch_server": {},
+}
+```
+
+## Required properties
+
+### addonscript
+
+This is an [AddonScript object](addonscript.md) containing information about the version of AddonScript used in this response.
+It MUST be equal to the [addonscript Property](api_builder_request.md#addonscript) of the [request](api_builder_request.md).
+
+### files
+
+This is an array of [File objects](file.md). 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](manifest.md#files).
+
+## Optional properties
+
+### launch_client
+
+This is a [Launch Config object](./patch.md) for the client, which can be used, to modify the launch configuration of the instance.
+
+### launch_server
+
+This is a [Launch Config object](./patch.md) for the server, which can be used, to modify the launch configuration of the instance.

docs/schema/api_env_response.md

@@ -1,20 +0,0 @@
-# Environment Builder Response Object
-
-```json
-{
-    "addonscript": {},
-    "files": []
-}
-```
-
-## Required properties
-
-### addonscript
-
-This is an [AddonScript object](addonscript.md) containing information about the version of AddonScript used in this response.
-It MUST be equal to the [addonscript Property](api_env_request.md#addonscript) of the [request](api_env_request.md).
-
-### files
-
-This is an array of [File objects](file.md). 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](manifest.md#files).

docs/schema/file.md

@@ -8,7 +8,8 @@
   "install": [],
   "hashes": {
     "sha1": "somesha1checksum"
-  }
+  },
+  "meta": {}
 }
 ```
 
@@ -51,3 +52,6 @@ value is the checksum.
 Supported hash algorithms:
 - `sha1`
 
+### meta
+
+This is a [meta object](meta.md) containing metadata about the file. it SHOULD only contain [additional metadata](meta.md#additional).

docs/schema/install.md

@@ -3,7 +3,8 @@
 ```json
 {
   "action": "move",
-  "args": ["./mods"]
+  "args": ["./mods"],
+  "side": "both"
 }
 ```
 
@@ -18,3 +19,8 @@ This is the [install action](../concepts/install.md), which will be used at this
 ### args
 
 This is an array of arguments for the [install action](../concepts/install.md). 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`.

docs/schema/manifest.md

@@ -5,13 +5,14 @@
   "addonscript": {},
   "id": "myaddon",
   "namespace": "com.example",
-  "version": "1.0",
-  "semver": "1.0.0",
+  "version": "1.0.0",
   "files": [],
   "relations": [],
   "flags": {},
   "repositories": [],
-  "env_api": "https://example.com",
+  "instance": false,
+  "use_builder": false,
+  "patches": [],
   "meta": {}
 }
 ```
@@ -30,9 +31,7 @@ It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD b
 
 ### version
 
-This is the [version number](../concepts/versioning.md) of this version. Versions are compared by 
-[Maven version order rules](../concepts/versioning.md#version-order-specification).
-If this version number is valid semver, the `semver` property is implicitly equal to `version` if `semver` was not explicitly set.
+This is the [AddonScript version number](../concepts/versioning.md#addonscript-version-numbers) of this version.
 
 ### namespace
 
@@ -44,10 +43,6 @@ This is an [flags object](flags.md) which contains [manifest flags](../concepts/
 
 ## Optional properties
 
-### semver
-
-This is the version number of this version in semver format. It MUST follow the [semver versioning specifications](https://semver.org/spec/v2.0.0.html).
-
 ### files
 
 This is an array of [file objects](file.md) including the files belonging to this addon.
@@ -59,13 +54,27 @@ This is an array of [relation objects](relation.md) which represent addons in re
 ### repositories
 
 This is an array of [repository objects](repository.md). Each repository object defines one repository from which files or
-addons can be retrieved.
+addons can be retrieved. Each AddonScript manifest SHOULD have a repository for the [canonical namespace](#namespace) of 
+that manifest, from which AddonScript implementations MAY check for updates for this addon. If [use_builder](#use_builder) is `true`, 
+this addon MUST have such a repository to provide API instances, which can be used to request the 
+[launch environment](../api/features/builder.md#build-launch-environment).
 
-### env_api
+### instance
 
-This is the base URL of an [AddonScript API](../api) instance, which has the `env` feature and will be used to
-build the launch environment for this addon. This property will only be used if this addon has the `env`
-[manifest flag](../concepts/flags.md#manifest-flags).
+This is a boolean which specifies, if this addon is an [instance addon](../concepts/instance.md). 
+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](../api/features/builder.md).
+Only valid if [instance](#instance) is `true`.
+If this property is not present, it defaults to `false`. (DEPRECATED)
+
+### patches
+
+This is an array of [patch object](patch.md) which can be used to modify t
+he launch configuration of this instance.
+Only available for [instance addons](../concepts/instance.md).
 
 ### meta
 

docs/schema/patch.md

@@ -0,0 +1,98 @@
+# Launch Patch Object
+
+```json
+{
+    "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](../concepts/instance.md#main-file) 
+should be used.
+
+### arguments
+
+This is an array of [game argument objects](#game-argument-object), 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](#jvmarguments) 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
+
+```json
+{
+    "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`.

docs/schema/relation.md

@@ -16,28 +16,24 @@
 
 This is the ID of the addon this relation refers to.
 
+### version
+
+This is an [AddonScript version range](../concepts/versioning.md#addonscript-version-ranges) that specifies, which versions
+of the related addon are targeted by this relation.
+
 ## Optional properties
 
 ### namespace
 
-This is the [namespace](../concepts/namespaces.md) of the related addon. This property will be implicitly equal to the 
-[namespace of the addon](manifest.md#namespace), if it was not set explicitly.
-
-### version
-
-This is a [maven version range](../concepts/versioning.md#dependancy-version-requirement-specification) that specifies, which versions
-of the related addon are targeted by this relation. You can either set this property or `semver`, but exactly one of them MUST be set.
-
-### semver
-
-This is a [semver version range](https://github.com/semver/semver/pull/584) of supported versions of this relation.
-It will only allow versions of the related addon, which have a valid semver version number, which is in this range.
+This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the related addon. If this property is not set,
+AddonScript will resolve the namespace via the [addon endpoint](../api/features/addons.md#get-addon) of a [repository](#repositories).
 
 ### repositories
 
-This is an array of [repository](repository.md) IDs. 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 by
-the namespace from all [defined repositories](manifest.md#repositories).
+This is an array of [repository namespaces](repository.md#namespace). 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](manifest.md#namespace). The repository described the the [canonical namespace](#namespace) of this
+relation has always precedence before these repositories.
 
 ### flags
 

docs/schema/repository.md

@@ -2,17 +2,25 @@
 
 ```json
 {
-  "id": "asrepo",
-  "url": "https://api.addonscript.net"
+  "namespace": "net.addonscript",
+  "instances": ["https://api.addonscript.net"]
 }
 ```
 
 ## Required properties
 
-### id
+### namespace
 
-This is the ID of the repository. It MUST be unique in the [manifest](manifest.md).
+This is the [namespace](../concepts/namespaces.md), which describes this repository.
 
-### url
+### instances
 
-This is the base URL of an [AddonScript API](../api) instance.
+This is an array of base URLs of [AddonScript API](../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](../api/features/addons.md#get-addon)
+of these API instances in the order, in which they are specified in this array.
+Instances in this array with the `builder` [feature](../api/features/builder.md) will
+be used by AddonScript, to request the launch environment for an addon with a
+[canonical namespace](../concepts/namespaces.md#canonical-namespaces) equal
+to the [namespace](#namespace) of this repository. The first API instance with 
+the `builder` feature will be used in this case with the others as fallback.