Basic Mod Pack Metadata specifications

[MrJeranimo]

This discussion is for decided the basic specifications of Mod Packs for KSA. The list below is not final and is just the properties I can think of. Please comment if you have anything to add or notice anything that may cause issues.

Properties

1. ModPackId: The constant unique Id of the Mod Pack. Does not have to follow the same rules as a Mod's ModId as KSA doesn't handle Mod Packs, only mods.

2. Display Name: The name that will show up on UI. Doesn't have to be unique, can use a wider set of characters, and can be longer than the ModPackId.

3. Author(s): The author(s) of the Mod Pack.

4. Version: The version of the Mod Pack. I also think this should be Major.Minor.Patch[-PreRelease] following the same rules as the proposed Mod versioning for simplification.

5. Built For Game Version: The game version the Mod Pack is built for. The mods themselves don't have to be built against the same version as long as the creator guarantees they will work. Uses KSA versioning Scheme and a single version can be built against multiple versions at the same time.

6. Description: The description of the Mod Pack.

7. Mod Loader: If the Mod Pack is intended to be used with a mod loader, which mod loader it is and which version.

8. Mods: A list of (ModId, Version) that list what mods and their version the Mod Pack is made of.

9. Released At: The date (and time?) this version of the Mod Pack was released.

10. Changelog: The changelog of this version of the Mod Pack. Can be a string or a link/path to the changelog.

11. Tags: A list of tags/categories the Mod Pack falls under (Contracts, Story, Cinematic, etc.).

12. License: The license of the Mod Pack. Can be either the name of a license (for popular ones) or a link/path to the license file. This is one I am not sure on, as I don't know if Mod Packs need a license.

[Maximilian-Nesslauer]

This list is about 80 percent the same as #15
Id, display name, authors, version, game version, description, loader, release date, changelog, tags, license all appear in both.
If the two become separate RFCs, they drift apart, and every future content type adds a third copy.

I propose one shared metadata core for every content type, and a small per-type extension.
The pack extension is then almost only the mod list.
I would fold #15 and #16 into one format RFC with two extensions rather than two parallel RFCs.

On the individual points:

1 (ModPackId): I would pull in the opposite direction: same id rules for every content type, not laxer ones for packs. The pack id ends up in file paths just like a mod id does, Borea's own instance folders get created from packs, and a second, laxer id space next to the strict one from #15 would just add a second namespace we have to differentiate between. I would like to use one id spec for everything to not cause confusion.
This would only open this question: is the id namespace global across content types, so a mod and a pack can never share an id? I would say yes, global, because then every reference to an id stays type-free.

5 (Built For Game Version): same situation as #15 property 6 i commented on in #15 (comment) , this is what #17 is about.

8 (Mods list): Makes sense.
Here I think your exact pins are right, and I want to say that explicitly because it looks like it contradicts what I wrote on #15 property 8 #15 (comment) . It does not.
A dependency says "I need X to function", and that is a range, because any X in the range works. A pack says "this exact set is what I curated and tested".

12 (License), and the question behind it: whether a pack needs a license depends on a property your list does not pin down, and which I think is an important open decision here:
is a pack pure reference metadata, or can it carry files, configs, tweaks, the way Minecraft or StardewValley packs do?
I would fix phase 1 to pure reference: the pack is its metadata, there is no archive, no download location, no checksum, and it never redistributes anyone's mod files, downloads keep coming from each mod's own host. Then the license question becomes small, the license covers the pack's own list, description and artwork, and something permissive for metadata is the natural default.
I believe that Packs that carry modpack specific config files are a real use case, but they reopen hosting, checksums and the licenses of whatever is inside, so I would name them as a deliberately postponed extension rather than deciding them now.

[Maximilian-Nesslauer]

Same as in #15 (worked example there), for a pack.
This pack does not exist.

spec_version = 1
id = "NavigationStarterPack"
type = "modpack"
name = "Navigation Starter Pack"
authors = ["Maxi"]
abstract = "Everything you need for maneuver planning, tested together."
license = "CC0-1.0"
tags = ["navigation"]
version = "1.0.0"

[compatibility]
game_min = "2026.8.3.5117"

# Exact pins, not ranges: a pack is a curated, tested set.
# A mod's own dependencies stay ranges; see my comment above for why both are right.
[[mods]]
id = "AdvancedFlightComputer"
version = "0.7.0"

[[mods]]
id = "KittenExtensions"
version = "0.4.0"

[MrJeranimo]

1. Add Vehicles and Games Saves

I was wondering if we should also include a Vehicles and Game Saves section within Mod Packs. I was thinking along the line of how Minecraft Mod Packs can also include shaders and world saves, despite being Mod Packs, and figure it might be a nice QOL for content creators to be able to include them.

I propose to keep the type name the same as the main use will be for a group of Mods, with the Vehicles and Game Saves as an addition.

I do want to ask, if we agree to put Vehicles and Game Saves in a Mod Pack, should we immediately give them a [[vehicles]] and [[saves]] section. Or should we wait till the designs for those are done and then add them later.

Adding support later won't break the format and invalidate the old data since it is a clean addition, but it most likely will require a spec_version increase to stay consistent. As for adding support now, they can stay empty until Borea or whichever manager is able to support it. I prefer adding support now.

2. Should we split Mod Packs into 1 authored, many versioned files?

I was wondering if we should split Mod Packs into 1 authored TOML file and many JSON versioned files due to similar reasons for why we did it to Mods. A Mod Pack's properties 1, 2, 3, 6, 7, 11, and 12 all are unlikely to change between Mod Pack versions, so I propose keeping them in an authored TOML file. As for properties 4, 5, 8, 9, and 10, they are much more likely to change each version of the Mod Pack, thus I think they should get JSON versioned files.

Granted this assumption does assume that Mod Packs are allowed to have multiple versions like Minecraft Mod Packs, of which I am in favor of allowing.

[MrJeranimo]

Forgot to mention for question 2, we can also let the versioned files be TOML as there is no download URL for a watcher to check if there is a new version. As such each version will not be an automated version file but instead be manually updated by the creator which means these files can all be TOML.

Also thinking about this more, since there is no need for a watcher -one of the biggest reasons why in the Mods have a versioned and author files- the need/benefits of splitting Mod Packs into two files is greatly reduced.

[Maximilian-Nesslauer]

1. Vehicles and saves

Yes i believe that your suggestion makes sense. Maybe in this shape?

[[mods]]
id = "AdvancedFlightComputer"
version = "0.7.0"

[[vehicles]]
id = "ReusableBoosterDemo"
version = "1.2.0"

[[saves]]
id = "ApolloRecreation"
version = "1.0.0"

I thought about the other way first, one generic [[content]] list carrying a type field, on the grounds that a new content type would then need no format change at all.
But i think that this reads better.

On your now-or-later question: now.

Given the shared entry shape there is not much left to guess, and RFC 0025 already puts vehicles and saves in scope, so defining all three sections in spec_version = 1 costs nothing today and saves a version bump on the day they land.
Only reason to wait would be a type that cannot be expressed as id plus version, and I do not think either of these is.

Nested packs, a pack listing another pack, are the obvious next question and I would rule them out for now.

2. Splitting packs

Agreed because the mod side is split because a watcher stamps a generated file per release without a human.
A pack has no download URL, so there is nothing to watch, so there is no generated half.
Packs stay one authored TOML.

3. My remaining questions is where the pack's versions live.

Since a pack is pure reference metadata with no archive (my position further up this thread, phase 1), the index stores the pack files themselves, and the simplest answer is one file per pack version, e.g. packs/<id>/<version>.toml.
Then a pack version is immutable once published, the same property a generated mod release file has, and the history stays readable.

The fields that are per-release on the mod side (version, game_min, released_at, changelog) are then authored by hand here.
That is fine, because publishing a pack version is a human act anyway, there is no release event to react to.