forked from addonscript/addonscript-spec
Compare commits
55 commits
unstable/e
...
master
Author | SHA1 | Date | |
---|---|---|---|
Timo Ley | 2949623607 | ||
Timo Ley | 25cf1e7561 | ||
Timo Ley | 3c2dd500a2 | ||
Timo Ley | f5f0d8c1e3 | ||
Timo Ley | a4ef1a5c34 | ||
Timo Ley | f2ca4f5177 | ||
Timo Ley | 6414425d5e | ||
Timo Ley | c7e68360fb | ||
Timo Ley | 41fe553787 | ||
Timo Ley | 006adfec92 | ||
Timo Ley | c8c27c5170 | ||
Timo Ley | 83c8948f95 | ||
Timo Ley | f265e1c858 | ||
Timo Ley | 38997a8984 | ||
Timo Ley | 14aa5338d2 | ||
Timo Ley | afd8a4b37b | ||
Timo Ley | 27ad758268 | ||
Timo Ley | 041fad3e6f | ||
Timo Ley | fce82e72e5 | ||
Timo Ley | 30545bf09e | ||
Timo Ley | 1861e66548 | ||
Timo Ley | 3fcece2622 | ||
Timo Ley | 967a4b9a24 | ||
Timo Ley | c170119e80 | ||
Timo Ley | 124f9a6a2b | ||
Timo Ley | 0f66dca177 | ||
Timo Ley | 9d5b4d945e | ||
Timo Ley | 65408a2b21 | ||
Timo Ley | c304c62855 | ||
Timo Ley | 6fab000c56 | ||
Timo Ley | 226cbf7cdb | ||
Timo Ley | a9dfcb7575 | ||
Timo Ley | 6e51a51ddc | ||
Timo Ley | ea975232e5 | ||
Timo Ley | 27d2e57c51 | ||
Timo Ley | aae473bc94 | ||
Timo Ley | 481174b566 | ||
Timo Ley | f14ec070d4 | ||
Timo Ley | cd44fe0184 | ||
Timo Ley | 30e93f7621 | ||
Timo Ley | 3f042e332c | ||
Timo Ley | 9d86792bfc | ||
Timo Ley | ca281821b8 | ||
Timo Ley | de156c1f0d | ||
Timo Ley | bc24466b0c | ||
Timo Ley | 90d8babdd2 | ||
Timo Ley | 63b4c53a59 | ||
Timo Ley | a4ec67e76c | ||
Timo Ley | 123f62e1c2 | ||
Timo Ley | 2a3d340b20 | ||
Timo Ley | 44372968e6 | ||
Timo Ley | f976226b20 | ||
Timo Ley | 9a0db82745 | ||
Timo Ley | 56837dcec1 | ||
Timo Ley | ef6dc8fa6f |
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
The official AddonScript specification is available in the master branch of the
|
The official AddonScript specification is available in the master branch of the
|
||||||
[addonscript-spec](https://git.tilera.org/AddonScript/addonscript-spec) repository
|
[addonscript-spec](https://git.tilera.org/AddonScript/addonscript-spec) repository
|
||||||
and on [docs.addonscript.org](https://docs.addonscript.org/).
|
and on [spec.addonscript.org](https://spec.addonscript.org/).
|
||||||
|
|
||||||
## What is AddonScript?
|
## What is AddonScript?
|
||||||
|
|
||||||
|
|
|
@ -5,22 +5,33 @@
|
||||||
# API
|
# API
|
||||||
|
|
||||||
- [AddonScript API](api/README.md)
|
- [AddonScript API](api/README.md)
|
||||||
|
- [Addon repository](api/features/addons.md)
|
||||||
|
- [File repository](api/features/files.md)
|
||||||
|
- [Environment builder](api/features/builder.md)
|
||||||
|
|
||||||
# Schema
|
# Schema
|
||||||
|
|
||||||
- [Addon Object](schema/addon.md)
|
- [Addon Manifest Object](schema/manifest.md)
|
||||||
- [AddonScript Object](schema/addonscript.md)
|
- [AddonScript Object](schema/addonscript.md)
|
||||||
- [File Object](schema/file.md)
|
- [File Object](schema/file.md)
|
||||||
- [Install Object](schema/install.md)
|
- [Install Object](schema/install.md)
|
||||||
- [Relation Object](schema/relation.md)
|
- [Relation Object](schema/relation.md)
|
||||||
- [Conditions Object](schema/conditions.md)
|
- [Flags Object](schema/flags.md)
|
||||||
- [Repository Object](schema/repository.md)
|
- [Repository Object](schema/repository.md)
|
||||||
- [Meta Object](schema/meta.md)
|
- [Meta Object](schema/meta.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)
|
||||||
|
- [Addon Descriptor Object](schema/api_addon_descriptor.md)
|
||||||
|
- [Environment Builder Response Object](schema/api_builder_response.md)
|
||||||
|
|
||||||
# Concepts
|
# Concepts
|
||||||
|
|
||||||
|
- [Minecraft](concepts/minecraft.md)
|
||||||
- [Installing](concepts/install.md)
|
- [Installing](concepts/install.md)
|
||||||
- [Flags](concepts/flags.md)
|
- [Flags](concepts/flags.md)
|
||||||
|
- [Instance addons](concepts/instance.md)
|
||||||
- [Links](concepts/links.md)
|
- [Links](concepts/links.md)
|
||||||
- [Namespaces](concepts/namespaces.md)
|
- [Namespaces](concepts/namespaces.md)
|
||||||
- [Versioning](concepts/versioning.md)
|
- [Versioning](concepts/versioning.md)
|
||||||
|
|
|
@ -2,73 +2,68 @@
|
||||||
|
|
||||||
## The Index Endpoint
|
## The Index Endpoint
|
||||||
|
|
||||||
### `GET {base URL}`
|
`GET {base URL}`
|
||||||
|
|
||||||
The index endpoint can be used to get basic information about an API
|
The index endpoint can be used to get basic information about which
|
||||||
instance, including the API versions and features supported by that
|
API versions an API instance implements. The response object of this
|
||||||
instance and the default namespace of the instance.
|
endpoint contains a `versions` property, which is an array containing
|
||||||
|
all API versions available on this instance.
|
||||||
|
|
||||||
#### Example response body:
|
### Example response body:
|
||||||
|
|
||||||
``` json
|
``` json
|
||||||
{
|
{
|
||||||
"default_namespace": "com.example",
|
"versions": ["v2"]
|
||||||
"versions": ["v1"],
|
|
||||||
"features": ["listing", "filters", "com.example.customfeature"]
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Basic Endpoints
|
`GET {base URL}/{API version}`
|
||||||
|
|
||||||
### `GET {base URL}/v1/addons/:namespace/:addon`
|
Each API version also has an index endpoint with information specifically
|
||||||
|
about that version. The response of that index MAY differ across different
|
||||||
|
API versions. If an API version is not implemented on an instance, the
|
||||||
|
corresponding index endpoint MUST return a `400 Bad Request` or
|
||||||
|
`404 Not Found` status code.
|
||||||
|
|
||||||
This endpoint can be used to retrieve information about a specific addon,
|
## API Version v2:
|
||||||
including metadata, all available versions and the canonical namespace of
|
|
||||||
the addon.
|
|
||||||
|
|
||||||
#### Path variales:
|
This version of the AddonScript specification only specifies API version `v2`,
|
||||||
|
which is currently the only existing version.
|
||||||
|
|
||||||
- `namespace`: The namespace which contains the addon
|
`GET {base URL}/v2`
|
||||||
- `addon`: The ID of the addon
|
|
||||||
|
|
||||||
#### Example response body:
|
The `v2` version index endpoint can be used to retrieve the API features
|
||||||
|
supported by this API instance on version `v2`. The response object of
|
||||||
|
this endpint contains a `features` property, which is an array containing
|
||||||
|
all [API features](#features) supported on this instance. It also contains
|
||||||
|
a `manifest_version` property, which is the latest
|
||||||
|
[manifest version](../schema/addonscript.md#version) available on this API
|
||||||
|
instance. This version MUST be part of AddonScript major version 2.
|
||||||
|
The manifest version of all manifests (and other objects using the manifest
|
||||||
|
version), returned by enpoints of this API version on this instance, MUST be
|
||||||
|
equal or less than this property, but MUST also be part of AddonScript major
|
||||||
|
version 2 (manifest version must be greater or equal to 2). If a client does
|
||||||
|
not support the manifest version returned by this endpoint, it SHOULD try to
|
||||||
|
request addons from other API instances, as this instance MAY return manifests
|
||||||
|
which are unsupported by the client.
|
||||||
|
|
||||||
|
### Example response body:
|
||||||
|
|
||||||
``` json
|
``` json
|
||||||
{
|
{
|
||||||
"id": "addon-id",
|
"features": ["addons", "env", "com.example.customfeature"],
|
||||||
"namespace": "com.example.canonical",
|
"manifest_version": 2
|
||||||
"meta": {
|
|
||||||
"addon": {},
|
|
||||||
"additional": {}
|
|
||||||
},
|
|
||||||
"versions": [
|
|
||||||
"1.0"
|
|
||||||
]
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
The [meta object](../schema/meta.md) is the same as in the AddonScript files,
|
### Features
|
||||||
exept, that it only includes `addon` and `additional` metadata and not `version`
|
|
||||||
specific metadata.
|
|
||||||
|
|
||||||
### `GET {base URL}/v1/addons/:namespace/:addon/:version`
|
|
||||||
|
|
||||||
This endpoint can be used to retrieve a specific version of an addon.
|
|
||||||
The response body of this endpoint contains the [addon schema](../schema/addon.md),
|
|
||||||
which is also used in AddonScript JSON files.
|
|
||||||
|
|
||||||
#### Path variables:
|
|
||||||
|
|
||||||
- `namespace`: The namespace which contains the addon
|
|
||||||
- `addon`: The ID of the addon
|
|
||||||
- `version`: The [version number](../concepts/versioning.md) of the requested version
|
|
||||||
|
|
||||||
## Features
|
|
||||||
|
|
||||||
API features can be either part of the specification itself or
|
API features can be either part of the specification itself or
|
||||||
are specified by third parties. Third-party API features should
|
are specified by third parties. Third-party API features SHOULD
|
||||||
be in a namespace-like format (reversed domain name).
|
be in a namespace-like format (reversed domain name).
|
||||||
|
|
||||||
These API features are part of the AddonScript specification itself:
|
These API features are part of the AddonScript specification itself:
|
||||||
|
|
||||||
- To be added
|
- `addons`: [Addon repository](./features/addons.md)
|
||||||
|
- `files`: [File repository](./features/files.md)
|
||||||
|
- `builder`: [Environment builder](./features/builder.md)
|
40
docs/api/features/addons.md
Normal file
40
docs/api/features/addons.md
Normal file
|
@ -0,0 +1,40 @@
|
||||||
|
# Addon repository
|
||||||
|
|
||||||
|
## Endpoints
|
||||||
|
|
||||||
|
### Get addon
|
||||||
|
|
||||||
|
`GET {base URL}/v2/addons/:namespace/:addon`
|
||||||
|
|
||||||
|
This endpoint can be used to retrieve information about a specific addon,
|
||||||
|
including metadata, all available versions and the [canonical namespace](../../concepts/namespaces.md#canonical-namespaces)
|
||||||
|
of the addon.
|
||||||
|
|
||||||
|
#### Path variales:
|
||||||
|
|
||||||
|
- `namespace`: The [namespace](../../concepts/namespaces.md#repository-namespaces) of a repository which contains the addon
|
||||||
|
- `addon`: The ID of the addon
|
||||||
|
|
||||||
|
#### Responses:
|
||||||
|
|
||||||
|
- `200 OK`: The addon is available on this API instance.
|
||||||
|
The response body MUST be an [API Addon Object](../../schema/api_addon.md).
|
||||||
|
- `404 Not Found`: The addon is not available on this API instance.
|
||||||
|
|
||||||
|
### Get addon manifest
|
||||||
|
|
||||||
|
`GET {base URL}/v2/addons/:namespace/:addon/:version`
|
||||||
|
|
||||||
|
This endpoint can be used to retrieve the manifest of a specific version of an addon.
|
||||||
|
|
||||||
|
#### Path variables:
|
||||||
|
|
||||||
|
- `namespace`: The [namespace](../../concepts/namespaces.md#repository-namespaces) of a repository which contains the addon
|
||||||
|
- `addon`: The ID of the addon
|
||||||
|
- `version`: The [version number](../../concepts/versioning.md) of the requested version
|
||||||
|
|
||||||
|
#### Responses:
|
||||||
|
|
||||||
|
- `200 OK`: This version of the addon is available on this API instance.
|
||||||
|
The response body MUST be an [Addon Manifest](../../schema/manifest.md).
|
||||||
|
- `404 Not Found`: This version of the addon is not available on this API instance.
|
58
docs/api/features/builder.md
Normal file
58
docs/api/features/builder.md
Normal file
|
@ -0,0 +1,58 @@
|
||||||
|
# Environment builder
|
||||||
|
|
||||||
|
## Endpoints
|
||||||
|
|
||||||
|
### Build launch environment
|
||||||
|
|
||||||
|
`POST {base URL}/v2/builder`
|
||||||
|
|
||||||
|
This endpoint can be used to build the launch environment for an [instance addon](../../concepts/instance.md).
|
||||||
|
|
||||||
|
If an [instance addon](../../concepts/instance.md), which has to provide a launch configuration, has
|
||||||
|
[`use_builder`](../../schema/manifest.md#use_builder) set to `true`, AddonScript will send a request to this
|
||||||
|
endpoint of an API instance, on which the [repository](../../schema/repository.md) of the
|
||||||
|
[namespace](../../schema/manifest.md#namespace) of this addon can be found.
|
||||||
|
This request contains information about the AddonScript [schema version](../../schema/api_builder_request.md#addonscript),
|
||||||
|
which will be used in the request and about which [addon](../../schema/api_builder_request.md#addon) this request is for.
|
||||||
|
Moreover it contains for both sides a list of addons, including their version, which will be part of the
|
||||||
|
[addon](../../schema/api_builder_request.md#addon) in this environment on that side. The [manifest](../../schema/manifest.md)
|
||||||
|
of this [addon](../../schema/api_builder_request.md#addon) uses the `expected` [relation flag](../../concepts/flags.md#relational-flags)
|
||||||
|
to tell AddonScript, which [related addons](../../schema/relation.md) MAY and which MUST be requested on this endpoint
|
||||||
|
and which [versions](../../schema/relation.md#version) of them are valid. Which exact version of them and which optional
|
||||||
|
addons will be requested is either decided by the user, if the instance addon is installed manually, or by another
|
||||||
|
[instance addon](../../concepts/instance.md), which inherits the launch configuration from this addon. In later case,
|
||||||
|
that [instance addon](../../concepts/instance.md) uses the `env` [relation flag](../../concepts/flags.md#relational-flags)
|
||||||
|
to specify an exact version for each addon, that will be requested. Each required `expected` addon MUST be covered this way
|
||||||
|
while only those optional `expected` addons will be requested, which are covered this way. Lastly the request also contains
|
||||||
|
for each side a list of all [related addons](../../schema/relation.md) of this one, which are or will be installed
|
||||||
|
into this instance, including their version. This does not include [relations](../../schema/relation.md) with the
|
||||||
|
`expected` [relation flag](../../concepts/flags.md#relational-flags).
|
||||||
|
|
||||||
|
Since the API instance MAY download files or build/compile things to build the launch environment, this request MAY
|
||||||
|
take some time so the client implementation SHOULD set the request timeout for this endpoint rather high. It is
|
||||||
|
RECOMMENDED to have a timeout of at least 5 minutes, better about 10 minutes.
|
||||||
|
|
||||||
|
After the launch environment was build by the API instance, this endpoint will respond with a list of
|
||||||
|
[file objects](../../schema/api_builder_response.md#files), the AddonScript
|
||||||
|
[schema version](../../schema/api_builder_response.md#addonscript) for the response and the
|
||||||
|
[launch configuration](../../concepts/instance.md#launch-configurations) for this addon.
|
||||||
|
These files MUST be considered to be part of the [files](../../schema/manifest.md#files) of the addon,
|
||||||
|
from which the request was send and can then be installed. The launch configuration will override the entirely.
|
||||||
|
|
||||||
|
#### Request Body:
|
||||||
|
|
||||||
|
The request body MUST be an [Environment Builder Request Object](../../schema/api_builder_request.md).
|
||||||
|
|
||||||
|
#### Responses:
|
||||||
|
|
||||||
|
- `200 OK`: The launch environment was successfully build.
|
||||||
|
The response body MUST be an [Environment Builder Response Object](../../schema/api_builder_response.md).
|
||||||
|
- `400 Bad Request`: The server was not able to build the launch environment because of
|
||||||
|
invalid information send by the client. The client SHOULD NOT try this request on
|
||||||
|
another API instance, since the request is invalid.
|
||||||
|
- `404 Not Found`: The launch environment can't be build for this addon, because no information
|
||||||
|
about it was found on this API instance. The client SHOULD try to use another API instance
|
||||||
|
to build the environment.
|
||||||
|
- `500 Internal Server Error`: The server was not able to build the launch environment
|
||||||
|
because of an internal error. The client MAY try to request the environment on another
|
||||||
|
API instance.
|
44
docs/api/features/files.md
Normal file
44
docs/api/features/files.md
Normal file
|
@ -0,0 +1,44 @@
|
||||||
|
# File Repository
|
||||||
|
|
||||||
|
## Endpoints
|
||||||
|
|
||||||
|
### Get a file by identifier
|
||||||
|
|
||||||
|
`GET {base URL}/v2/files/:namespace/:addon/:version/:qualifier`
|
||||||
|
|
||||||
|
This endpoint can be used to retrieve information about a specific file.
|
||||||
|
If the instance don't know this file, it MUST respond with status code 404.
|
||||||
|
|
||||||
|
#### Path variables:
|
||||||
|
|
||||||
|
- `namespace`: The [canonical namespace](../../concepts/namespaces.md#canonical-namespaces)
|
||||||
|
of the addon to which the file belongs to
|
||||||
|
- `addon`: The addon ID of the addon to which the file belongs to
|
||||||
|
- `version`: The addon version to which the file belongs to
|
||||||
|
- `qualifier`: The qualifier of the file
|
||||||
|
|
||||||
|
#### Responses:
|
||||||
|
|
||||||
|
- `200 OK`: The file is available in this file repository.
|
||||||
|
The response body MUST be an [API File Object](../../schema/api_file.md).
|
||||||
|
- `404 Not Found`: The file is not available in this file repository.
|
||||||
|
|
||||||
|
### Get a file by hash
|
||||||
|
|
||||||
|
`GET {base URL}/v2/files/:algorithm/:hash`
|
||||||
|
|
||||||
|
This endpoint can be used to retrieve information about a file from the hash value of the file.
|
||||||
|
If the instance can't find the file by the hash or does not know the specified hash algorithm,
|
||||||
|
it MUST respond with status code 404.
|
||||||
|
|
||||||
|
#### Path variables:
|
||||||
|
|
||||||
|
- `algorithm`: The hash algorithm of the hash
|
||||||
|
- `hash`: The hash value of the file
|
||||||
|
|
||||||
|
#### Responses:
|
||||||
|
|
||||||
|
- `200 OK`: The file is available in this file repository.
|
||||||
|
The response body MUST be an [API File Object](../../schema/api_file.md).
|
||||||
|
- `404 Not Found`: The file is either not available in this file repository
|
||||||
|
or the hash algorithm is unknown to the API instance.
|
|
@ -1,38 +1,58 @@
|
||||||
# Flags
|
# 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/addon.md), a [file](../schema/file.md) or
|
## Manifest flags
|
||||||
a [relation](../schema/relation.md) was made.
|
|
||||||
|
|
||||||
- `client` This flag specifies, that the version, relation or file can be installed on the client side
|
- `required` This flag specifies, that the addon of the manifest is required on the side which has this flag set,
|
||||||
- `server` This flag specifies, that the version, relation or file can be installed on the server side
|
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
|
||||||
## Version flags
|
`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,
|
||||||
These are flags, which can be set for [versions](../schema/addon.md).
|
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.
|
||||||
- `instance` This flag specifies, that this is a version of an instance addon. Instance addons represent instances of
|
If a side has this flag, this side will completly be ignored for the manifest.
|
||||||
Minecraft itself, while non-instance addons have to be installed into an existing instance of Minecraft.
|
|
||||||
|
|
||||||
## Relational flags
|
## 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,
|
- `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,
|
- `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. This flag
|
the user SHOULD be able to choose, whether he wants to install the relation or file with this flag, or not.
|
||||||
can be used in combination with the [conditions](../schema/conditions.md) property.
|
- `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.
|
||||||
### Relation specific
|
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
|
||||||
These are relational flags, which can only be used for [relations](../schema/relation.md).
|
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.
|
||||||
- `included` This flag specifies, that the related addon is included in this one. This also means, that if some
|
- `incompatible` This flag specifies for a relation, that the related addon is incompatible to this one, which means,
|
||||||
addon requires the related addon, it can also be installed with this addon instead.
|
that they can't be installed together in the same instance. For a file this flag specifies, that the file can't be
|
||||||
- `incompatible` This flag specifies, that the related addon is incompatible to this one. This means, that they can't
|
installed on the side which has this flag set.
|
||||||
be installed together in the same instance.
|
- `launch` This flag is only valid for relations and files of [instance addons](instance.md). For relations, it specifies,
|
||||||
- `launch` This flag specifies, that the related addon should take care of the Minecraft launch process. It can only
|
that the [launch patches](../schema/patch.md) from the related addon (which MUST also be an instance addon) will also be
|
||||||
be used, if both this and the related addon are instance addons.
|
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` (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).
|
||||||
|
It is used together with the `required` or `optional` flag to specify, which addons are required for the launch
|
||||||
|
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.
|
||||||
|
- `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.
|
|
@ -1,21 +1,20 @@
|
||||||
# File installing
|
# File installing
|
||||||
|
|
||||||
## Install commands
|
## Install actions
|
||||||
|
|
||||||
### move
|
### move
|
||||||
|
|
||||||
args:
|
args:
|
||||||
|
|
||||||
- `[location]`
|
- `<location>`
|
||||||
|
|
||||||
`move` is simplest install step of all. It just moves the selected file to
|
`move` moves the file to the given location.
|
||||||
the given location.
|
|
||||||
|
|
||||||
### extract
|
### extract
|
||||||
|
|
||||||
args:
|
args:
|
||||||
|
|
||||||
- `[location]`
|
- `<location>`
|
||||||
|
|
||||||
`extract` can be used with zip files, to extract the contents of the zip file
|
`extract` can be used with zip files, to extract the contents of the zip file
|
||||||
to the given location.
|
to the given location.
|
||||||
|
@ -24,46 +23,38 @@ to the given location.
|
||||||
|
|
||||||
args:
|
args:
|
||||||
|
|
||||||
- `[new name]`
|
- `<new name>`
|
||||||
|
|
||||||
`rename` renames the selected file to the new given filename.
|
`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
|
||||||
|
|
||||||
`inject` can be used with zip or jar files, to inject the contents of that file
|
`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.
|
into the server launch jar on server side or into the client jar on client side.
|
||||||
In contrast to libraries, `inject` will not add that file to the classpath, but
|
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
|
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).
|
||||||
|
|
||||||
### launch
|
|
||||||
|
|
||||||
`launch` can be used to mark the selected file as the launch file for a specific side. Files having this
|
|
||||||
install step 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 step may only be used with launchable or instance addons and there may be only one file for each
|
|
||||||
side, which has this install step, except all of them are marked as `optional`, in which case they are also
|
|
||||||
implicitly marked as incompatible to each other.
|
|
||||||
|
|
||||||
### select
|
|
||||||
|
|
||||||
args:
|
|
||||||
|
|
||||||
- `[filename]`
|
|
||||||
|
|
||||||
`select` is used to select the file with the given file name for other installation steps.
|
|
||||||
The file name can also be a relative path, if the file is not directly in the Minecraft directory.
|
|
||||||
If no file name is given, the selection resets to the original file itself, also if it was already moved to another location.
|
|
||||||
|
|
||||||
## Locations
|
## Locations
|
||||||
|
|
||||||
Locations are specified as a relative path from the Minecraft directory to which the file should be installed.
|
Locations are specified as a relative path from the Minecraft directory to which the file will be installed.
|
||||||
For example `./mods` would point to the mods directory of the Minecraft instance.
|
For example `./mods` would point to the mods directory of the Minecraft instance.
|
||||||
|
|
||||||
## Directories
|
## Directories
|
||||||
|
|
||||||
If the selected file is a directory, then it is treated like a zip file, which means, that you can move and
|
If the file is a directory, then it is treated like a zip file, which means, that you can move and
|
||||||
rename it like a normal file, but also use the `extract` install step to move all contents of the directory
|
rename it like a normal file, but also use the `extract` install action to move all contents of the directory
|
||||||
to the specified location.
|
to the specified location.
|
||||||
|
|
47
docs/concepts/instance.md
Normal file
47
docs/concepts/instance.md
Normal file
|
@ -0,0 +1,47 @@
|
||||||
|
# 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 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 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.
|
||||||
|
|
||||||
|
## Launch configurations
|
||||||
|
|
||||||
|
Instance launch configurations are always based on a
|
||||||
|
[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) 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 [patches array](../schema/manifest.md#patches)
|
||||||
|
in the order, in which they are specified in the array.
|
||||||
|
|
||||||
|
## 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.
|
|
@ -1,6 +1,6 @@
|
||||||
# Links
|
# Links
|
||||||
|
|
||||||
AddonScript uses links to point to specific files. AddonScript specifies three link types, which can be used
|
AddonScript uses links to point to specific files. AddonScript specifies two link types, which can be used
|
||||||
to point to files.
|
to point to files.
|
||||||
|
|
||||||
## http(s)
|
## http(s)
|
||||||
|
@ -14,5 +14,5 @@ a file on a http server.
|
||||||
|
|
||||||
`./relative/path/to/file.jar`
|
`./relative/path/to/file.jar`
|
||||||
|
|
||||||
This is a relative path to a file. It can only be used with [packaging](../packaging/README.md)
|
This is a relative path to a file. It can only be used with [packaging](../packaging)
|
||||||
or in some third-party environments, which are not covered by this specification.
|
or in some third-party environments, which are not covered by this specification.
|
||||||
|
|
69
docs/concepts/minecraft.md
Normal file
69
docs/concepts/minecraft.md
Normal file
|
@ -0,0 +1,69 @@
|
||||||
|
# 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. 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.
|
||||||
|
|
||||||
|
## 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 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 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 it also provides an asset index, which SHOULD be used by
|
||||||
|
implementations to retrieve game assets (if they are not already cached).
|
|
@ -1 +1,33 @@
|
||||||
# Namespaces
|
# Namespaces
|
||||||
|
|
||||||
|
Namespaces are used in conjunction with addon IDs to uniquely identify an addon as well as
|
||||||
|
an identifier for repositories.
|
||||||
|
|
||||||
|
## Format
|
||||||
|
|
||||||
|
Namespaces MUST only contain lowercase alphanumeric characters, hyphens (SHOULD be avoided) and dots.
|
||||||
|
They SHOULD be in a reversed domain name format. A namespace SHOULD specify the distribution source
|
||||||
|
(i.e. `com.example.repository`) or the author (i.e. `com.author.website`) of the addon and
|
||||||
|
optionally also the addon type (i.e. `com.example.repository.mods`, `com.author.website.modpacks`).
|
||||||
|
|
||||||
|
## Repository Namespaces
|
||||||
|
|
||||||
|
A repository namespace describes an addon repository across [API instances](../api/). A repository
|
||||||
|
contains different addons and MAY be hosted on multiple API instances (mirrors). The ID of an addon
|
||||||
|
MUST be unique in a repository, so an addon can be resolved by the addon ID in conjuction with the
|
||||||
|
repository namespace. Since the same addon MAY be contained in multiple repositories, it MUST have a
|
||||||
|
[canonical namespace](#canonical-namespaces), so it can be identified globally. The repository
|
||||||
|
described by the canonical namespace of an addon MUST also contain that addon. If different API
|
||||||
|
instances return contradicting information about a repository, for example an addon with the same
|
||||||
|
ID in the same repository has different canonical namespaces on different instances, the AddonScript
|
||||||
|
implementation decides, which instance is more trustworthy. This MAY be done by comparing the
|
||||||
|
repository namespace to the API URL or by asking the user.
|
||||||
|
|
||||||
|
## Canonical Namespaces
|
||||||
|
|
||||||
|
While an addon MAY be included in multiple repository namespaces, it MUST have exactly
|
||||||
|
one canonical namespace, which is defined in the [addon manifest](../schema/manifest.md#namespace).
|
||||||
|
An [API instance](../api/) MUST also return the canonical namespace of
|
||||||
|
the addon on the [addon endpoint](../api/features/addons.md#get-addon)
|
||||||
|
even if the addon was requested from another repository namespace. To check, if two addons
|
||||||
|
are the same addon, their canonical namespace and their ID MUST be equal.
|
|
@ -1,7 +1,28 @@
|
||||||
# AddonScript Versioning
|
# AddonScript Versioning
|
||||||
|
|
||||||
Version numbers in AddonScript are based on Maven version numbers. The only difference to the Maven versioning specification is,
|
## AddonScript Version Numbers
|
||||||
that AddonScript version numbers may only contain non-space ASCII characters.
|
|
||||||
|
AddonScript version numbers MUST only contain non-whitespace ASCII characters. They SHOULD follow the
|
||||||
|
[SemVer specifications](https://semver.org/spec/v2.0.0.html). AddonScript version numbers are ordered
|
||||||
|
according to the [Maven version order specification](#version-order-specification).
|
||||||
|
|
||||||
|
### SemVer Compatible Versions
|
||||||
|
|
||||||
|
If an AddonScript version number is valid SemVer, that version of the addon is SemVer compatible and implies
|
||||||
|
all semantics according to SemVer. AddonScript implementations MAY provide specific behavior based on the
|
||||||
|
semver semantics, for example warning the user before updating to a next major version.
|
||||||
|
|
||||||
|
## AddonScript Version Ranges
|
||||||
|
|
||||||
|
An AddonScript version range can either be a [SemVer version range](https://github.com/semver/semver/pull/584)
|
||||||
|
or a [Maven version range](#dependency-version-requirement-specification). If a version range starts with one
|
||||||
|
of SemVer primitive operators (`<`, `<=`, `>`, `>=`, `=`) it will be considered as a SemVer version range,
|
||||||
|
otherwise it will be a Maven version range. SemVer version ranges can only include
|
||||||
|
[SemVer compatible versions](#semver-compatible-versions). If the version range is required to include
|
||||||
|
an exact version, for example when using the `included` [relational flag](./flags.md#relational-flags),
|
||||||
|
it MUST be a Maven soft requirement, which is equal to the targeted version. In all other cases
|
||||||
|
it is highly RECOMMENDED to use SemVer version ranges, as long as the targeted addon uses
|
||||||
|
[SemVer compatible versions](#semver-compatible-versions).
|
||||||
|
|
||||||
## Maven Versioning Specification
|
## Maven Versioning Specification
|
||||||
|
|
||||||
|
@ -50,7 +71,7 @@ End Result Examples:
|
||||||
|
|
||||||
Note: Contrary to what was stated in some design documents, for version order, snapshots are not treated differently than releases or any other qualifier.
|
Note: Contrary to what was stated in some design documents, for version order, snapshots are not treated differently than releases or any other qualifier.
|
||||||
|
|
||||||
### Dependancy Version Requirement Specification
|
### Dependency Version Requirement Specification
|
||||||
|
|
||||||
Version requirements have the following syntax:
|
Version requirements have the following syntax:
|
||||||
|
|
||||||
|
|
|
@ -1,8 +1,7 @@
|
||||||
# Zip Packaging
|
# Zip Packaging
|
||||||
|
|
||||||
With zip packaging, the AddonScript file and the associated files are contained in
|
With zip packaging, the AddonScript file and the associated files are contained in
|
||||||
a zip file. The AddonScript file has to be called `addon.json` and can either be placed
|
a zip file. The AddonScript file MUST be named `manifest.json` and MUST be placed
|
||||||
at the root of the zip file or, if there is just one directory in the root of the zip file,
|
at the root of the zip file. All files and directories inside the zip file can be
|
||||||
in this directory. All files and directories inside the zip file can be accessed from AddonScript
|
accessed from AddonScript using the [file links](../concepts/links.md#file).
|
||||||
using the [file links](../concepts/links.md#file). The path from the file URL is relative to the location of
|
The path from the file URL is relative to the location of the AddonScript file.
|
||||||
the AddonScript file.
|
|
||||||
|
|
|
@ -1,66 +0,0 @@
|
||||||
# Addon Object
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"addonscript": {},
|
|
||||||
"id": "myaddon",
|
|
||||||
"namespace": "com.example",
|
|
||||||
"version": "1.0",
|
|
||||||
"semver": "1.0.0",
|
|
||||||
"files": [],
|
|
||||||
"relations": [],
|
|
||||||
"flags": ["server", "client"],
|
|
||||||
"repositories": [],
|
|
||||||
"meta": {}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Required properties
|
|
||||||
|
|
||||||
### addonscript
|
|
||||||
|
|
||||||
This is an [AddonScript object](addonscript.md) containing information about the version of AddonScript used in this file.
|
|
||||||
|
|
||||||
### id
|
|
||||||
|
|
||||||
This is the ID of the addon.
|
|
||||||
|
|
||||||
It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces.
|
|
||||||
|
|
||||||
### version
|
|
||||||
|
|
||||||
This is the [version number](../concepts/versioning.md) of this version. Versions are compared by
|
|
||||||
[Maven version order rules](../concepts/versioning.md#version-order-specification).
|
|
||||||
If this version number is valid semver, the `semver` property is implicitly equal to `version` if `semver` was not explicitly set.
|
|
||||||
|
|
||||||
## Optional properties
|
|
||||||
|
|
||||||
### semver
|
|
||||||
|
|
||||||
This is the version number of this version in semver format. It must follow the [semver versioning specifications](https://semver.org/spec/v2.0.0.html).
|
|
||||||
|
|
||||||
### namespace
|
|
||||||
|
|
||||||
This is the [namespace](../concepts/namespaces.md) of the addon, which should be in a reversed domain name format.
|
|
||||||
Used to identify addons across repositories.
|
|
||||||
|
|
||||||
### files
|
|
||||||
|
|
||||||
This is an array of [file objects](file.md) including the files belonging to this addon.
|
|
||||||
|
|
||||||
### relations
|
|
||||||
|
|
||||||
This is an array of [relation objects](relation.md) which represent addons in relation to this one.
|
|
||||||
|
|
||||||
### flags
|
|
||||||
|
|
||||||
This is an array of [flags](../concepts/flags.md) for this version.
|
|
||||||
|
|
||||||
### repositories
|
|
||||||
|
|
||||||
This is an array of [repository objects](repository.md). Each repository object defines one repository from which files or
|
|
||||||
addons can be retrieved.
|
|
||||||
|
|
||||||
### meta
|
|
||||||
|
|
||||||
This is a [meta object](meta.md) containing metadata about the addon.
|
|
39
docs/schema/api_addon.md
Normal file
39
docs/schema/api_addon.md
Normal file
|
@ -0,0 +1,39 @@
|
||||||
|
# API Addon Object
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "myaddon",
|
||||||
|
"namespace": "com.example",
|
||||||
|
"meta": {
|
||||||
|
"addon": {},
|
||||||
|
"additional": {}
|
||||||
|
},
|
||||||
|
"versions": [
|
||||||
|
"1.0"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Required properties
|
||||||
|
|
||||||
|
### id
|
||||||
|
|
||||||
|
This is the ID of the addon.
|
||||||
|
|
||||||
|
It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the `kebab-case` format.
|
||||||
|
|
||||||
|
### namespace
|
||||||
|
|
||||||
|
This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the addon.
|
||||||
|
|
||||||
|
### versions
|
||||||
|
|
||||||
|
This is an array of all [version numbers](../concepts/versioning.md) of this addon, which are
|
||||||
|
available on this API instance.
|
||||||
|
|
||||||
|
## Optional properties
|
||||||
|
|
||||||
|
### meta
|
||||||
|
|
||||||
|
This is a [meta object](meta.md) containing metadata about the addon. It does not
|
||||||
|
contain any version specific metadata.
|
24
docs/schema/api_addon_descriptor.md
Normal file
24
docs/schema/api_addon_descriptor.md
Normal file
|
@ -0,0 +1,24 @@
|
||||||
|
# Addon Descriptor Object
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "addonid",
|
||||||
|
"namespace": "com.example",
|
||||||
|
"version": "1.0.0"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Required properties
|
||||||
|
|
||||||
|
### id
|
||||||
|
|
||||||
|
This is the [ID](manifest.md#id) of the addon which this object describes.
|
||||||
|
|
||||||
|
### namespace
|
||||||
|
|
||||||
|
This is the [namespace](../concepts/namespaces.md) of the addon which this object describes.
|
||||||
|
It MUST be the [canonical namespace](../concepts/namespaces.md#canonical-namespaces).
|
||||||
|
|
||||||
|
### version
|
||||||
|
|
||||||
|
This is the [version](manifest.md#version) of the addon.
|
56
docs/schema/api_builder_request.md
Normal file
56
docs/schema/api_builder_request.md
Normal file
|
@ -0,0 +1,56 @@
|
||||||
|
# Environment Builder Request Object
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"addonscript": {},
|
||||||
|
"addon": {},
|
||||||
|
"client": {},
|
||||||
|
"server": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Required properties
|
||||||
|
|
||||||
|
### addonscript
|
||||||
|
|
||||||
|
This is an [AddonScript object](addonscript.md) containing information about the version of AddonScript used in this request.
|
||||||
|
It SHOULD be equal to the [addonscript Property](manifest.md#addonscript) of the [manifest](manifest.md) from which the request
|
||||||
|
was send.
|
||||||
|
|
||||||
|
### addon
|
||||||
|
|
||||||
|
This is an [addon descriptor object](api_addon_descriptor.md), which contains the [addon ID](manifest.md#id),
|
||||||
|
[canonical namespace](manifest.md#namespace) and [version](manifest.md#version) of the addon, for which the
|
||||||
|
launch environment will be build.
|
||||||
|
|
||||||
|
## Optional properties
|
||||||
|
|
||||||
|
### client
|
||||||
|
|
||||||
|
This is an [environment object](#environment-object) containing information about the client environment.
|
||||||
|
|
||||||
|
### server
|
||||||
|
|
||||||
|
This is an [environment object](#environment-object) containing information about the server environment.
|
||||||
|
|
||||||
|
# Environment Object
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"requested": [],
|
||||||
|
"provided": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Optional properties
|
||||||
|
|
||||||
|
### requested
|
||||||
|
|
||||||
|
This is an array of [addon descriptor objects](api_addon_descriptor.md) which contains all addons, that will
|
||||||
|
be part of the launch environment, including their version.
|
||||||
|
|
||||||
|
### provided
|
||||||
|
|
||||||
|
This is an array of [addon descriptor objects](api_addon_descriptor.md) which contains all addons from the
|
||||||
|
[relations](manifest.md#relations) of the [addon](#addon), from which the request was send, that will be installed
|
||||||
|
in the instance, including their version
|
32
docs/schema/api_builder_response.md
Normal file
32
docs/schema/api_builder_response.md
Normal file
|
@ -0,0 +1,32 @@
|
||||||
|
# Environment Builder Response Object
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"addonscript": {},
|
||||||
|
"files": [],
|
||||||
|
"launch_client": {},
|
||||||
|
"launch_server": {},
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Required properties
|
||||||
|
|
||||||
|
### addonscript
|
||||||
|
|
||||||
|
This is an [AddonScript object](addonscript.md) containing information about the version of AddonScript used in this response.
|
||||||
|
It MUST be equal to the [addonscript Property](api_builder_request.md#addonscript) of the [request](api_builder_request.md).
|
||||||
|
|
||||||
|
### 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).
|
||||||
|
|
||||||
|
## Optional properties
|
||||||
|
|
||||||
|
### launch_client
|
||||||
|
|
||||||
|
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](./patch.md) for the server, which can be used, to modify the launch configuration of the instance.
|
34
docs/schema/api_file.md
Normal file
34
docs/schema/api_file.md
Normal file
|
@ -0,0 +1,34 @@
|
||||||
|
# API File Object
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"src": ["https://example.com/file.jar"],
|
||||||
|
"hashes": {
|
||||||
|
"sha1": "somesha1checksum"
|
||||||
|
},
|
||||||
|
"meta": {
|
||||||
|
"additional": {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Required properties
|
||||||
|
|
||||||
|
### src
|
||||||
|
|
||||||
|
This is an array of [links](../concepts/links.md), which are pointing to the actual file. These MUST be a http(s) links.
|
||||||
|
All of these links MUST have the same file type.
|
||||||
|
|
||||||
|
## Optional properties
|
||||||
|
|
||||||
|
### hashes
|
||||||
|
|
||||||
|
This is an object with checksums for this file. The object contains key-value-pairs where the key is the hash algorithm and the
|
||||||
|
value is the checksum.
|
||||||
|
|
||||||
|
Supported hash algorithms:
|
||||||
|
- `sha1`
|
||||||
|
|
||||||
|
### meta
|
||||||
|
|
||||||
|
This is a [meta object](meta.md) containing metadata about the file. it SHOULD only contain [additional metadata](meta.md#additional).
|
|
@ -1,154 +0,0 @@
|
||||||
# Conditions Object
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"require": ["some-addon"],
|
|
||||||
"companion": ["another-addon"],
|
|
||||||
"exclude": ["incompatible-addon"]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Optional properties
|
|
||||||
|
|
||||||
All addons in the arrays are specified as addon IDs or namespaced addon IDs. They all need to be specified
|
|
||||||
as optional relations in this version.
|
|
||||||
|
|
||||||
### require
|
|
||||||
|
|
||||||
This is an array of addon IDs, which are required for this relation or file and must be present.
|
|
||||||
|
|
||||||
### companion
|
|
||||||
|
|
||||||
This is an array of addon IDs which go together with this relation/file.
|
|
||||||
This field is fairly complex.
|
|
||||||
|
|
||||||
The `companion` field is used to represent a relation between an optional file/relation, and an optional relation.
|
|
||||||
This means, if one of them isn't optional, an error occurs.
|
|
||||||
|
|
||||||
The behaviour can be summarized as such:
|
|
||||||
|
|
||||||
1. The relation/file that declares companions is only installed if all companions are also installed.
|
|
||||||
2. A relation that is a companion also will not be installed, unless **all** files/relations of that
|
|
||||||
relation declare it as a companion are also installed.
|
|
||||||
|
|
||||||
This can be described as the relation and the relation/file that is a companion of the relation requiring **eachother**.
|
|
||||||
The reason this isn't done by declaring a `require` condition both on the addon/file and the file, is that files
|
|
||||||
cannot be referenced, as only addon-ids are used.
|
|
||||||
|
|
||||||
<!--this table has to be in HTML and without indentation to allow markdown code blocks-->
|
|
||||||
<table>
|
|
||||||
<thead>
|
|
||||||
<tr>
|
|
||||||
<th>Name</th>
|
|
||||||
<th>Type</th>
|
|
||||||
<th>Installed if</th>
|
|
||||||
<th>Flags</th>
|
|
||||||
<th>Conditions</th>
|
|
||||||
</tr>
|
|
||||||
</thead>
|
|
||||||
<tbody>
|
|
||||||
<tr>
|
|
||||||
<td>companion-relation</td>
|
|
||||||
<td>relation</td>
|
|
||||||
<td><em>example-file</em> is installed</td>
|
|
||||||
<td>
|
|
||||||
|
|
||||||
```json
|
|
||||||
["optional"]
|
|
||||||
```
|
|
||||||
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
|
|
||||||
```json
|
|
||||||
{}
|
|
||||||
```
|
|
||||||
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>example-file</td>
|
|
||||||
<td>file</td>
|
|
||||||
<td><em>companion-relation</em> is installed</td>
|
|
||||||
<td>
|
|
||||||
|
|
||||||
```json
|
|
||||||
["optional"]
|
|
||||||
```
|
|
||||||
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
|
|
||||||
<!-- prettier-ignore -->
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"companion": [
|
|
||||||
"companion-relation"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
</tbody>
|
|
||||||
</table>
|
|
||||||
|
|
||||||
An example of this would be to present alternative files for different modloaders in the case of a mod.
|
|
||||||
Let's consider this example addon:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"addonscript": { "version": 2 },
|
|
||||||
"id": "example-addon",
|
|
||||||
"version": "0.1.0",
|
|
||||||
"relations": [
|
|
||||||
{
|
|
||||||
"id": "forge",
|
|
||||||
"version": "37.0",
|
|
||||||
"flags": ["optional"]
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": "fabric",
|
|
||||||
"version": "9.0",
|
|
||||||
"flags": ["optional"]
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": "fabric-api",
|
|
||||||
"version": "0.42.1",
|
|
||||||
"flags": ["optional"],
|
|
||||||
"conditions": {
|
|
||||||
"companion": ["fabric"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"files": [
|
|
||||||
{
|
|
||||||
"id": "example-addon-forge",
|
|
||||||
"url": "./example_addon_forge.jar",
|
|
||||||
"conditions": {
|
|
||||||
"companion": ["forge"]
|
|
||||||
},
|
|
||||||
"flags": ["optional"]
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": "example-addon-fabric",
|
|
||||||
"url": "./example_addon_fabric.jar",
|
|
||||||
"conditions": {
|
|
||||||
"companion": ["fabric"]
|
|
||||||
},
|
|
||||||
"flags": ["optional"]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
This example addon provides files for forge and fabric, the files both having their
|
|
||||||
respective modloaders as companions. This allows a mod to ship files for both modloaders
|
|
||||||
without using different addons.
|
|
||||||
|
|
||||||
Also note that the addon also adds the `fabric` relation to the `fabric-api` relation.
|
|
||||||
Thus it will also be installed if the fabric version of the mod is used.
|
|
||||||
|
|
||||||
### exclude
|
|
||||||
|
|
||||||
This is an array of addon IDs, which can't be installed together with this relation or file.
|
|
|
@ -2,66 +2,56 @@
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "modfile",
|
"qualifier": "modfile",
|
||||||
"link": ["https://example.com/mymod.jar", "./mymod.jar"],
|
"src": ["https://example.com/mymod.jar", "./mymod.jar"],
|
||||||
"flags": [],
|
"flags": {},
|
||||||
"maven": {},
|
|
||||||
"install": [],
|
"install": [],
|
||||||
"sha1": "somesha1checksum",
|
"hashes": {
|
||||||
"conditions": {}
|
"sha1": "somesha1checksum"
|
||||||
|
},
|
||||||
|
"meta": {}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Required properties
|
## Required properties
|
||||||
|
|
||||||
### id
|
### qualifier
|
||||||
|
|
||||||
This is the ID of the file.
|
This is the qualifier of this file.
|
||||||
It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces.
|
It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the `kebab-case` format.
|
||||||
The file ID has to be unique to this addon version.
|
The qualifier has to be unique to this addon version. The namespace, addon ID, version and qualifier
|
||||||
|
can together be used to uniquely identify a file.
|
||||||
|
|
||||||
### link
|
### src
|
||||||
|
|
||||||
This is an array of [links](../concepts/links.md), which are pointing to the actual file. All of these links must
|
This is an array of [links](../concepts/links.md), which are pointing to the actual file. All of these links must
|
||||||
have the same file type. Since AddonScript treats directories and zip files equally,
|
have the same file type. Since AddonScript treats directories and zip files equally,
|
||||||
they can be mixed in the same link array. When downloading the file,
|
they can be mixed in the same link array. When downloading the file,
|
||||||
the first link in this array should be used with the other links as fallback, if the first doesn't work.
|
the first link in this array SHOULD be used with the other links as fallback, if the first doesn't work.
|
||||||
If none of the specified links works, the file should be downloaded by it's Maven
|
If none of the specified links works or the array is empty, the file link SHOULD be retrieved by it's identifier
|
||||||
specifier from one of the specified repository, but only, if a `sha1` hash is specified, so that it can be
|
from one of the [repositories](repository.md), but only, if a `sha1` hash is specified, so that it can be
|
||||||
verified, that the downloaded file is correct.
|
verified, that the downloaded file is correct.
|
||||||
|
|
||||||
## Optional properties
|
## Optional properties
|
||||||
|
|
||||||
### install
|
### install
|
||||||
|
|
||||||
This is an array of [install objects](install.md). They describe how the file should be installed to the game.
|
This is an array of [install objects](install.md). They describe how the file will be installed to the game.
|
||||||
The order in the array corresponds to the order in which the installation steps should be applied.
|
The order in the array corresponds to the order in which the installation steps will be applied.
|
||||||
|
|
||||||
### flags
|
### 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 use the default flags.
|
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.
|
||||||
|
|
||||||
### sha1
|
### hashes
|
||||||
|
|
||||||
This is the sha1 checksum of the file. Although the checksum is optional, it is strongly recommended.
|
This is an object with checksums for this file. The object contains key-value-pairs where the key is the hash algorithm and the
|
||||||
|
value is the checksum.
|
||||||
|
|
||||||
### conditions
|
Supported hash algorithms:
|
||||||
|
- `sha1`
|
||||||
|
|
||||||
This is a [conditions object](conditions.md). It can only be used, if the [optional flag](../concepts/flags.md) was set.
|
### meta
|
||||||
|
|
||||||
### maven
|
This is a [meta object](meta.md) containing metadata about the file. it SHOULD only contain [additional metadata](meta.md#additional).
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"group": "com.example",
|
|
||||||
"artifact": "mymod",
|
|
||||||
"version": "1.0",
|
|
||||||
"qualifier": ""
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Each file has a unique Maven specifier, consisting of a group ID, an artifact ID, a version, a file type and an optional qualifier.
|
|
||||||
By default, the group ID is equal to the addon namespace, the artifact ID to the addon ID, the version to the addon version and
|
|
||||||
the qualifier to file ID. Those values can be overwritten in this object. If the qualifier is set to an empty string, it will be
|
|
||||||
removed from the Maven specifier. The file type is always equal to the file type of the `link`. If the group ID, addon ID and version
|
|
||||||
all have their default values and the qualifier is an emptry string, the file type may not be `json`.
|
|
24
docs/schema/flags.md
Normal file
24
docs/schema/flags.md
Normal file
|
@ -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).
|
|
@ -2,19 +2,25 @@
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"command": "move",
|
"action": "move",
|
||||||
"args": ["./mods"]
|
"args": ["./mods"],
|
||||||
|
"side": "both"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Required properties
|
## Required properties
|
||||||
|
|
||||||
### command
|
### action
|
||||||
|
|
||||||
This is the [install command](../concepts/install.md), which should be used at this installation step.
|
This is the [install action](../concepts/install.md), which will be used at this installation step.
|
||||||
|
|
||||||
## Optional properties
|
## Optional properties
|
||||||
|
|
||||||
### args
|
### args
|
||||||
|
|
||||||
This is an array of arguments for the [install command](../concepts/install.md). Each of them takes other arguments.
|
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`.
|
||||||
|
|
81
docs/schema/manifest.md
Normal file
81
docs/schema/manifest.md
Normal file
|
@ -0,0 +1,81 @@
|
||||||
|
# Addon Manifest Object
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"addonscript": {},
|
||||||
|
"id": "myaddon",
|
||||||
|
"namespace": "com.example",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"files": [],
|
||||||
|
"relations": [],
|
||||||
|
"flags": {},
|
||||||
|
"repositories": [],
|
||||||
|
"instance": false,
|
||||||
|
"use_builder": false,
|
||||||
|
"patches": [],
|
||||||
|
"meta": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Required properties
|
||||||
|
|
||||||
|
### addonscript
|
||||||
|
|
||||||
|
This is an [AddonScript object](addonscript.md) containing information about the version of AddonScript used in this file.
|
||||||
|
|
||||||
|
### id
|
||||||
|
|
||||||
|
This is the ID of the addon.
|
||||||
|
|
||||||
|
It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the `kebab-case` format.
|
||||||
|
|
||||||
|
### version
|
||||||
|
|
||||||
|
This is the [AddonScript version number](../concepts/versioning.md#addonscript-version-numbers) of this version.
|
||||||
|
|
||||||
|
### namespace
|
||||||
|
|
||||||
|
This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the addon.
|
||||||
|
|
||||||
|
### flags
|
||||||
|
|
||||||
|
This is an [flags object](flags.md) which contains [manifest flags](../concepts/flags.md#manifest-flags) for both sides for this manifest.
|
||||||
|
|
||||||
|
## Optional properties
|
||||||
|
|
||||||
|
### files
|
||||||
|
|
||||||
|
This is an array of [file objects](file.md) including the files belonging to this addon.
|
||||||
|
|
||||||
|
### relations
|
||||||
|
|
||||||
|
This is an array of [relation objects](relation.md) which represent addons in relation to this one.
|
||||||
|
|
||||||
|
### repositories
|
||||||
|
|
||||||
|
This is an array of [repository objects](repository.md). Each repository object defines one repository from which files or
|
||||||
|
addons can be retrieved. Each AddonScript manifest SHOULD have a repository for the [canonical namespace](#namespace) of
|
||||||
|
that manifest, from which AddonScript implementations MAY check for updates for this addon. If [use_builder](#use_builder) is `true`,
|
||||||
|
this addon MUST have such a repository to provide API instances, which can be used to request the
|
||||||
|
[launch environment](../api/features/builder.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`.
|
||||||
|
|
||||||
|
### use_builder
|
||||||
|
|
||||||
|
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`. (DEPRECATED)
|
||||||
|
|
||||||
|
### patches
|
||||||
|
|
||||||
|
This is an array of [patch object](patch.md) which can be used to modify t
|
||||||
|
he 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.
|
|
@ -41,17 +41,17 @@ This object can contain any arbitrary data,
|
||||||
|
|
||||||
### name
|
### name
|
||||||
|
|
||||||
The full, human-readable name of the addon. This is what a program such as a launcher should
|
The full, human-readable name of the addon. This is what a program such as a launcher SHOULD
|
||||||
display to the user.
|
display to the user.
|
||||||
|
|
||||||
### icon
|
### icon
|
||||||
|
|
||||||
A [link](../concepts/links.md) to the icon of the addon. This path should point to an image file of small resolution
|
A [link](../concepts/links.md) to the icon of the addon. This path SHOULD point to an image file of small resolution
|
||||||
which is ideally square. It can be dispayed to users in programs.
|
which is ideally square. It MAY be dispayed to users in programs.
|
||||||
|
|
||||||
### description
|
### description
|
||||||
|
|
||||||
A [link](../concepts/links.md) to a description file for the addon. The file should be in CommonMark markdown.
|
A [link](../concepts/links.md) to a description file for the addon. The file SHOULD be in CommonMark markdown.
|
||||||
|
|
||||||
### summary
|
### summary
|
||||||
|
|
||||||
|
@ -75,7 +75,8 @@ The type of the addon, for example `mod`, `modpack` or `resourcepack`.
|
||||||
|
|
||||||
### contributors
|
### contributors
|
||||||
|
|
||||||
An array of people who have contributed to the addon.
|
An array of people who have contributed to the addon. Each contributor is represented by an object, which
|
||||||
|
MUST have a `name` and a `email` property.
|
||||||
|
|
||||||
# Version Meta Object
|
# Version Meta Object
|
||||||
|
|
||||||
|
|
98
docs/schema/patch.md
Normal file
98
docs/schema/patch.md
Normal file
|
@ -0,0 +1,98 @@
|
||||||
|
# Launch Patch Object
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"side": "client",
|
||||||
|
"main_class": "com.example.SomeClass",
|
||||||
|
"arguments": [],
|
||||||
|
"jvm_arguments": ["-Djvmargument"],
|
||||||
|
"replace_jvm_arguments": false,
|
||||||
|
"java_version": 8
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Required properties
|
||||||
|
|
||||||
|
### side
|
||||||
|
|
||||||
|
This specifies, for which side this patch should be applied. Valid values are `client`, `server` and `both`.
|
||||||
|
|
||||||
|
## 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`.
|
|
@ -6,8 +6,7 @@
|
||||||
"namespace": "com.example",
|
"namespace": "com.example",
|
||||||
"version": "[1.0]",
|
"version": "[1.0]",
|
||||||
"repositories": ["repo1"],
|
"repositories": ["repo1"],
|
||||||
"flags": [],
|
"flags": {}
|
||||||
"conditions": {}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
@ -17,33 +16,27 @@
|
||||||
|
|
||||||
This is the ID of the addon this relation refers to.
|
This is the ID of the addon this relation refers to.
|
||||||
|
|
||||||
|
### version
|
||||||
|
|
||||||
|
This is an [AddonScript version range](../concepts/versioning.md#addonscript-version-ranges) that specifies, which versions
|
||||||
|
of the related addon are targeted by this relation.
|
||||||
|
|
||||||
## Optional properties
|
## Optional properties
|
||||||
|
|
||||||
### namespace
|
### namespace
|
||||||
|
|
||||||
This is the [namespace](../concepts/namespaces.md) of the related addon. This property will be implicitly equal to the
|
This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the related addon. If this property is not set,
|
||||||
[namespace of the addon](addon.md#namespace), if it was not set explicitly.
|
AddonScript will resolve the namespace via the [addon endpoint](../api/features/addons.md#get-addon) of a [repository](#repositories).
|
||||||
|
|
||||||
### version
|
|
||||||
|
|
||||||
This is a [maven version range](../concepts/versioning.md#dependancy-version-requirement-specification) that specifies, which versions
|
|
||||||
of the related addon are targeted by this relation. You can either set this property or `semver`, but exactly one of them has to be set.
|
|
||||||
|
|
||||||
### semver
|
|
||||||
|
|
||||||
This is a [semver version range](https://github.com/semver/semver/pull/584) of supported versions of this relation.
|
|
||||||
It will only allow versions of the related addon, which have a valid semver version number, which is in this range.
|
|
||||||
|
|
||||||
### repositories
|
### repositories
|
||||||
|
|
||||||
This is an array of [repository](repository.md) IDs. These are the repositories, from which AddonScript should try to get this relation from,
|
This is an array of [repository namespaces](repository.md#namespace). These are the repositories, from which AddonScript will try to get this relation from,
|
||||||
in the order as they are specified in the array. If this property is not set or the array is empty, AddonScript will try to resolve the relation by
|
in the order as they are specified in the array. If this property is not set or the array is empty, AddonScript will try to resolve the relation from
|
||||||
the namespace from all defined repositories.
|
the repository described by the [manifest namespace](manifest.md#namespace). The repository described the the [canonical namespace](#namespace) of this
|
||||||
|
relation has always precedence before these repositories.
|
||||||
|
|
||||||
### flags
|
### 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 use the default flags.
|
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,
|
||||||
### conditions
|
since the related addon can still be installed on that side without any conflict.
|
||||||
|
|
||||||
This is a [conditions object](conditions.md). It can only be used, if the [optional flag](../concepts/flags.md) was set.
|
|
||||||
|
|
|
@ -2,29 +2,25 @@
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "asrepo",
|
"namespace": "net.addonscript",
|
||||||
"type": "api",
|
"instances": ["https://api.addonscript.net"]
|
||||||
"url": "https://api.addonscript.net"
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Required properties
|
## Required properties
|
||||||
|
|
||||||
### id
|
### namespace
|
||||||
|
|
||||||
This is the ID of the repository. It has to be unique to the AddonScript file.
|
This is the [namespace](../concepts/namespaces.md), which describes this repository.
|
||||||
|
|
||||||
### type
|
### instances
|
||||||
|
|
||||||
This is the type of the repository. Possible values are `addonscript` or `maven`.
|
This is an array of base URLs of [AddonScript API](../api) instances, on which this
|
||||||
A repository of the type `addonscript` is an instance of the [AddonScript API](../api).
|
repository can be found. To get an addon from this repository, AddonScript will
|
||||||
AddonScript will use the basic endpoints of that instance to retrieve available versions
|
try to get it from the [addon endpoint](../api/features/addons.md#get-addon)
|
||||||
of a specific addon, as well as the [addon JSON](./addon.md) for a specific version of an
|
of these API instances in the order, in which they are specified in this array.
|
||||||
addon.
|
Instances in this array with the `builder` [feature](../api/features/builder.md) will
|
||||||
|
be used by AddonScript, to request the launch environment for an addon with a
|
||||||
|
[canonical namespace](../concepts/namespaces.md#canonical-namespaces) equal
|
||||||
### url
|
to the [namespace](#namespace) of this repository. The first API instance with
|
||||||
|
the `builder` feature will be used in this case with the others as fallback.
|
||||||
This is the base URL of an [AddonScript API](../api) instance, if the repository
|
|
||||||
type is `addonscript`, or the base URL of a Maven Repository, if the repository
|
|
||||||
type is `maven`.
|
|
Loading…
Reference in a new issue