Skip to content

Packaging

This page contains all information related to how packages are structured and distributed.

The following sections contain information specifically about how reloaded3 packages are structured.

Other systems may use slightly different layout and/or feature set.

Package Structure

Each mod package contains the following approximate structure.

reloaded3.utility.examplemod.s56
├── config
│   └── config.toml
├── languages
│   ├── config
│   │   ├── en-GB.toml
│   │   └── uwu-en.toml
│   └── dll
│       ├── en-GB.toml
│       └── uwu.toml
├── modfiles
│   ├── redirector
│   │   └── skill-game-asset.bin
│   └── mod.dll
├── package
│   ├── docs
│   │   ├── changelog
│   │   │   ├── 1.0.0.md
│   │   │   ├── 1.1.0.md
│   │   │   ├── 1.2.0.md
│   │   │   ├── 1.2.1.md
│   │   │   └── 2.0.0.md
│   │   └── index.html
│   ├── images
│   │   ├── config-image-1.jxl
│   │   ├── skill-1.jxl
│   │   ├── skill-2.jxl
│   │   └── skill-3.jxl
│   ├── description.md
│   └── license.md
└── package.toml

The specification for package.toml can be found at Package Metadata.

The specification for config.toml can be found at Configuration Schema.

The specification for the languages folder can be found at Localisation.

Changelog

Located in package/docs/changelog.

This contains the changelog for each version of the mod up until the current version.

Each version is contained in its own Markdown file, e.g. 1.0.0.md.

Having Docs is not required to have Changelogs

The Changelog exists in the docs part of the folder because they commonly share images. It also allows you to have the Changelogs as separate documentation pages.

Some documentation building tools may require that all images are within a certain subfolder, thus to allow image reuse, we put the changelog pages within the docs folder.

Config

Located at config.toml.

This contains the configuration for the mod.

This file may not exist in some packages.

This file stores the configuration schema used for the package when the user hits Configure Mod (or equivalent) button inside the Mod Manager frontend.

Images referenced by the config should be in the package/images folder.

Description

Located at package/description.md.

This contains the full description of the package, written in markdown.

For a mod, this should match what you would normally put on a modding site (e.g. GameBanana, Nexus, ThunderStore) etc.

Docs

Located in package/docs.

Entry point for this package documentation.

This is the file that will be opened when the user wishes to click the documentation button in Mod Manager.

This should be a file in a format the user can be reasonably expected to open on a Windows or Linux machine.

Currently accepted formats include:

  • HTML (.htm, .html)
  • Markdown (.md)
  • PDF (.pdf)
  • Text (.txt)

The entry point for the documentation is specified in the DocsFile field in the package.toml.

We recommand using MkDocs Material in CI for the documentation.

Images

Located in package/images.

Images use JPEG XL (.jxl)

This contains any supplementary images that are used in the package. These images can be referenced from the main package.toml file, for example in gallery items.

They can also be used in any other supporting files, such as workflows or configuration files.

This is a unified images folder

When used in the Reloaded3 ecosystem, all images are in this folder to allow for deduplication.

However the individual components such as workflows, configs etc. are designed to allow for setting an arbitrary folder when used outside of the R3 ecosystem.

License

Located at package/license.md.

License defaults to CC BY-NC-SA 4.0.

Design Philosophy

Packages Should be Self Contained

For historical preservation, we should strive to make packages as 'self contained' as possible.

That means including the following in each package:

  • A full description for each mod, as you'd find in a mod page.
  • Documentation on how to use the mod, e.g. mkdocs website.
  • Complete changelog for the mod (down to first version).

A package does not need to contain assets for previous versions, only changelogs.

Where are Packages Stored?

Reloaded3 packages are by default stored in a machine persistent Packages folder.