diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index e4461d1..7d30b49 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -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) diff --git a/docs/schema/root.md b/docs/schema/addon.md similarity index 66% rename from docs/schema/root.md rename to docs/schema/addon.md index 87dce01..c298d4d 100644 --- a/docs/schema/root.md +++ b/docs/schema/addon.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. diff --git a/docs/schema/addonscript.md b/docs/schema/addonscript.md index bf7d580..b04cc62 100644 --- a/docs/schema/addonscript.md +++ b/docs/schema/addonscript.md @@ -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. + diff --git a/docs/schema/conditions.md b/docs/schema/conditions.md index e178d25..59d7f16 100644 --- a/docs/schema/conditions.md +++ b/docs/schema/conditions.md @@ -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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeInstalled ifFlagsConditions
companion-relationrelationexample-file is installed + +```json +["optional"] +``` + + + +```json +{} +``` + +
example-filefilecompanion-relation is installed + +```json +["optional"] +``` + + + +```json +{ + "companion": [ + "companion-relation" + ] +} +``` + +
+ +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 diff --git a/docs/schema/file.md b/docs/schema/file.md index 0701963..0ef4bdc 100644 --- a/docs/schema/file.md +++ b/docs/schema/file.md @@ -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. + 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 diff --git a/docs/schema/meta.md b/docs/schema/meta.md index c1664c1..5d9921b 100644 --- a/docs/schema/meta.md +++ b/docs/schema/meta.md @@ -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. diff --git a/docs/schema/relation.md b/docs/schema/relation.md index 6a9128f..87ca38a 100644 --- a/docs/schema/relation.md +++ b/docs/schema/relation.md @@ -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 + 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