Merge pull request 'Flags overhaul' (#23) from tilera/addonscript-spec:master into master

Reviewed-on: addonscript/addonscript-spec#23

docs/concepts/flags.md

@@ -1,42 +1,42 @@
 # Flags
 
-## Side flags
+Flags are side-specific information about a [manifest](../schema/manifest.md), [file](../schema/file.md) or
+[relation](../schema/relation.md). There are two types of flags: [manifest flags](#manifest-flags) and
+[relational flags](#relational-flags). [Manifest 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](instance.md).
+[Relational flags](#relational-flags) provide information about how a file or relation is related to the addon.
 
-These are flags, which specify, for which side a [version](../schema/manifest.md), a [file](../schema/file.md) or
-a [relation](../schema/relation.md) was made. If a file has no side flags set, it will inherit them from the
-[version object](../schema/manifest.md), while a version is required to have side flags set.
+## Manifest flags
 
-- `client` This flag specifies, that the version, relation or file can be installed on the client side
-- `server` This flag specifies, that the version, relation or file can be installed on the server side
-
-## Version flags
-
-These are flags, which can be set for [versions](../schema/manifest.md).
-
-- `instance` This flag specifies, that this is a version of an instance addon. Instance addons represent instances of
-  Minecraft itself, while non-instance addons have to be installed into an existing instance of Minecraft.
+- `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.
+- `instance` This flag specifies, that this is a manifest of an [instance addon](instance.md).
 
 ## Relational flags
 
-These are flags, which describe the relation between the addon and [related addons](../schema/relation.md)
-or [files](../schema/file.md).
-
 - `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.
 - `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.
-
-### Relation specific
-
-These are relational flags, which can only be used for [relations](../schema/relation.md).
-
-- `included` This flag 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 since AddonScript assumes,
-  that they are already covered by this addon.
-- `incompatible` This flag specifies, that the related addon is incompatible to this one. This means, that they can't
-  be installed together in the same instance.
-- `launch` This flag specifies, that the related addon should take care of the Minecraft launch process. It can only
-  be used, if both this and the related addon are instance addons.
+- `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 
+  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. For a relation this flag specifies, that the launch configuration
+  should 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 should 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 should 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`.

docs/concepts/install.md

@@ -36,17 +36,6 @@ In contrast to libraries, `inject` will not add 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. 
 
-### launch
-
-`launch` can be used to mark the file as the launch file for a specific side. Files having this
-install action can only have the `client` or the `server` flag, not both. If the file is client-sided, it
-has to be a [client JSON file](https://minecraft.fandom.com/wiki/Client.json) as specified by Minecraft
-itself. If it is server-sided, it has to be a jar file, which is the file, that should be launched to start
-the server. The jar file has to be moved to the root of the instance directory, before using `launch` on it.
-Moreover, this install action may only be used with launchable or instance addons and there may be only one file for each
-side, which has this install action, except all of them are marked as `optional`, in which case they are also
-implicitly marked as incompatible to each other.
-
 ## Locations
 
 Locations are specified as a relative path from the Minecraft directory to which the file should be installed.

docs/concepts/instance.md

@@ -0,0 +1,16 @@
+# 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 requires
+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 can 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.
+
+## Instance addons as relations
+
+If an instance addon is a relation of another instance addon, each side of that
+relation requires to 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.

docs/schema/file.md

@@ -4,7 +4,7 @@
 {
   "qualifier": "modfile",
   "link": ["https://example.com/mymod.jar", "./mymod.jar"],
-  "flags": [],
+  "flags": {},
   "install": [],
   "hashes": {
     "sha1": "somesha1checksum"
@@ -40,8 +40,8 @@ The order in the array corresponds to the order in which the installation steps
 
 ### flags
 
-This is an array of [flags](../concepts/flags.md) for this file. If this property is not present in a file object, the file will 
-inherit the [side flags](../concepts/flags.md#side-flags) from the [version](manifest.md) and have the `required` flag set by default.
+This is an [flags object](flags.md) which contains [relational flags](../concepts/flags.md#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
 

docs/schema/flags.md

@@ -0,0 +1,24 @@
+# Flags object
+
+```json
+{
+    "client": ["optional"],
+    "server": ["required"],
+    "both": ["included"]
+}
+```
+
+## Optional properties
+
+### client
+
+This is an array of [flags](../concepts/flags.md) which only apply on the client side.
+
+### server
+
+This is an array of [flags](../concepts/flags.md) which only apply on the server side. 
+
+### both
+
+This is an array of [flags](../concepts/flags.md) which apply on both sides. AddonScript will
+treat each flag in this array as if it was in the [client array](#client) and the [server array](#server).

docs/schema/manifest.md

@@ -9,7 +9,7 @@
   "semver": "1.0.0",
   "files": [],
   "relations": [],
-  "flags": ["server", "client"],
+  "flags": {},
   "repositories": [],
   "meta": {}
 }
@@ -39,7 +39,7 @@ This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces
 
 ### flags
 
-This is an array of [flags](../concepts/flags.md) for this version.
+This is an [flags object](flags.md) which contains [manifest flags](../concepts/flags.md#manifest-flags) for both sides for this manifest.
 
 ## Optional properties
 

docs/schema/relation.md

@@ -6,7 +6,7 @@
   "namespace": "com.example",
   "version": "[1.0]",
   "repositories": ["repo1"],
-  "flags": []
+  "flags": {}
 }
 ```
 
@@ -41,5 +41,6 @@ the namespace from all defined repositories.
 
 ### flags
 
-This is an array of [flags](../concepts/flags.md) for this relation.  If this property is not present in a relation object, the relation will 
-inherit the [side flags](../concepts/flags.md#side-flags) from the [version](manifest.md) and have the `required` flag set by default.
+This is an [flags object](flags.md) which contains [relational flags](../concepts/flags.md#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.