instance addon overhaul

This commit is contained in:
Timo Ley 2023-02-03 16:20:43 +01:00
parent c8c27c5170
commit 006adfec92
9 changed files with 215 additions and 17 deletions

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

68
docs/schema/launch.md Normal file
View file

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

24
docs/schema/library.md Normal file
View file

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

View file

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