Compare commits

...

54 Commits

Author SHA1 Message Date
Timo Ley 25cf1e7561 use patches array instead of side patches
continuous-integration/drone/push Build is passing Details
2023-09-01 11:32:38 +02:00
Timo Ley 3c2dd500a2 change spec url
continuous-integration/drone/push Build is passing Details
2023-08-16 10:18:56 +02:00
Timo Ley f5f0d8c1e3 new launch patches system 2023-08-16 10:18:35 +02:00
Timo Ley a4ef1a5c34 use underscore in link
continuous-integration/drone/push Build is passing Details
continuous-integration/drone Build is passing Details
2023-04-21 19:57:56 +02:00
Timo Ley f2ca4f5177 launch configuration overhaul
continuous-integration/drone/push Build is passing Details
2023-04-21 19:56:33 +02:00
Timo Ley 6414425d5e change usebuilder to use_builder
continuous-integration/drone/push Build is passing Details
2023-04-10 16:12:50 +02:00
Timo Ley c7e68360fb env builder overhaul
continuous-integration/drone/push Build is passing Details
2023-04-10 16:10:08 +02:00
Timo Ley 41fe553787 add JVM arguments
continuous-integration/drone/push Build is passing Details
2023-02-06 16:26:09 +01:00
Timo Ley 006adfec92 instance addon overhaul
continuous-integration/drone/push Build is passing Details
continuous-integration/drone/tag Build is passing Details
2023-02-03 16:20:43 +01:00
Timo Ley c8c27c5170 add manifest_version to v2
continuous-integration/drone/push Build is passing Details
2022-12-27 23:26:23 +01:00
Timo Ley 83c8948f95 API improvements 2022-12-27 23:01:50 +01:00
Timo Ley f265e1c858 small changes to API spec
continuous-integration/drone/push Build is passing Details
2022-12-16 11:09:33 +01:00
Timo Ley 38997a8984 Remove namespaces endpoint from addons feature
continuous-integration/drone/push Build is passing Details
will be part of another api feature in the future
2022-09-29 14:23:31 +02:00
Timo Ley 14aa5338d2 Merge pull request 'Repository and Namespace improvements' (#27) from tilera/addonscript-spec:repos into master
continuous-integration/drone/push Build is passing Details
continuous-integration/drone/tag Build is passing Details
Reviewed-on: #27
2022-09-26 08:19:25 +00:00
Timo Ley afd8a4b37b env builder API now parts of repositories
continuous-integration/drone/pr Build is passing Details
2022-09-26 10:17:50 +02:00
Timo Ley 27ad758268 Namespace and repository overhaul 2022-09-23 18:33:14 +02:00
Timo Ley 041fad3e6f Add meta property to file
continuous-integration/drone/push Build is passing Details
2022-09-21 11:08:10 +02:00
Timo Ley fce82e72e5 change versioning spec 2022-09-21 10:19:26 +02:00
Timo Ley 30545bf09e Merge pull request 'Versioning spec improvements' (#26) from tilera/addonscript-spec:versioning into master
continuous-integration/drone/push Build is passing Details
Reviewed-on: #26
2022-09-17 13:04:40 +00:00
Timo Ley 1861e66548 AddonScript version range specification 2022-09-17 14:18:20 +02:00
Timo Ley 3fcece2622 Moving version spec to versioning.md 2022-09-17 13:54:34 +02:00
Timo Ley 967a4b9a24 Remove semver property from manifest
An addon should not have two version numbers, either the main version number is semver compatible or nor
2022-09-16 16:59:39 +02:00
Timo Ley c170119e80 Merge branch 'master' of https://git.tilera.org/addonscript/addonscript-spec
continuous-integration/drone/push Build is passing Details
2022-09-12 14:54:37 +02:00
Timo Ley 124f9a6a2b Some fixes 2022-09-12 14:54:05 +02:00
Timo Ley 0f66dca177 Merge pull request 'Environment builder spec' (#25) from tilera/addonscript-spec:master into master
continuous-integration/drone/push Build is passing Details
continuous-integration/drone/tag Build is passing Details
Reviewed-on: #25
2022-09-10 14:58:35 +00:00
Timo Ley 9d5b4d945e Environment builder spec
continuous-integration/drone/pr Build is passing Details
2022-09-10 16:56:51 +02:00
Timo Ley 65408a2b21 Merge pull request 'Spec rephrasing to use requirement keywords' (#24) from tilera/addonscript-spec:master into master
continuous-integration/drone/push Build is passing Details
Reviewed-on: #24
2022-09-05 16:07:19 +00:00
Timo Ley c304c62855 Spec rephrasing to use requirement keywords
continuous-integration/drone/pr Build is passing Details
2022-09-05 16:54:36 +02:00
Timo Ley 6fab000c56 Fix new files not being in SUMMARY.md
continuous-integration/drone/push Build is passing Details
2022-09-03 21:30:18 +02:00
Timo Ley 226cbf7cdb Merge pull request 'Flags overhaul' (#23) from tilera/addonscript-spec:master into master
continuous-integration/drone/push Build is passing Details
Reviewed-on: #23
2022-09-03 19:25:17 +00:00
Timo Ley a9dfcb7575 Flags overhaul
continuous-integration/drone/pr Build is passing Details
2022-09-03 21:23:53 +02:00
Timo Ley 6e51a51ddc Index endpoint spec improvement
continuous-integration/drone/push Build is passing Details
2022-08-31 21:11:12 +02:00
Timo Ley ea975232e5 Merge pull request 'Rename addon.md to manifest.md' (#22) from tilera/addonscript-spec:master into master
continuous-integration/drone/push Build is passing Details
Reviewed-on: #22
2022-08-31 14:12:53 +00:00
Timo Ley 27d2e57c51 Rename addon.md to manifest.md
continuous-integration/drone/pr Build is passing Details
2022-08-31 16:11:10 +02:00
Timo Ley aae473bc94 Merge pull request 'API spec overhaul' (#21) from tilera/addonscript-spec:repos into master
continuous-integration/drone/push Build is passing Details
Reviewed-on: #21
2022-08-31 12:55:37 +00:00
Timo Ley 481174b566 API spec overhaul
continuous-integration/drone/pr Build is passing Details
2022-08-31 14:40:32 +02:00
Timo Ley f14ec070d4 Merge pull request 'Remove Maven repositories from spec' (#17) from tilera/addonscript-spec:maven into master
continuous-integration/drone/push Build is passing Details
Reviewed-on: #17
2022-08-30 14:12:37 +00:00
Timo Ley cd44fe0184 Merge branch 'master' into maven 2022-08-30 14:12:03 +00:00
Timo Ley 30e93f7621 Added file repository feature to API 2022-08-30 16:11:03 +02:00
Timo Ley 3f042e332c Merge pull request 'Install spec improvements' (#19) from tilera/addonscript-spec:install into master
continuous-integration/drone/push Build is passing Details
Reviewed-on: #19
Discussed-on: #10
2022-08-26 20:01:05 +00:00
Timo Ley 9d86792bfc Rename "command" to "action"
continuous-integration/drone/pr Build is passing Details
2022-08-26 21:56:07 +02:00
Timo Ley ca281821b8 Remove select installer 2022-08-26 21:52:01 +02:00
Timo Ley de156c1f0d Merge pull request 'namespace spec' (#16) from tilera/addonscript-spec:master into master
continuous-integration/drone/push Build is passing Details
Reviewed-on: #16
2022-08-23 11:24:22 +00:00
Timo Ley bc24466b0c Change file ID to qualifier
continuous-integration/drone/pr Build is passing Details
2022-08-22 21:24:34 +02:00
Timo Ley 90d8babdd2 Remove Maven repositories from spec 2022-08-16 17:28:53 +02:00
Timo Ley 63b4c53a59 Merge pull request 'Make file hashes more scalable' (#15) from tilera/addonscript-spec:hashes into master
continuous-integration/drone/push Build is passing Details
Reviewed-on: #15
2022-08-04 17:38:44 +00:00
Timo Ley a4ec67e76c basic namespace spec
continuous-integration/drone/pr Build is passing Details
2022-08-04 16:53:33 +02:00
Timo Ley 123f62e1c2 Make file hashes more scalable
continuous-integration/drone/pr Build is passing Details
2022-06-25 22:14:43 +02:00
Timo Ley 2a3d340b20 Improve included flag specification
continuous-integration/drone/push Build is passing Details
2022-06-10 23:57:15 +02:00
Timo Ley 44372968e6 Remove conditions
Will be replaced by another feature
2022-06-09 23:05:45 +02:00
Timo Ley f976226b20 Merge pull request 'Specify default flags' (#13) from tilera/addonscript-spec:master into master
continuous-integration/drone/push Build is passing Details
Reviewed-on: #13
2022-06-08 17:48:46 +00:00
Timo Ley 9a0db82745 Merge branch 'master' into master
continuous-integration/drone/pr Build is passing Details
2022-06-08 17:47:10 +00:00
Timo Ley 56837dcec1 Specify default flags
continuous-integration/drone/pr Build is passing Details
Closes #9
2022-06-08 19:44:19 +02:00
Timo Ley ef6dc8fa6f Fix "packaging" link in links.md
continuous-integration/drone Build is passing Details
continuous-integration/drone/push Build is passing Details
2022-02-28 23:10:52 +00:00
29 changed files with 907 additions and 426 deletions

View File

@ -2,7 +2,7 @@
The official AddonScript specification is available in the master branch of the
[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?

View File

@ -5,22 +5,33 @@
# API
- [AddonScript API](api/README.md)
- [Addon repository](api/features/addons.md)
- [File repository](api/features/files.md)
- [Environment builder](api/features/builder.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)
- [Conditions Object](schema/conditions.md)
- [Flags Object](schema/flags.md)
- [Repository Object](schema/repository.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
- [Minecraft](concepts/minecraft.md)
- [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)

View File

@ -2,73 +2,68 @@
## 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 of the instance.
The index endpoint can be used to get basic information about which
API versions an API instance implements. The response object of this
endpoint contains a `versions` property, which is an array containing
all API versions available on this instance.
#### Example response body:
### Example response body:
``` json
{
"default_namespace": "com.example",
"versions": ["v1"],
"features": ["listing", "filters", "com.example.customfeature"]
"versions": ["v2"]
}
```
## 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,
including metadata, all available versions and the canonical namespace of
the addon.
## API Version v2:
#### 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
- `addon`: The ID of the addon
`GET {base URL}/v2`
#### 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
{
"id": "addon-id",
"namespace": "com.example.canonical",
"meta": {
"addon": {},
"additional": {}
},
"versions": [
"1.0"
]
"features": ["addons", "env", "com.example.customfeature"],
"manifest_version": 2
}
```
The [meta object](../schema/meta.md) is the same as in the AddonScript files,
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
### 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:
- To be added
- `addons`: [Addon repository](./features/addons.md)
- `files`: [File repository](./features/files.md)
- `builder`: [Environment builder](./features/builder.md)

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

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

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

View File

@ -1,38 +1,58 @@
# 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.
## 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.
## 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.
then any relation or file, which has this flag set, also has to be installed.
- `optional` This flag specifies, that the related addon or file is optional for this addon. If the addon gets installed,
the user should be able to choose, whether he wants to install the relation or file with this flag, or not. This flag
can be used in combination with the [conditions](../schema/conditions.md) property.
### 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.
- `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, transistive relations will however be ignored
since AddonScript assumes, that they are already covered by this addon.
- `incompatible` This flag specifies for a relation, that the related addon is incompatible to this one, which means,
that they can't be installed together in the same instance. For a file this flag specifies, that the file can't be
installed on the side which has this flag set.
- `launch` This flag is only valid for relations and files of [instance addons](instance.md). For relations, it specifies,
that the [launch patches](../schema/patch.md) from the related addon (which MUST also be an instance addon) will also be
applied for this addon, including those inherited by other addons using the `patch` flag or the `launch` flag. This flag
will also inherit the main file of the relation, if it has any. `launch` only applies for one relation. If multiple relations
have the `launch` flag, it only applies for the first of them, which will be installed in the instance.
For files, it specifies, that the file will be the main jar for this instance. `launch` only applies for one file. If multiple
files have the `launch` flag, it only applies for the first of them, which will be installed in the instance.
- `env` (DEPRECATED) This flag is only valid for relations of [instance addons](instance.md).
An addon, that is inheriting the launch configuration from one, which uses the
[environment builder](../api/features/builder.md), uses this flag to tell AddonScript, which version of the `expected`
addons will be requested for the environment by setting an exact [version](../schema/relation.md#version) for the relation.
It also tells AddonScript, which optional `expected` addons will be part of the environment and which not.
- `expected` (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.

View File

@ -1,21 +1,20 @@
# File installing
## Install commands
## Install actions
### move
args:
- `[location]`
- `<location>`
`move` is simplest install step of all. It just moves the selected file to
the given location.
`move` moves the file to the given location.
### extract
args:
- `[location]`
- `<location>`
`extract` can be used with zip files, to extract the contents of the zip file
to the given location.
@ -24,46 +23,38 @@ to the given location.
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` 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 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.
are also in injected file. This install action can only be used by [instance addons](./instance.md).
## 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
If the selected 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
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 action to move all contents of the directory
to the specified location.

47
docs/concepts/instance.md Normal file
View 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.

View File

@ -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)
@ -14,5 +14,5 @@ a file on a http server.
`./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.

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

View File

@ -1 +1,33 @@
# 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.

View File

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

View File

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

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

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

View 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

View 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
View File

@ -0,0 +1,34 @@
# API File Object
```json
{
"link": ["https://example.com/file.jar"],
"hashes": {
"sha1": "somesha1checksum"
},
"meta": {
"additional": {}
}
}
```
## Required properties
### link
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).

View File

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

View File

@ -2,66 +2,56 @@
```json
{
"id": "modfile",
"qualifier": "modfile",
"link": ["https://example.com/mymod.jar", "./mymod.jar"],
"flags": [],
"maven": {},
"flags": {},
"install": [],
"sha1": "somesha1checksum",
"conditions": {}
"hashes": {
"sha1": "somesha1checksum"
},
"meta": {}
}
```
## Required properties
### id
### qualifier
This is the ID of the file.
It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces.
The file ID has to be unique to this addon version.
This is the qualifier of this file.
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.
### link
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, the file should be downloaded by it's Maven
specifier from one of the specified repository, but only, if a `sha1` hash is specified, so that it can be
verified, that the downloaded file is correct.
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.
## Optional properties
### 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 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
```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`.
This is a [meta object](meta.md) containing metadata about the file. it SHOULD only contain [additional metadata](meta.md#additional).

24
docs/schema/flags.md Normal file
View 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).

View File

@ -2,19 +2,25 @@
```json
{
"command": "move",
"args": ["./mods"]
"action": "move",
"args": ["./mods"],
"side": "both"
}
```
## 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
### 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
View 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.

View File

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

98
docs/schema/patch.md Normal file
View 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`.

View File

@ -6,8 +6,7 @@
"namespace": "com.example",
"version": "[1.0]",
"repositories": ["repo1"],
"flags": [],
"conditions": {}
"flags": {}
}
```
@ -17,33 +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 use the default flags.
### conditions
This is a [conditions object](conditions.md). It can only be used, if the [optional flag](../concepts/flags.md) was set.
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.

View File

@ -2,29 +2,25 @@
```json
{
"id": "asrepo",
"type": "api",
"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.
### type
### instances
This is the type of the repository. Possible values are `addonscript` or `maven`.
A repository of the type `addonscript` is an instance of the [AddonScript API](../api).
AddonScript will use the basic endpoints of that instance to retrieve available versions
of a specific addon, as well as the [addon JSON](./addon.md) for a specific version of an
addon.
### url
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`.
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.
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
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.