forked from addonscript/addonscript-spec
make docs more clear
This commit is contained in:
parent
2e26c5ab95
commit
244442223b
7 changed files with 206 additions and 26 deletions
|
|
@ -3,7 +3,7 @@
|
|||
- [AddonScript](README.md)
|
||||
|
||||
# Schema
|
||||
- [Addon Object](schema/root.md)
|
||||
- [Addon Object](schema/addon.md)
|
||||
- [AddonScript Object](schema/addonscript.md)
|
||||
- [File Object](schema/file.md)
|
||||
- [Install Object](schema/install.md)
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
"addonscript": {},
|
||||
"id": "myaddon",
|
||||
"namespace": "com.example",
|
||||
"version": "1.0",
|
||||
"version": "1.0.0",
|
||||
"files": [],
|
||||
"relations": [],
|
||||
"flags": ["server", "client"],
|
||||
|
|
@ -22,26 +22,28 @@ This is an [AddonScript object](addonscript.md) containing information about the
|
|||
|
||||
### id
|
||||
|
||||
This is the ID of the addon. It should only contain **lowercase letters, numbers and dashes**.
|
||||
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 of this version. It must follow [semver version naming conventions](https://semver.org/spec/v2.0.0.html),
|
||||
This is the version number of this version. It must follow [semver versioning specifications](https://semver.org/spec/v2.0.0.html),
|
||||
as they are used to compare versions.
|
||||
|
||||
## Optional properties
|
||||
|
||||
### namespace
|
||||
|
||||
This is the namespace of the addon.
|
||||
The namespace of the addon in a reverse-DNS format. Used to identify addons across repositories, if it is present.
|
||||
|
||||
### files
|
||||
|
||||
This is an array of [file objects](file.md) including the files belonging to this version.
|
||||
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 represents related addons.
|
||||
This is an array of [relation objects](relation.md) which represent addons in relation to this one.
|
||||
|
||||
### flags
|
||||
|
||||
|
|
@ -54,4 +56,4 @@ addons can be retrieved.
|
|||
|
||||
### meta
|
||||
|
||||
This is a [meta object](meta.md).
|
||||
This is a [meta object](meta.md) containing metadata about the addon.
|
||||
|
|
@ -6,5 +6,13 @@
|
|||
}
|
||||
```
|
||||
|
||||
Currently the AddonScript object only contains the version of AddonScript the file uses.
|
||||
In future versions, there may be other information added to this.
|
||||
Future fields may be added.
|
||||
|
||||
# Required properties
|
||||
|
||||
## version
|
||||
This is the version of the addonscript format the file is written in.
|
||||
|
||||
The specification you are reading is for version 2. Version 1 is an old version which is deprecated,
|
||||
and doesn't have to be (and shouldn't be) implemented by tools using addonscript.
|
||||
|
||||
|
|
|
|||
|
|
@ -15,14 +15,138 @@ as optional relations in this version.
|
|||
|
||||
### require
|
||||
|
||||
This is an array of addons, which are required for this relation or file.
|
||||
This is an array of addons, which are required for this relation or file and must be present.
|
||||
|
||||
### companion
|
||||
|
||||
This is an array of addons, which have to be installed together with this
|
||||
relation or file. In contrast to `require`, this is a two-way dependency, which means, that if this
|
||||
file or relation is installed, the addons in the array also have to be installed and if one of the
|
||||
addons in the array are installed, this relation or file also have to be installed.
|
||||
This is an array of file 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>
|
||||
|
||||
```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
|
||||
|
||||
|
|
|
|||
|
|
@ -15,8 +15,10 @@
|
|||
|
||||
### id
|
||||
|
||||
This is the ID of the file. It should only contain **lowercase letters, numbers and dashes**.
|
||||
This is the ID of the file.
|
||||
It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces.
|
||||
|
||||
<!--TODO: error if there are multiple relations with the same id and allow multiple urls-->
|
||||
If multiple file objects in the same array have the same ID, they are treated as the same file,
|
||||
which means that the first one of them in the array will be used unless it can't be retrieved from the URL,
|
||||
in which case the next one will be used as a fallback.
|
||||
|
|
@ -34,13 +36,11 @@ The order in the array corresponds to the order in which the installation steps
|
|||
|
||||
### flags
|
||||
|
||||
This is an array of [flags](../flags.md) for this file. If this property is not present in a file object, the file
|
||||
will have the flags which are set as default for files, or if no default was set, it will inherit the flags from the
|
||||
associated version, which are applicable for files.
|
||||
This is an array of [flags](../flags.md) for this file. If this property is not present in a file object, the file will use the default flags.
|
||||
|
||||
### sha1
|
||||
|
||||
This is the sha1 checksum of the file. Although the checksum is optional, it is recommended to use it.
|
||||
This is the sha1 checksum of the file. Although the checksum is optional, it is recommended.
|
||||
|
||||
### conditions
|
||||
|
||||
|
|
|
|||
|
|
@ -22,4 +22,51 @@
|
|||
|
||||
## Optional properties
|
||||
|
||||
### addon
|
||||
An [addon mata](#addon-meta-object) object.
|
||||
|
||||
### version
|
||||
A [version mata](#version-meta-object) object.
|
||||
|
||||
### additional
|
||||
This object can contain any arbitrary data,
|
||||
|
||||
# Addon Meta Object
|
||||
|
||||
## Optional Properties
|
||||
|
||||
### name
|
||||
The full, human-readable name of the addon. This is what a program such as a launcher should
|
||||
display to the user.
|
||||
|
||||
### icon
|
||||
A path 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.
|
||||
|
||||
### description
|
||||
A path to a description file for the addon. The file should be in CommonMark markdown.
|
||||
|
||||
### summary
|
||||
A short description of the addon, to be shown in lists and menus where the addon is shown aside others.
|
||||
|
||||
### website
|
||||
A URL to a website about the addon
|
||||
|
||||
### source
|
||||
A URL to the source code of the addon.
|
||||
|
||||
### issues
|
||||
A URL to an issue tracker for the addon.
|
||||
|
||||
### contributors
|
||||
An array of people who have contributed to the addon.
|
||||
|
||||
# Version Meta Object
|
||||
|
||||
## Optional properties
|
||||
|
||||
### changelog
|
||||
A path to a changelog file for the addon.
|
||||
|
||||
### timestamp
|
||||
A unix timestamp of the time and date of the version's release.
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
```json
|
||||
{
|
||||
"id": "namespace:othermod",
|
||||
"version": "[1.0,)",
|
||||
"version": "1.0",
|
||||
"repositories": ["repo1"],
|
||||
"flags": [],
|
||||
"conditions": {}
|
||||
|
|
@ -18,21 +18,20 @@ This is the ID or namespaced ID of the addon this relation refers to.
|
|||
|
||||
### version
|
||||
|
||||
<!--TODO: update link one PR is merged-->
|
||||
This is a [semver version range](https://github.com/semver/semver/pull/584) of supported versions of this relation.
|
||||
|
||||
## Optional properties
|
||||
|
||||
### repositories
|
||||
|
||||
This is an array of [repository](repository.md) IDs. This are the repositories, from where AddonScript should try to get this relation from,
|
||||
in the order as they are ordered in the array. If this property is not set or the array is empty, AddonScript will try to resolve the relation by
|
||||
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.
|
||||
|
||||
### flags
|
||||
|
||||
This is an array of [flags](../flags.md) for this relation. If this property is not present in a relation object, the relation
|
||||
will have the flags which are set as default for relations or, if no default was set, it will inherit the flags
|
||||
which are applicable for relations from the associated version.
|
||||
This is an array of [flags](../flags.md) for this relation. If this property is not present in a relation object, the relation will use the default flags.
|
||||
|
||||
### conditions
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue