From 006adfec92909e68e6a053e469f571578c7b71ab Mon Sep 17 00:00:00 2001 From: Timo Ley Date: Fri, 3 Feb 2023 16:20:43 +0100 Subject: [PATCH] instance addon overhaul --- docs/SUMMARY.md | 3 ++ docs/concepts/flags.md | 12 ++---- docs/concepts/instance.md | 28 +++++++++++--- docs/concepts/minecraft.md | 65 +++++++++++++++++++++++++++++++ docs/schema/api_env_response.md | 11 +++++- docs/schema/install.md | 8 +++- docs/schema/launch.md | 68 +++++++++++++++++++++++++++++++++ docs/schema/library.md | 24 ++++++++++++ docs/schema/manifest.md | 13 +++++++ 9 files changed, 215 insertions(+), 17 deletions(-) create mode 100644 docs/concepts/minecraft.md create mode 100644 docs/schema/launch.md create mode 100644 docs/schema/library.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 3d0dfcc..888596d 100644 --- a/docs/SUMMARY.md +++ b/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) diff --git a/docs/concepts/flags.md b/docs/concepts/flags.md index 8c4adda..0a190d0 100644 --- a/docs/concepts/flags.md +++ b/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 - 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`. +- `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 als be an + instance addon or [Minecraft](./minecraft.md) itself). The inherited launch configuration, MAY still be modified + using the [launch object](../schema/launch.md) of this addon. 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) diff --git a/docs/concepts/instance.md b/docs/concepts/instance.md index 8a330e3..b040f19 100644 --- a/docs/concepts/instance.md +++ b/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 -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. +a launch configuration for each side by inheriting the launch configuration of another +instance addon or [Minecraft](./minecraft.md) itself using the `launch` [flag](flags.md). +Inheriting a launch configuration MAY be 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 +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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/concepts/minecraft.md b/docs/concepts/minecraft.md new file mode 100644 index 0000000..42d3ec7 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/schema/api_env_response.md b/docs/schema/api_env_response.md index 4a41693..1e6356f 100644 --- a/docs/schema/api_env_response.md +++ b/docs/schema/api_env_response.md @@ -3,7 +3,8 @@ ```json { "addonscript": {}, - "files": [] + "files": [], + "launch": {} } ``` @@ -17,4 +18,10 @@ It MUST be equal to the [addonscript Property](api_env_request.md#addonscript) o ### 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). \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/schema/install.md b/docs/schema/install.md index 54fd1a0..2e73eee 100644 --- a/docs/schema/install.md +++ b/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`. diff --git a/docs/schema/launch.md b/docs/schema/launch.md new file mode 100644 index 0000000..61281c4 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/schema/library.md b/docs/schema/library.md new file mode 100644 index 0000000..f420af7 --- /dev/null +++ b/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`. \ No newline at end of file diff --git a/docs/schema/manifest.md b/docs/schema/manifest.md index adcf124..b02693a 100644 --- a/docs/schema/manifest.md +++ b/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.