Skip to content

Commit

Permalink
Docs: Separate Package and Mod Metadata
Browse files Browse the repository at this point in the history
  • Loading branch information
@Sewer56
Sewer56 committed Apr 7, 2024
1 parent 58a8032 commit 002c41f
Show file tree
Hide file tree
Showing 6 changed files with 277 additions and 170 deletions.
2 changes: 1 addition & 1 deletion docs/Loader/Backends/CoreCLR.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -304,7 +304,7 @@ A mod translates Reloaded-II APIs to Reloaded3 APIs. That's about it.
[dotnet-sdk-download]: https://dotnet.microsoft.com/en-us/download/dotnet/7.0
[features]: ../../Server/Features.md
[native-hosting-locate-hostfxr]: https://github.com/dotnet/runtime/blob/main/docs/design/features/native-hosting.md#locate-hostfxr
[package-id]: ../../Server/Configurations/Package-Metadata.md#id
[package-id]: ../../Server/Packaging/Package-Metadata.md#id
[reloaded-ii-nethost]: https://github.com/Reloaded-Project/Reloaded-II/tree/master/source/Reloaded.Mod.Loader.Bootstrapper/nethost
[r2-alc]: https://reloaded-project.github.io/Reloaded-II/DependencyInjection_Consumer/
[r2r-compilation]: https://docs.microsoft.com/en-us/dotnet/core/deploying/ready-to-run
Expand Down
156 changes: 4 additions & 152 deletions docs/Server/Configurations/Mod-Metadata.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,90 +2,18 @@

!!! warning "Work in Progress"

!!! info
!!! info "Describes the format of `Package.toml` for mods."

Describes the syntax of the minimal config file used to store mod metadata.

Inside each mod folder is a file named `R3ModConfig.json`; which stores the metadata of each mod.
Mod Metadata extends from standard package metadata ([Package.toml][package-toml]).

| Type | Name | Description |
| -------------------------------- | ---------------------------------- | ----------------------------------------------------------------- |
| string | [Id](#id) | A name that uniquely identifies the mod. |
| string | Name | Name of the mod. |
| string | Author | Main author(s) of the mod. Separate multiple authors with commas. |
| SemVer | [Version](#version) | Semantic versioning version of the mod. |
| string | Description | Short description of the mod. (<= 200 chars) |
| string[] | [Tags](#tags) | Used to make searching easier within mod managers. |
| string | [Icon](#icon) | Relative path of preview icon. |
| bool | [IsLibrary](#is-library) | If true this mod cannot be explicitly enabled by the user. |
| UpdateData | [UpdateData](#update-data) | Stores mod update specific information. |
| DependencyInfo | [Dependencies](#dependency-info) | Stores information about this mod's dependencies. |
| string | SourceUrl | Link to source code (if applicable). |
| string | ProjectUrl | Link to website to learn more about the project. |
| Dictionary&lt;string, Target&gt; | [Targets](#targets) | Specifies the DLLs/binaries used [for each backend.][backend] |
| string[] | [SupportedGames](#supported-games) | List of supported titles/games. |

## Id

A name that uniquely identifies the mod.

The suggested format to use for names is `game.type.subtype.name`.

- `game` should ideally match [App 'Id'][app-metadata-id] for the given application.
- `type` name should ideally match category of the mod on a site like [GameBanana](https://gamebanana.com) or [NexusMods](https://www.nexusmods.com).
- `subtype` [Optional] provides additional information about the item.
- `name` unique identifier for the mod. Can use another `.` dot if additional info is needed.

Example(s):

- `sonicheroes.skins.seasidehillmidnight`
- `sonicheroes.skins.seasidehill.midnighthill`

Use lowercase, no spaces, no special characters.

### Non-Game Specific Components

!!! note

For mods that are non-game specific such as backends; set the `game` identifier as `reloaded3` and use one of the following.

| Type | Description | Example |
| ------- | ------------------------------------------------- | --------------------------- |
| backend | For [backends][backend]. | `reloaded3.backend.coreclr` |
| api | For [middleware/API hooks][middleware-api-hooks]. | `reloaded3.api.windows.vfs` |
| utility | For utility mods with reusable code. | `reloaded3.utility.hooks` |

Mod manager can choose whether to show non game-specific mods (`reloaded3` id) on a specific game's page or not.

## Version

!!! info

This stores a mod version specified using a [Semantic Versioning][semantic-versioning] compatible standard.
This is required for update support.

!!! warning

For legacy mods converted from other loaders. If a non-semver version is used, we strip all spaces and write it as `0.0.0.{originalVersion}`.

## Tags

!!! info "Used to make searching within mod managers easier; i.e. `filter by tag`."

These are completely arbitrary, up to end users.
The default set of suggested tags include:

| Tag Name | Description |
| ------------ | ----------------------------- |
| GUI/HUD | Any 2D element on the screen. |
| Stage/Level | Self explanatory. |
| Character | Playable characters. |
| 3D Model | Any non-Player 3D model. |
| Pack | Compilation of several mods. |
| Sound Effect | Sound effects. |
| Music | Music to enjoy. |
| Texture | Texture overhauls. |

## Icon

!!! info "Stores path relative to folder `ModConfig.json` is stored in."
Expand All @@ -100,81 +28,6 @@ The default set of suggested tags include:

!!! info "Some libraries may have user [configuration(s)][mod-configurations]. Manager is free to hide other libraries."

## Update Data

!!! info

Information tied to Reloaded3's update library. This info is stored in a way that avoids direct dependency
on Update library by using an `Abstractions` package.

!!! note

This section might be moved to dedicated Update library section.

| Type | Name | Description |
| -------------------- | ------------------------------------------------------ | ---------------------------------------- |
| string | [ReleaseMetadataFileName](#release-metadata-file-name) | A name that uniquely identifies the mod. |
| GameBananaUpdateInfo | [GameBananaUpdateInfo](#gamebanana-update-info) | Info on how to update from GitHub. |
| GitHubUpdateInfo | [GitHubUpdateInfo](#github-update-info) | Info on how to update from GameBanana. |
| NexusUpdateInfo | [ReleaseMetadataFileName](#nexus-update-info) | Info on how to update from Nexus. |
| NuGetUpdateInfo | [NuGetUpdateInfo](#nuget-update-info) | Info on how to update from NuGet. |
| DependencyInfo | [DependencyInfo](#dependency-info) | A name that uniquely identifies the mod. |

### Release Metadata File Name

!!! info "This filename is used by Update Library to fetch information about current version on GitHub/Nexus/GameBanana/etc."

This name defaults to `{Id}.ReleaseMetadata.json` upon the creation of a mod and should never be modified by the end user
unless they know what they're doing.

### GameBanana Update Info

| Type | Name | Description |
| ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| string | ItemType | Type of item on GameBanana API, e.g. 'Mod', 'Sound', 'Wip' |
| int | ItemId | Id of the item on GameBanana, this is the last number in the URL to your mod page; e.g. 150115 if your mod URL is https://gamebanana.com/mods/150115. |

### GitHub Update Info

| Type | Name | Description |
| ------ | -------------- | ------------------------------------------------------------------------------------- |
| string | UserName | The user/organization name associated with the repository to fetch files from. |
| string | RepositoryName | The name of the repository to fetch files from. |
| bool | AssetFileName | [Optional] Pattern for the file name to download if no metadata file is found. |
| bool | UseReleaseTag | [Optional] If true, uses the release tag to denote version of the package as speedup. |

The field `AssetFileName` is provided for backwards compatibility only. e.g. `*update.zip` will look for any file ending with `update.zip`

### Nexus Update Info

!!! warning "Implementation delayed until API allows non-premium members to generate download links."

| Type | Name | Description |
| ------ | ---------- | ----------------------------------------- |
| string | GameDomain | The ID/Domain for the game. e.g. 'skyrim' |
| int | ModId | Unique index for the mod. |

### NuGet Update Info

| Type | Name | Description |
| -------- | --------------------- | -------------------------------------------------- |
| string[] | DefaultRepositoryUrls | List of NuGet URLs/repos this mod can update from. |

## Dependency Info

!!! info "The dependency resolution strategy is to simply copy update info of all dependencies into this structure. We can use that info to resolve mods if they are missing."

| Type | Name | Description |
| -------------- | -------------- | --------------------------------------------------------------- |
| DependencyItem | DependencyItem | A tuple of mod ID and copy of mod's [UpdateData](#update-data). |

`DependencyItem` is defined as:

| Type | Name | Description |
| ---------- | -------------------------- | --------------------------------------- |
| string | ModId | Unique ID of the dependency. |
| UpdateData | [UpdateData](#update-data) | Stores mod update specific information. |

## Targets

!!! info "This section specifies info for the individual [backends.][backend]"
Expand Down Expand Up @@ -237,9 +90,8 @@ Mod managers will automatically update this to appropriate ID during process of
[backend]: ../../Loader/Backends/About.md
[community-repository]: ../../Services/Community-Repository.md
[coreclr-backend]: ../../Loader/Backends/CoreCLR.md
[middleware-api-hooks]: ../../Loader/Core-Architecture.md#middlewareos-handling-mods-layer-1
[mod-configurations]: ./Mod-Configurations.md
[native-backend]: ../../Loader/Backends/Native.md
[package-toml]: ../Packaging/Package-Metadata.md
[ready-to-run]: ../../Loader/Backends/CoreCLR.md#ready-to-run
[reloaded2-backend]: ../../Loader/Backends/CoreCLR.md#reloaded-ii
[semantic-versioning]: https://semver.org
[reloaded2-backend]: ../../Loader/Backends/CoreCLR.md#reloaded-ii
17 changes: 0 additions & 17 deletions docs/Server/Configurations/Package-Metadata.md
View file

This file was deleted.

6 changes: 6 additions & 0 deletions docs/Server/Packaging/About.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
## Packages Should be Self Contained

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

That means including a full description for each mod, as you'd find in a mod page and documentation
for each mod.
Loading

0 comments on commit 002c41f

Please sign in to comment.