SFTtech · TheJJ · Sep 25, 2020 · Sep 20, 2020 · Sep 23, 2020
diff --git a/doc/media/openage/modpack_definition_file.md b/doc/media/openage/modpack_definition_file.md
@@ -0,0 +1,113 @@
+# Modpack Definition File
+
+The modpack definition file is the header file for [modpacks](modpacks.md).
+
+TOML is used as the configuration language.
+
+This document contains information about the parameters and sections that
+can be interpreted by the engine.
+
+## File Header
+
+It is recommended to start the file with the following comment.
+
+```
+# openage modpack definition file
+```
+
+This is not mandatory, but will help others who don't know the format
+find this specification document.
+
+The following parameters have to be specified.
+
+Parameter            | Data Type | Optional | Description
+---------------------|-----------|----------|------------
+`file_version`       | String    | No       | Version of the modpack definition file format.
+
+
+## [info] Section
+
+`[info]` contains general information about the modpack.
+
+Parameter          | Data Type     | Optional | Description
+-------------------|---------------|----------|------------
+`packagename`      | String        | No       | Name of the modpack.
+`version`          | String        | No       | Version number.
+`repo`             | String        | Yes      | Name of the repo where the package comes from.
+`alias`            | String        | Yes      | Alias of the modpack. Aliases can be used for replacing other modpacks.
+`title`            | String        | Yes      | Title used in UI.
+`description`      | String        | Yes      | Path to a file with a short description (max 500 chars).
+`long_description` | String        | Yes      | Path to a file with a detailed description.
+`url`              | String        | Yes      | Link to the modpack's website.
+`license`          | Array[String] | Yes      | License(s) of the modpack.
+
+
+## [assets] Section
+
+`[assets]` contains paths to assets in the modpack.
+
+Parameter      | Data Type      | Optional | Description
+---------------|----------------|----------|------------
+`include`      | Array[String]  | No       | List of paths to assets that should be mounted on load time. Paths are allowed to contain wildcards.
+`exclude`      | Array[String]  | Yes      | List of paths to assets that should be excluded from mounting. Paths are allowed to contain wildcards.
+
+
+## [dependency] Section
+
+`[dependency]` contains a list of other modpacks that the modpack depends on.
+
+Parameter      | Data Type      | Optional | Description
+---------------|----------------|----------|------------
+`modpacks`     | Array[String]  | Yes      | List of modpack aliases or identifiers.
+
+
+## [conflict] Section
+
+`[conflict]` contains a list of other modpacks that the modpack conflicts with.
+
+Parameter      | Data Type      | Optional | Description
+---------------|----------------|----------|------------
+`modpacks`     | Array[String]  | Yes      | List of modpack aliases or identifiers.
+
+
+## [authors] Section
+
+`[authors]` contains information about the creators and authors of the modpack.
+Every author must have their own subtable `[authors.{authorname}]`. The
+subtable can set the following parameters.
+
+Parameter  | Data Type     | Optional | Description
+-----------|---------------|----------|------------
+`name`     | String        | No       | Nickname of the author.
+`fullname` | String        | Yes      | Full name of the author.
+`since`    | String        | Yes      | Version number of the release where the author started to contribute.
+`until`    | String        | Yes      | Version number of the release where the author stopped to contribute.
+`role`     | Array[String] | Yes      | List of roles of the author during the creation of the modpack.
+`contact`  | Table         | Yes      | Contact information (see below).
+
+The contact table can use the following parameters.
+
+Parameter  | Data Type     | Optional | Description
+-----------|---------------|----------|------------
+`email`    | String        | Yes      | Email address.
+`github`   | String        | Yes      | Github username.
+`gitlab`   | String        | Yes      | Gitlab username.
+`mastodon` | String        | Yes      | Mastodon username.
+`matrix`   | String        | Yes      | Matrix username.
+`reddit`   | String        | Yes      | Reddit username.
+`twitter`  | String        | Yes      | Twitter username.
+`youtube`  | String        | Yes      | Youtube username.
+
+
+## [authorgroups] Section
+
+`[authorgroups]` contains information about teams or groups of authors.
+It can be used in addition to `[authors]` to signify that the modpack is
+a team effort.
+
+
+Parameter     | Data Type     | Optional | Description
+--------------|---------------|----------|------------
+`name`        | String        | No       | Group or team name.
+`description` | String        | Yes      | Path to a file with a description of the team.
+`authors`     | Array[String] | No       | List of author identifiers. These must match up with subtable keys in the `[authors]` section, e.g. `"xxbunny123"` references `[authors.xxbunny123]`.
diff --git a/doc/media/openage/modpacks.md b/doc/media/openage/modpacks.md
@@ -0,0 +1,176 @@
+# Modpacks
+
+Input assets for openage are organized in packages that we call **modpacks**.
+Everything you need to know about them is described in this document.
+
+
+## What does a modpack contain?
+
+Modpacks contain anything that is considered an input for the engine, e.g.
+gamedata, graphics, sounds, scripts, translations or a combination of all
+of those. There are no limits on their scope. A modpack can contain
+anything from minor enhancements to standalone games.
+
+Apart from game-related data, modpacks store configuration data for loading
+them into the engine. Most of this data is located in the
+**[modpack definition file](###modpack-definition-file)**. Modpacks can define
+their interaction with other modpacks by specifying **dependencies** and
+**conflicts**.
+
+The organization of files inside the modpack can be decided by its creators.
+openage does not enforce a specific file structure, although a "sensible"
+structure is of course recommended. The only file that is bound to some requirements
+is the modpack definition file (see its dedicated section for details).
+
+
+### Modpack Definition File
+
+The modpack definition file acts as the header file for the modpack. It is
+the only mandatory file in the modpack. The definition file must be placed
+in the modpack's root folder under the filename `modpack.toml`.
+
+The main purpose of the file is to store configuration parameters such as:
+
+* Internal name, alias and version number
+* Paths to game assets that should be loaded
+* Descriptions and author information
+
+Furthermore, the file can specify the interaction with other modpacks:
+
+* Dependencies on other modpacks
+* Conflicts with other modpacks
+* Replacment of other modpacks
+* Specification of a preferred load order (in relation to other mods)
+
+A full list of configuration parameters can be found [here](modpack_definition_file.md).
+
+
+## Distribution
+
+Modpacks can be distributed as standalone packages or via a package
+repository. Each of these methods has their own advantages.
+
+
+### Standalone Distribution
+
+Any modpack can be distributed as a standalone package by publishing
+a ZIP or tar.gz archive of the modpack on a hosting platform or a
+website. The archive can be imported by the openage launcher.
+
+It is the easiest way to publish a modpack for openage. However, updates
+and dependencies have to be done manually. Therefore, it is recommended
+to use a package repository to offer better convenience features for users.
+
+A note of advice: Allow everyone to download older versions of a modpack.
+Other modpacks might depend on a specific release version of your content.
+
+
+### Package Repositories
+
+A package repository (repo for short) is a dedicated hosting platform for
+modpacks. They are inspired by the package management systems of Linux
+distributions, Python, Rust and others. Package repositories have the following
+advantages:
+
+* Can be checked regularly for updates
+* Automatically download and install dependencies if they are in the same repo
+* Can store the history of modpacks (previous versions)
+* They can be searched by using keywords or content filters
+* Can sign modpacks to indicate trust (i.e. check for exploits or malware)
+
+Everyone can set up a package repository. Users can add an unlimted number of
+repositories in the openage launcher. Some repositories are added by default
+when openage is installed.
+
+Repositories are the preferred method of distributing mods.
+
+
+## Licensing
+
+Once a mod is out in the open, it's good to clarify how and what other creators are
+allowed to do with it. This can be done by adding a **license** to the
+modpack. Using a license is completely optional, but it makes sense to
+add one in some cases. For example, a license can specify how to give credit
+or whether files from a modpack are allowed to be integrated into other modpacks.
+
+The license can be chosen for every modpack individually by the creator.
+While the engine is licensed as GPLv3+, modpack licenses do not need to
+be compatible with it. Repos may decide which licenses they allow and
+reject. Additionally, they may offer a default license.
+
+When you copy (not reference) assets from modpacks of other creators,
+always check their license first. Copying files may be subject to terms set
+in the license. It is usually safer (and less frowned upon) to have the modpack
+referenced as a dependency than to copy files over.
+
+
+## Addressing Modpacks
+
+This section describes standards for addressing and referencing modpacks
+as well as administrative requirements for that purpose.
+
+
+### Naming Conventions
+
+Modpack and repository names can only contain these characters:
+
+* Letters from the latin alphabet (`a-z`, `A-Z`)
+* Numbers (`0-9`)
+* Separators (`-`, `_`, `.`)
+
+It is recommend to use at least 4 characters, but this is not mandatory.
+Repositories might enforce stricter rules on modpack names such as
+word filters or prefixes.
+
+Some repository names are reserved and cannot be used:
+
+* `openage`: Reserved for engine development by us and modpacks created by the converter
+* `local`: Internal repository name for modpacks that were not installed from a repository
+
+
+### Alias and Identifier
+
+There are two ways to reference a modpack: By using the modpack **identifier**
+or by using an **alias**. It is recommended to use aliases wherever possible
+and only use the identifier when it is absolutely necessary.
+
+The modpack identifier is a unique string that is composed of the modpack
+name and the repository name seperated by `@`.
+
+```
+modname@reponame
+```
+
+Mods that are not installed from a repository are referred to by using `local`
+as the repo name.
+
+```
+modname@local
+```
+
+----
+
+An alias is a string that is used as a quick reference for the modpack
+internally. By default, the alias is the name of the modpack, but it can
+also be assigned in the modpack definition file. Aliases must be unique
+at load time.
+
+```
+modname
+```
+
+Aliases can be utilized for replacing other modpacks. For example, an enhanced
+graphics pack for a mod can replace a normal graphics pack by assigning itself
+the same alias. References using the alias will then point to the enhancement
+graphics pack.
+
+
+### Version Pinning
+
+Sometimes a very specific version of a modpack can be required due to
+compatibility issues. This can be done by apending the requested version
+number to the modpack identifier separated by `::`.
+
+```
+modname@reponame::version
+```