forked from addonscript/addonscript-spec
Compare commits
20 Commits
481174b566
...
27ad758268
| Author | SHA1 | Date |
|---|---|---|
 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 |
|
|
@ -7,23 +7,29 @@
|
|||
- [AddonScript API](api/README.md)
|
||||
- [Addon repository](api/features/addons.md)
|
||||
- [File repository](api/features/files.md)
|
||||
- [Environment builder](api/features/env.md)
|
||||
|
||||
# Schema
|
||||
|
||||
- [Addon Object](schema/addon.md)
|
||||
- [Addon Manifest Object](schema/manifest.md)
|
||||
- [AddonScript Object](schema/addonscript.md)
|
||||
- [File Object](schema/file.md)
|
||||
- [Install Object](schema/install.md)
|
||||
- [Relation Object](schema/relation.md)
|
||||
- [Flags Object](schema/flags.md)
|
||||
- [Repository Object](schema/repository.md)
|
||||
- [Meta Object](schema/meta.md)
|
||||
- [API Addon](schema/api_addon.md)
|
||||
- [API File](schema/api_file.md)
|
||||
- [API Addon Object](schema/api_addon.md)
|
||||
- [API File Object](schema/api_file.md)
|
||||
- [Environment Builder Request Object](schema/api_env_request.md)
|
||||
- [Addon Descriptor Object](schema/api_addon_descriptor.md)
|
||||
- [Environment Builder Response Object](schema/api_env_response.md)
|
||||
|
||||
# Concepts
|
||||
|
||||
- [Installing](concepts/install.md)
|
||||
- [Flags](concepts/flags.md)
|
||||
- [Instance addons](concepts/instance.md)
|
||||
- [Links](concepts/links.md)
|
||||
- [Namespaces](concepts/namespaces.md)
|
||||
- [Versioning](concepts/versioning.md)
|
||||
|
|
|
|||
|
|
@ -2,26 +2,23 @@
|
|||
|
||||
## The Index Endpoint
|
||||
|
||||
### `GET {base URL}`
|
||||
`GET {base URL}`
|
||||
|
||||
The index endpoint can be used to get basic information about an API
|
||||
instance, including the API versions and features supported by that
|
||||
instance and the [default namespace](../concepts/namespaces.md#default-namespaces) of the instance.
|
||||
The response object of this endpoint contains a `versions` property, which is an object with API
|
||||
version numbers as keys and the configuration objects for the specific API version as values.
|
||||
For API version `v2` (AddonScript major release 2) the configuration object contains a `default_namespace`
|
||||
property, which is the [default namespace](../concepts/namespaces.md#default-namespaces) of the API
|
||||
instance, and a `features` property, which is an array containing all [API features](#features)
|
||||
available on this API instance.
|
||||
For API version `v2` (AddonScript major release 2) the configuration object contains a `features`
|
||||
property, which is an array containing all [API features](#features) available on this API instance.
|
||||
|
||||
#### Example response body:
|
||||
### Example response body:
|
||||
|
||||
``` json
|
||||
{
|
||||
"versions": {
|
||||
"v2": {
|
||||
"default_namespace": "com.example",
|
||||
"features": ["listing", "filters", "com.example.customfeature"]
|
||||
"features": ["addons", "env", "com.example.customfeature"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -30,10 +27,11 @@ available on this API instance.
|
|||
## Features
|
||||
|
||||
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).
|
||||
|
||||
These API features are part of the AddonScript specification itself:
|
||||
|
||||
- `addons`: [Addon repository](./features/addons.md)
|
||||
- `files`: [File repository](./features/files.md)
|
||||
- `files`: [File repository](./features/files.md)
|
||||
- `env`: [Environment builder](./features/env.md)
|
||||
|
|
@ -12,13 +12,13 @@ of the addon.
|
|||
|
||||
#### Path variales:
|
||||
|
||||
- `namespace`: A [namespace](../../concepts/namespaces.md) which contains the addon
|
||||
- `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 in this addon repository.
|
||||
The response body must be an [API Addon Object](../../schema/api_addon.md).
|
||||
The response body MUST be an [API Addon Object](../../schema/api_addon.md).
|
||||
- `404 Not Found`: The addon is not available in this addon repository.
|
||||
|
||||
### Get addon manifest
|
||||
|
|
@ -29,12 +29,23 @@ This endpoint can be used to retrieve the manifest of a specific version of an a
|
|||
|
||||
#### Path variables:
|
||||
|
||||
- `namespace`: The namespace which contains the addon
|
||||
- `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 in this addon repository.
|
||||
The response body must be an [Addon Manifest](../../schema/addon.md).
|
||||
- `404 Not Found`: This version of the addon is not available in this addon repository.
|
||||
The response body MUST be an [Addon Manifest](../../schema/manifest.md).
|
||||
- `404 Not Found`: This version of the addon is not available in this addon repository.
|
||||
|
||||
### Get namespaces
|
||||
|
||||
`GET {base URL}/v2/namespaces`
|
||||
|
||||
This endpoint can be used to get a list of [repository namespaces](../../concepts/namespaces.md#repository-namespaces),
|
||||
which can be found on this API instance. It MAY be incomplete or empty at all.
|
||||
|
||||
#### Responses:
|
||||
|
||||
- `200 OK`: The response body MUST be a JSON array of namespace strings.
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
# Environment builder
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Build launch environment
|
||||
|
||||
`POST {base URL}/v2/env`
|
||||
|
||||
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 the
|
||||
`env` [manifest flag](../../concepts/flags.md#manifest-flags), AddonScript will send a request to this
|
||||
endpoint if the API instance [specified in the manifest](../../schema/manifest.md#envapi) of that addon.
|
||||
This request contains information about the AddonScript [schema version](../../schema/api_env_request.md#addonscript),
|
||||
which will be used in the request and about which [addon](../../schema/api_env_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_env_request.md#addon) in this environment on that side. The [manifest](../../schema/manifest.md)
|
||||
of this [addon](../../schema/api_env_request.md#addon) uses the `env` [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 delegates the launch configuration to this addon. In latetr 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 `env` addon MUST be covered this way
|
||||
while only those optional `env` 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
|
||||
`env` [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_env_response.md#files) and the AddonScript
|
||||
[schema version](../../schema/api_env_response.md#addonscript) for the response. 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.
|
||||
|
||||
#### Request Body:
|
||||
|
||||
The request body MUST be an [Environment Builder Request Object](../../schema/api_env_request.md).
|
||||
|
||||
#### Responses:
|
||||
|
||||
- `200 OK`: The launch environment was successfully build.
|
||||
The response body MUST be an [Environment Builder Response Object](../../schema/api_env_response.md).
|
||||
- `400 Bad Request`: The server was not able to build the launch environment because of
|
||||
invalid information sned by the client.
|
||||
- `500 Internal Server Error`: The server was not able to build the launch environment
|
||||
because of an internal error.
|
||||
|
|
@ -7,7 +7,7 @@
|
|||
`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.
|
||||
If the instance don't know this file, it MUST respond with status code 404.
|
||||
|
||||
#### Path variables:
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ of the addon to which the file belongs to
|
|||
#### Responses:
|
||||
|
||||
- `200 OK`: The file is available in this file repository.
|
||||
The response body must be an [API File Object](../../schema/api_file.md).
|
||||
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
|
||||
|
|
@ -29,7 +29,7 @@ The response body must be an [API File Object](../../schema/api_file.md).
|
|||
|
||||
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.
|
||||
it MUST respond with status code 404.
|
||||
|
||||
#### Path variables:
|
||||
|
||||
|
|
@ -39,6 +39,6 @@ it must respond with status code 404.
|
|||
#### Responses:
|
||||
|
||||
- `200 OK`: The file is available in this file repository.
|
||||
The response body must be an [API File Object](../../schema/api_file.md).
|
||||
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,42 +1,57 @@
|
|||
# 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
|
||||
a [relation](../schema/relation.md) was made. If a file has no side flags set, it will inherit them from the
|
||||
[version object](../schema/addon.md), while a version is required to have side flags set.
|
||||
## Manifest flags
|
||||
|
||||
- `client` This flag specifies, that the version, relation or file can be installed on the client side
|
||||
- `server` This flag specifies, that the version, relation or file can be installed on the server side
|
||||
|
||||
## Version flags
|
||||
|
||||
These are flags, which can be set for [versions](../schema/addon.md).
|
||||
|
||||
- `instance` This flag specifies, that this is a version of an instance addon. Instance addons represent instances of
|
||||
Minecraft itself, while non-instance addons have to be installed into an existing instance of Minecraft.
|
||||
- `required` This flag specifies, that the addon of the manifest is required on the side which has this flag set,
|
||||
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
|
||||
`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,
|
||||
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 the [env_api](../schema/manifest.md#envapi) property.
|
||||
|
||||
## 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,
|
||||
than any relation or file, which has this flag set, also has to be installed.
|
||||
- `optional` This flag specifies, that the related addon or file is optional for this addon. If the addon gets installed,
|
||||
the user should be able to choose, whether he wants to install the relation or file with this flag, or not.
|
||||
|
||||
### Relation specific
|
||||
|
||||
These are relational flags, which can only be used for [relations](../schema/relation.md).
|
||||
|
||||
- `included` This flag specifies, that the related addon is included in this one. This also means, that if some
|
||||
addon requires the related addon, it can also be installed with this addon instead. Relations with this flag must
|
||||
have an exact version specified, a version range, which includes multiple versions is not allowed. If this flag
|
||||
is used together with `required` or `optional`, the files of the related addon will be installed like if the
|
||||
relation wouldn't have this flag, relations of the related addon will however be ignored since AddonScript assumes,
|
||||
that they are already covered by this addon.
|
||||
- `incompatible` This flag specifies, that the related addon is incompatible to this one. This means, that they can't
|
||||
be installed together in the same instance.
|
||||
- `launch` This flag specifies, that the related addon should take care of the Minecraft launch process. It can only
|
||||
be used, if both this and the related addon are instance addons.
|
||||
the user SHOULD be able to choose, whether he wants to install the relation or file with this flag, or not.
|
||||
- `included` This flag is only valid for relations. It specifies, that the related addon is included in this one.
|
||||
This also means, that if some addon requires the related addon, it can also be installed with this addon instead.
|
||||
Relations with this flag MUST have an exact version specified, a version range, which includes multiple versions
|
||||
is not allowed. If this flag is used together with `required` or `optional`, the files of the related addon will
|
||||
be installed like if the relation wouldn't have this flag, relations of the related addon will however be ignored
|
||||
since AddonScript assumes, that they are already covered by this addon.
|
||||
- `incompatible` This flag specifies for a relation, that the related addon is incompatible to this one, which means,
|
||||
that they can't be installed together in the same instance. For a file this flag specifies, that the file can't be
|
||||
installed on the side which has this flag set.
|
||||
- `launch` This flag is only valid for [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`.
|
||||
- `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)
|
||||
to be part of the [launch environment](../api/features/env.md#build-launch-environment). For the addon, for
|
||||
which the launch environment will be build, 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. An addon, that is delegating the launch configuration to one, which has the `env`
|
||||
[manifest flag](#manifest-flags), uses this flag to tell AddonScript, which version of the 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 `env` addons will be part of the environment. If an addon with the `env`
|
||||
[manifest flag](#manifest-flags) gets manually installed, meaning not as a dependency, the user SHOULD be asked,
|
||||
which optional `env` addons and which version of each `env` addon will be requested.
|
||||
|
|
@ -8,8 +8,7 @@ args:
|
|||
|
||||
- `[location]`
|
||||
|
||||
`move` is simplest install action of all. It just moves the file to
|
||||
the given location.
|
||||
`move` moves the file to the given location.
|
||||
|
||||
### extract
|
||||
|
||||
|
|
@ -32,24 +31,13 @@ args:
|
|||
|
||||
`inject` can be used with zip or jar files, to inject the contents of that file
|
||||
into the server launch jar on server side or into the client jar on client side.
|
||||
In contrast to libraries, `inject` will not add 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
|
||||
are also in injected file.
|
||||
|
||||
### launch
|
||||
|
||||
`launch` can be used to mark the file as the launch file for a specific side. Files having this
|
||||
install action 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 action may only be used with launchable or instance addons and there may be only one file for each
|
||||
side, which has this install action, except all of them are marked as `optional`, in which case they are also
|
||||
implicitly marked as incompatible to each other.
|
||||
|
||||
## 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.
|
||||
|
||||
## Directories
|
||||
|
|
|
|||
|
|
@ -0,0 +1,16 @@
|
|||
# Instance addons
|
||||
|
||||
Instance addons represent instances of Minecraft itself, while non-instance addons
|
||||
have to be installed into an existing instance of Minecraft. An instance addon MUST have
|
||||
a launch configuration for each side 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.
|
||||
|
||||
## 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.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# 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.
|
||||
|
||||
## http(s)
|
||||
|
|
|
|||
|
|
@ -1,26 +1,33 @@
|
|||
# Namespaces
|
||||
|
||||
Namespaces are used in conjunction with addon IDs to uniquely identify an addon.
|
||||
Namespaces are used in conjunction with addon IDs to uniquely identify an addon as well as
|
||||
an identifier for repositories.
|
||||
|
||||
## Format
|
||||
|
||||
Namespaces may 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
|
||||
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 can have multiple namespaces, it must have exactly one canonical
|
||||
namespace, which is defined in the [addon object](../schema/addon.md#namespace).
|
||||
An [API instance](../api/) must also return the canonical namespace of
|
||||
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 namespace. To check, if two addons
|
||||
are the same addon, thier canonical namespace and their ID must be equal.
|
||||
|
||||
## Default Namespaces
|
||||
|
||||
Each [API instance](../api/) has a default namespace. Addons in the
|
||||
repository of that API instance should have that namespace, as long as there
|
||||
are no ID conflicts in the repository. The default namespace does not need
|
||||
to be the canonical namespace of these addons.
|
||||
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
|
||||
|
||||
Version numbers in AddonScript are based on Maven version numbers. The only difference to the Maven versioning specification is,
|
||||
that AddonScript version numbers may only contain non-space ASCII characters.
|
||||
## AddonScript Version Numbers
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
### Dependancy Version Requirement Specification
|
||||
### Dependency Version Requirement Specification
|
||||
|
||||
Version requirements have the following syntax:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,7 @@
|
|||
# Zip Packaging
|
||||
|
||||
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
|
||||
at the root of the zip file or, if there is just one directory in the root of the zip file,
|
||||
in this directory. All files and directories inside the zip file can be accessed from AddonScript
|
||||
using the [file links](../concepts/links.md#file). The path from the file URL is relative to the location of
|
||||
the AddonScript file.
|
||||
a zip file. The AddonScript file MUST be named `manifest.json` and MUST be placed
|
||||
at the root of the zip file. All files and directories inside the zip file can be
|
||||
accessed from AddonScript using the [file links](../concepts/links.md#file).
|
||||
The path from the file URL is relative to the location of the AddonScript file.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@
|
|||
|
||||
This is the ID of the addon.
|
||||
|
||||
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.
|
||||
|
||||
### namespace
|
||||
|
||||
|
|
|
|||
|
|
@ -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 SHOULD be the [canonical namespace](../concepts/namespaces.md#canonical-namespaces).
|
||||
|
||||
### version
|
||||
|
||||
This is the [version](manifest.md#version) of the addon.
|
||||
|
|
@ -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
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
# Environment Builder Response Object
|
||||
|
||||
```json
|
||||
{
|
||||
"addonscript": {},
|
||||
"files": []
|
||||
}
|
||||
```
|
||||
|
||||
## 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_env_request.md#addonscript) of the [request](api_env_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).
|
||||
|
|
@ -16,8 +16,8 @@
|
|||
|
||||
### link
|
||||
|
||||
This is an array of [links](../concepts/links.md), which are pointing to the actual file. This must be a http(s) link.
|
||||
All of these links must have the same file type.
|
||||
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
|
||||
|
||||
|
|
@ -31,4 +31,4 @@ Supported hash algorithms:
|
|||
|
||||
### meta
|
||||
|
||||
This is a [meta object](meta.md) containing metadata about the file. it may only contain [additional metadata](meta.md#additional).
|
||||
This is a [meta object](meta.md) containing metadata about the file. it SHOULD only contain [additional metadata](meta.md#additional).
|
||||
|
|
@ -4,11 +4,12 @@
|
|||
{
|
||||
"qualifier": "modfile",
|
||||
"link": ["https://example.com/mymod.jar", "./mymod.jar"],
|
||||
"flags": [],
|
||||
"flags": {},
|
||||
"install": [],
|
||||
"hashes": {
|
||||
"sha1": "somesha1checksum"
|
||||
}
|
||||
},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -17,7 +18,7 @@
|
|||
### qualifier
|
||||
|
||||
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 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.
|
||||
|
||||
|
|
@ -26,8 +27,8 @@ can together be used to uniquely identify a file.
|
|||
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,
|
||||
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.
|
||||
If none of the specified links works or the array is empty, the file link should be retrieved by it's identifier
|
||||
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 or the array is empty, the file link SHOULD be retrieved by it's identifier
|
||||
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.
|
||||
|
||||
|
|
@ -35,13 +36,13 @@ verified, that the downloaded file is correct.
|
|||
|
||||
### install
|
||||
|
||||
This is an array of [install objects](install.md). They describe how the file should be installed to the game.
|
||||
The order in the array corresponds to the order in which the installation steps should be applied.
|
||||
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 will be applied.
|
||||
|
||||
### 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
|
||||
inherit the [side flags](../concepts/flags.md#side-flags) from the [version](addon.md) and have the `required` flag set by default.
|
||||
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.
|
||||
|
||||
### hashes
|
||||
|
||||
|
|
@ -51,3 +52,6 @@ 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).
|
||||
|
|
@ -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).
|
||||
|
|
@ -11,7 +11,7 @@
|
|||
|
||||
### action
|
||||
|
||||
This is the [install action](../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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
# Addon Object
|
||||
# Addon Manifest Object
|
||||
|
||||
```json
|
||||
{
|
||||
"addonscript": {},
|
||||
"id": "myaddon",
|
||||
"namespace": "com.example",
|
||||
"version": "1.0",
|
||||
"semver": "1.0.0",
|
||||
"version": "1.0.0",
|
||||
"files": [],
|
||||
"relations": [],
|
||||
"flags": ["server", "client"],
|
||||
"flags": {},
|
||||
"repositories": [],
|
||||
"env_api": "https://example.com",
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
|
@ -25,13 +25,11 @@ This is an [AddonScript object](addonscript.md) containing information about the
|
|||
|
||||
This is the ID of the addon.
|
||||
|
||||
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.
|
||||
|
||||
### 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.
|
||||
This is the [AddonScript version number](../concepts/versioning.md#addonscript-version-numbers) of this version.
|
||||
|
||||
### namespace
|
||||
|
||||
|
|
@ -39,14 +37,10 @@ This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces
|
|||
|
||||
### flags
|
||||
|
||||
This is an array of [flags](../concepts/flags.md) for this version.
|
||||
This is an [flags object](flags.md) which contains [manifest flags](../concepts/flags.md#manifest-flags) for both sides for this manifest.
|
||||
|
||||
## 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).
|
||||
|
||||
### files
|
||||
|
||||
This is an array of [file objects](file.md) including the files belonging to this addon.
|
||||
|
|
@ -58,7 +52,14 @@ This is an array of [relation objects](relation.md) which represent addons in re
|
|||
### repositories
|
||||
|
||||
This is an array of [repository objects](repository.md). Each repository object defines one repository from which files or
|
||||
addons can be retrieved.
|
||||
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.
|
||||
|
||||
### env_api
|
||||
|
||||
This is the base URL of an [AddonScript API](../api) instance, which has the `env` feature and will be used to
|
||||
build the launch environment for this addon. This property will only be used if this addon has the `env`
|
||||
[manifest flag](../concepts/flags.md#manifest-flags).
|
||||
|
||||
### meta
|
||||
|
||||
|
|
@ -41,17 +41,17 @@ This object can contain any arbitrary data,
|
|||
|
||||
### 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.
|
||||
|
||||
### icon
|
||||
|
||||
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.
|
||||
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 MAY be dispayed to users in programs.
|
||||
|
||||
### 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
|
||||
|
||||
|
|
@ -75,7 +75,8 @@ The type of the addon, for example `mod`, `modpack` or `resourcepack`.
|
|||
|
||||
### 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
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
"namespace": "com.example",
|
||||
"version": "[1.0]",
|
||||
"repositories": ["repo1"],
|
||||
"flags": []
|
||||
"flags": {}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -16,30 +16,27 @@
|
|||
|
||||
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
|
||||
|
||||
### namespace
|
||||
|
||||
This is the [namespace](../concepts/namespaces.md) of the related addon. This property will be implicitly equal to the
|
||||
[namespace of the addon](addon.md#namespace), if it was not set explicitly.
|
||||
|
||||
### 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.
|
||||
This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the related addon. If this property is not set,
|
||||
AddonScript will resolve the namespace via the [addon endpoint](../api/features/addons.md#get-addon) of a [repository](#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,
|
||||
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
|
||||
the namespace from all defined repositories.
|
||||
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 from
|
||||
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
|
||||
|
||||
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
|
||||
inherit the [side flags](../concepts/flags.md#side-flags) from the [version](addon.md) and have the `required` flag set by default.
|
||||
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,
|
||||
since the related addon can still be installed on that side without any conflict.
|
||||
|
|
|
|||
|
|
@ -2,17 +2,20 @@
|
|||
|
||||
```json
|
||||
{
|
||||
"id": "asrepo",
|
||||
"url": "https://api.addonscript.net"
|
||||
"namespace": "net.addonscript",
|
||||
"instances": ["https://api.addonscript.net"]
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
### url
|
||||
### instances
|
||||
|
||||
This is the base URL of an [AddonScript API](../api) instance.
|
||||
This is an array of base URLs of [AddonScript API](../api) instances, on which this
|
||||
repository can be found. To get an addon from this repository, AddonScript will
|
||||
try to get it from the [addon endpoint](../api/features/addons.md#get-addon)
|
||||
of these API instances in the order, in which they are specified in this array.
|
||||
Loading…
Reference in New Issue