instance addon overhaul

docs/SUMMARY.md

@@ -19,6 +19,8 @@
   - [Flags Object](schema/flags.md)
   - [Repository Object](schema/repository.md)
   - [Meta Object](schema/meta.md)
+  - [Launch Config Object](schema/launch.md)
+    - [Library Object](schema/library.md)
 - [API Addon Object](schema/api_addon.md)
 - [API File Object](schema/api_file.md)
 - [Environment Builder Request Object](schema/api_env_request.md)
@@ -27,6 +29,7 @@
 
 # Concepts
 
+- [Minecraft](concepts/minecraft.md)
 - [Installing](concepts/install.md)
 - [Flags](concepts/flags.md)
 - [Instance addons](concepts/instance.md)

docs/concepts/flags.md

@@ -16,7 +16,6 @@ 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 get the launch files for this addon.
   An addon with this flag MUST have a [repository](../schema/repository.md) for it's 
@@ -37,13 +36,10 @@ addon manifest, including for which side it is available and for which side it i
 - `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 
+- `launch` This flag is only valid for relations of [instance addons](instance.md). It specifies, that the 
-  configuration will be delegated to the related addon. The related addon MUST also be an instance addon on that side. 
+  [launch configuration](../schema/launch.md) should be inherited from the related addon (which MUST als be an
-  For a file this flag specifies, that the file will be the launch file of this addon. On the client side the launch 
+  instance addon or [Minecraft](./minecraft.md) itself). The inherited launch configuration, MAY still be modified
-  file MUST be a [client JSON file](https://minecraft.fandom.com/wiki/Client.json) which contains the client launch 
+  using the [launch object](../schema/launch.md) of this addon. This flag always also implies any effect of `required`.
-  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)

docs/concepts/instance.md

@@ -2,15 +2,31 @@
 
 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
+a launch configuration for each side by inheriting the launch configuration of another
-addon MUST have exactly one [file](../schema/file.md) or [relation](../schema/relation.md)
+instance addon or [Minecraft](./minecraft.md) itself using the `launch` [flag](flags.md). 
-for each side, which has the `launch` [flag](flags.md) flag. A file MUST NOT have this flag 
+Inheriting a launch configuration MAY be recursive which 
-on both sides, since the file type is different for each side, while a relation MAY have
+means, that an instance addon MAY inherit it's launch configuration from another addon, which 
-it on both sides, as long as the related addon is itself an instance addon for both sides.
+itself inherits it. Instance addons MAY modify inherited launch configurations using a 
+[launch config object](../schema/launch.md) by overriding the main file or main class, or by
+adding libraries or launch arguments. Inheriting a launch configuration also includes any
+modifications to it.
 
 ## Instance addons as relations
 
 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`, `env`
 or `incompatible`. Non-instance addons MAY have instance addons as relations without
-this restrictions.
+this restriction.
+
+## Launch configurations
+
+Instance launch configurations are always based on a 
+[Minecraft launch config](./minecraft.md#launch-configuration) and MAY have modifications
+applied to it. Modifications are done by [launch config objects](../schema/launch.md) and
+can override the main class or main file and include additional libraries and arugments.
+When launching a Minecraft instance, AddonScript implementations SHOULD take the Minecraft
+launch configuration as specified [here](./minecraft.md#launch-configuration) and then apply
+all modifications by instance addons in the instance stack to it. When overriding the main class
+or file, an instance addon has always priority over the instance addon, from which it inherits
+the launch config. When adding arguments, they are always appended at the end of those
+arguments from the inherited launch config.

docs/concepts/minecraft.md

@@ -0,0 +1,65 @@
+# 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. [Instance addons](./instance.md) MUST either
+directly or indirectly inherit their launch configuration from Minecraft. This 
+way it is also defined, on which version of Minecraft an instance is base on.
+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,
+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 file, the main class, all required libraries and launch arguments.
+In contrast to launch config modifications 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 they also provide an asset index, which SHOULD be used by
+implementations to retrieve game assets (if they are not already cached).

docs/schema/api_env_response.md

@@ -3,7 +3,8 @@
 ```json
 {
     "addonscript": {},
-    "files": []
+    "files": [],
+    "launch": {}
 }
 ```
 
@@ -18,3 +19,9 @@ It MUST be equal to the [addonscript Property](api_env_request.md#addonscript) o
 
 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
+
+This is a [Launch Config object](./launch.md) which can be used, to modify the launch configuration of the instance.

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/launch.md

@@ -0,0 +1,68 @@
+# Launch Config Object
+
+```json
+{
+    "libraries": [],
+    "java_version": 8,
+    "client": {},
+    "server": {}
+}
+```
+
+## Optional properties
+
+
+### libraries
+
+This is an array of [libraries](library.md), which are added to the instance in
+addition to those of inherited launch configurations.
+
+### 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 inherited `java_version`
+settings.
+
+### client
+
+This is a [side config object](#side-config-object) containing the launch configuration
+for the client.
+
+### server
+
+This is a [side config object](#side-config-object) containing the launch configuration
+for the server.
+
+# Side Config Object
+
+```json
+{
+    "main_file": "somefilequalifier",
+    "main_class": "com.example.SomeClass",
+    "arguments": ["--someArgument"]
+}
+```
+
+## Optional properties
+
+### main_file
+
+This is the [qualifier](./file.md#qualifier) of the main jar file for
+this side. It will override any inherited main file for this side.
+That file MUST be specified in the [manifest](./manifest.md), which
+uses this library. Setting this to an empty string will indicate, that
+there is no main file for this instance, in which case the 
+[main_file](#mainfile) MUST be explicitly configured. 
+
+### main_class
+
+This is the main class for this instance, which will be used to launch
+the game. It will override any inherited main class for this side. 
+Setting this to an empty string will indicate, that the main class
+specified in of manifest of the [main jar file](#mainfile) should be used.
+
+### arguments
+
+This is an array of arguments, which will be used to launch the instance
+in addition to inherited arguments. They will be appendes after inherited 
+arguments.

docs/schema/library.md

@@ -0,0 +1,24 @@
+# Library Object
+
+```json
+{
+    "file": "somequalifier",
+    "side": "both"
+}
+```
+
+## Required properties
+
+### file
+
+This is the [qualifier](./file.md#qualifier) of the file of this library.
+That file MUST be specified in the [manifest](./manifest.md), which
+uses this library.
+
+### Optional properties
+
+### side
+
+This specifies, for which side this library should be used. Valid values
+are `client`, `server` and `both`. If this property is not present, 
+it defaults to `both`.

docs/schema/manifest.md

@@ -10,6 +10,8 @@
   "relations": [],
   "flags": {},
   "repositories": [],
+  "instance": false,
+  "launch": {},
   "meta": {}
 }
 ```
@@ -56,6 +58,17 @@ that manifest, from which AddonScript implementations MAY check for updates for
 [manifest flag](../concepts/flags.md#manifest-flags), it MUST have such a repository to provide API instances, which can
 be used to request the [launch environment](../api/features/env.md#build-launch-environment).
 
+### instance
+
+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`.
+
+### launch
+
+This is a [launch config object](launch.md) which can be used to modify the 
+inherited launch configuration of this instance.
+Only available for [instance addons](../concepts/instance.md).
+
 ### meta
 
 This is a [meta object](meta.md) containing metadata about the addon.