diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 6b84375..8cd2fc7 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -19,7 +19,7 @@ - [Flags Object](schema/flags.md) - [Repository Object](schema/repository.md) - [Meta Object](schema/meta.md) - - [Launch Config Object](schema/launch.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_builder_request.md) diff --git a/docs/concepts/flags.md b/docs/concepts/flags.md index 3dfb98a..54d06ef 100644 --- a/docs/concepts/flags.md +++ b/docs/concepts/flags.md @@ -20,29 +20,31 @@ addon manifest, including for which side it is available and for which side it i ## 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 relations of [instance addons](instance.md). It specifies, that the - [launch configuration](../schema/launch.md) should be inherited from the related addon (which MUST also be an - instance addon). The inherited launch configuration, MAY still be modified - using the [launch object](../schema/launch.md) of this addon or by adding libraries with the `library` flag. - This flag always also implies any effect of `required`. -- `env` This flag is only valid for relations of [instance addons](instance.md). +- `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` This flag is only valid for relations of [instance addons](instance.md), which use the +- `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). @@ -50,6 +52,7 @@ addon manifest, including for which side it is available and for which side it i 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. -- `library` This flag is only valid for files of [instance addons](instance.md). It specifies, that this file - will be added as a libary to the [launch configuration](../concepts/instance.md#launch-configurations) of this - addon. \ No newline at end of file +- `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. \ No newline at end of file diff --git a/docs/concepts/install.md b/docs/concepts/install.md index 1ae35d4..59760bc 100644 --- a/docs/concepts/install.md +++ b/docs/concepts/install.md @@ -6,7 +6,7 @@ args: -- `[location]` +- `` `move` moves the file to the given location. @@ -14,7 +14,7 @@ args: args: -- `[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]` +- `` `rename` renames the file to the new given filename. +### library + +args: + +- `` +- `` +- `` + +`library` can be used with jar files, to add them to the classpath of the game. +If a library with the same `` and ``, 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 diff --git a/docs/concepts/instance.md b/docs/concepts/instance.md index 682c1d9..2af2809 100644 --- a/docs/concepts/instance.md +++ b/docs/concepts/instance.md @@ -1,34 +1,48 @@ # 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 by inheriting the launch configuration of another -instance addon using the `launch` [flag](flags.md) or by modifying the [Minecraft](./minecraft.md) -launch configuration directly using a [launch config object](../schema/launch.md). -Inheriting a launch configuration MAY be recursive which -means, that an instance addon MAY inherit it's launch configuration from another addon, which +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 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 +[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 - -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`, -`expect` or `incompatible`. Non-instance addons MAY have instance addons as relations -without 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), which -can override the main class or main file and include additional arugments, and by adding -libraries using the `library` [flag](flags.md). +[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) and then apply -all modifications by instance addons in the launch inheritance 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. \ No newline at end of file +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 + [client_patches](../schema/manifest.md#clientpatches) and [server_patches](../schema/manifest.md#serverpatches) + properties. + +## 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. \ No newline at end of file diff --git a/docs/concepts/minecraft.md b/docs/concepts/minecraft.md index 18d8c2c..b41f74b 100644 --- a/docs/concepts/minecraft.md +++ b/docs/concepts/minecraft.md @@ -2,15 +2,13 @@ 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 have -their [launch configuration](./instance.md#launch-configurations) based on -the launch configuration of a Minecraft version. This way it is also defined, -on which version of Minecraft an instance is base on. The version of Minecraft, -which will be used, MUST be defined either by using the -`included` [relational flag](./flags.md#relational-flags) with an exact Minecraft -version or by using the `expected` [relational flag](./flags.md#relational-flags), -while the exact version later gets defined by the user or by the `env` -[relational flag](./flags.md#relational-flags). +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. @@ -58,14 +56,14 @@ be proceeded, and warned about possible incompatibilities. 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 +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 file, the main class, all required libraries and launch arguments. -In contrast to launch config modifications done by [instance addons](./instance.md), +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 they also provide an asset index, which SHOULD be used 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). \ No newline at end of file diff --git a/docs/schema/api_builder_response.md b/docs/schema/api_builder_response.md index 743ea0e..6d1843e 100644 --- a/docs/schema/api_builder_response.md +++ b/docs/schema/api_builder_response.md @@ -25,8 +25,8 @@ environment was build, and MUST be treated equal to the [files in the manifest]( ### launch_client -This is a [Launch Config object](./launch.md) for the client, which can be used, to modify the launch configuration of the instance. +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](./launch.md) for the server, which can be used, to modify the launch configuration of the instance. \ No newline at end of file +This is a [Launch Config object](./patch.md) for the server, which can be used, to modify the launch configuration of the instance. \ No newline at end of file diff --git a/docs/schema/launch.md b/docs/schema/launch.md deleted file mode 100644 index c90bac9..0000000 --- a/docs/schema/launch.md +++ /dev/null @@ -1,47 +0,0 @@ -# Launch Config Object - -```json -{ - "main_file": "somefilequalifier", - "main_class": "com.example.SomeClass", - "arguments": ["--someArgument"], - "jvm_arguments": ["-Djvmargument"], - "java_version": 8 -} -``` - -## 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) of this -addon. Setting this to an empty string will indicate, that -there is no main file for this instance, in which case the -[main_class](#main_class) 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](#main_file) should be used. - -### arguments - -This is an array of game arguments, which will be used to launch the instance -in addition to inherited arguments. They will be appended after inherited -arguments. - -### 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 inherited -JVM arguments. - -### 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. \ No newline at end of file diff --git a/docs/schema/manifest.md b/docs/schema/manifest.md index 1136c55..14590f7 100644 --- a/docs/schema/manifest.md +++ b/docs/schema/manifest.md @@ -12,8 +12,8 @@ "repositories": [], "instance": false, "use_builder": false, - "launch_client": {}, - "launch_server": {}, + "client_patches": {}, + "server_patches": {}, "meta": {} } ``` @@ -69,17 +69,17 @@ If this property is not present, it defaults to `false`. 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`. +If this property is not present, it defaults to `false`. (DEPRECATED) -### launch_client +### client_patches -This is a [launch config object](launch.md) for the client, +This is a [patch object](patch.md) for the client, which can be used to modify the launch configuration of this instance. Only available for [instance addons](../concepts/instance.md). -### launch_server +### server_patches -This is a [launch config object](launch.md) for the server, +This is a [patch object](patch.md) for the server, which can be used to modify the launch configuration of this instance. Only available for [instance addons](../concepts/instance.md). diff --git a/docs/schema/patch.md b/docs/schema/patch.md new file mode 100644 index 0000000..f0cbbf3 --- /dev/null +++ b/docs/schema/patch.md @@ -0,0 +1,91 @@ +# Launch Patch Object + +```json +{ + "main_class": "com.example.SomeClass", + "arguments": [], + "jvm_arguments": ["-Djvmargument"], + "replace_jvm_arguments": false, + "java_version": 8 +} +``` + +## 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 `-- `. +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`. \ No newline at end of file