tilera
/
addonscript-spec
forked from addonscript/addonscript-spec
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

new launch patches system

This commit is contained in:
Timo Ley 2023-08-16 10:18:35 +02:00
parent a4ef1a5c34
commit f5f0d8c1e3
9 changed files with 184 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/SUMMARY.md
View File

@ -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)

27
docs/concepts/flags.md
View File

@ -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.
- `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.

21
docs/concepts/install.md
View File

@ -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

62
docs/concepts/instance.md
View File

@ -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.
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.

28
docs/concepts/minecraft.md
View File

@ -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).

4
docs/schema/api_builder_response.md
View File

@ -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.
This is a [Launch Config object](./patch.md) for the server, which can be used, to modify the launch configuration of the instance.

47
docs/schema/launch.md
View File

@ -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.

14
docs/schema/manifest.md
View File

@ -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).

91
docs/schema/patch.md Normal file
View File

@ -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 `--<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`.