Setting up mod_info.yaml and archived_versions

[EricKlei]

This post covers how to set up mod_info.yaml to get your mod loading, and how to use archived versions to support multiple versions of the game such as live release and public testing.

mod_info.yaml

This file contains information to determine whether your mod should be loaded by the game. You'll need a copy of this file in the root of your mod, as well as in the root of each archived version of your mod (if you have any). 

Make sure the file is saved with UTF-8 (no signature) encoding.

Here's what a minimal version looks like:

minimumSupportedBuild: 652372 # replace with the build you tested your mod with
version: 1.0.0
APIVersion: 2

Full specification

Spoiler

minimumSupportedBuild (required)

This is used to determine if your mod should be loaded, and which archived version of your mod to load. Please get in the habit of updating this number when you publish your mod as it will make using archived versions easier.

minimumSupportedBuild: 622115

 

requiredDlcIds & forbiddenDlcIds (optional)

If your mod requires or forbids certain DLCs, you can specify those configurations using requiredDlcIds and forbiddenDlcIds. The game won't load mods with requirements that don't match the currently active DLCs. If you mod has no restrictions, simply omit this info from mod_info.yaml.

For example, if you're working on a mod which adds new bionic boosters, then your mod requires The Bionic Booster Pack (DLC3). You'll want to add the info below to your mod_info.yaml file:

requiredDlcIds: 
- DLC3_ID

You can also forbid DLCs, though it's very unlikely you'll want to do this. The most likely use case for forbidding a DLC would be base game rocketry mods. In that case you would want to forbid Spaced Out! like this:

forbiddenDlcIds:
- EXPANSION1_ID

If your mod contains a mixture of content for all versions of the game and content that requires specific DLCs then this system probably won't help you. You'll need to instead rely on the DLC checks in DlcManager (installed) and Game (active in save).

List of valid options:

• EXPANSION1_ID = Spaced Out!
• DLC2_ID = The Frosty Planet Pack
• DLC3_ID = The Bionic Booster Pack
• Future DLCs will maintain the DLC#_ID format.

Note that VANILLA_ID and ALL are not valid options.

 

supportedContent (deprecated)

This is deprecated as of U55 (March 2025). It was previously used to specify whether a mod was compatible only with the base game (VANILLA_ID), Spaced Out! (EXPANSION1_ID) or both (ALL). The original guide describing it can be found here. This format is still supported, but should only be used for archived versions of mods intended for older versions of the game that don't support the newer requiredDlcIds/forbiddenDlcIds format. 

 

version (optional)

This appears on the mods screen in game. It is used for display purposes only, not for determining which archived version to load. It's prefixed with a "v" in game.

version: 1.0.0

 

APIVersion (required)

This is required for mods which included DLLs, though it is always recommended you include this line.

APIVersion: 2

 

Supporting multiple versions of the game with the archived_versions folder

It is possible to publish two or more builds of your mod in the same distribution, and the game will dynamically load the correct build.

Create a folder in the root directory of your mod called “archived_versions”. This directory can, in turn, contain multiple directories: one for each version of your mod that you wish to archive.
 

MyOniMod/
|- mod_info.yaml
|- (normal mod contents)
|- archived_versions/
    |- update49_old/
    |   |- mod_info.yaml
    |   |- (normal mod contents)
    |- update50_old/
        |- mod_info.yaml
        |- (normal mod contents)

Each of these archived versions should have their own mod_info.yaml, which the game will use to determine which version to load. The mod that you’re actively developing should stay in the root directory, also with a mod_info.yaml

The game will now load the root mod, or one of the archived versions, based on the build number the player is currently on.

Let’s go over an example:

Spoiler

1. Suppose you've got a mod working on the the live branch, on version U50-441000 with this mod_info.yaml contents, and publish your mod.

minimumSupportedBuild: 441000
version: 1.0.0
APIVersion: 2

2. Later, we start a public_testing branch for the new update which is U51-442000.

First: make a new folder and subfolder in your mod for archiving the current version of your mod, named something like:

<your mod folder>/archived_versions/u50_44100

and copy all your mod files (including the mod_info.yaml) into that subfolder.

Then change the mod_info.yaml in the root folder of your mod to these contents:

minimumSupportedBuild: 442000
version: 1.1.0
APIVersion: 2

You can update your mod for the public_testing branch and publish it in that root folder. Players on the public_testing version of the game will get the newest version of your mod, and players not on the public_testing version will continue playing the preceding version from the archive folder.

You can of course delete old archived versions as the progress of the game moves forward.

With a correctly configured mod_info.yaml set in the root and in each archive’s directory, you can publish a version of your mod that supports the changes in the public_testing branch without breaking your mod for players on the live branch!

This means you can publish your changes while working on public_testing branch, and when that branch goes live, your subscribers will immediately start loading the correct version! No more scrambling to upload your mod as soon as public_testing becomes the live branch!

---

Changelog

• March 2025 - Updated to include new requiredDlcIds & forbiddenDlcIds formatting introduced in U55.

[Sanchozz]

Wait.
Have you changed the algorithm ?
Right now the mods with  supportedContent: VANILLA_ID,EXPANSION1_ID  work fine with the beta version of The Frosty Planet Pack.
ill it all be broken ?
And we'll have to re-upload all the mods ?

[EricKlei]

I will be giving this some more thought but wanted to quickly reassure you the algorithm hasn't changed during the beta. You are correct, mods with supportedContent: VANILLA_ID,EXPANSION1_ID will load The Frosty Planet Pack and do not need to be updated.

[zerstrick]

On 7/17/2024 at 7:33 PM, EricKlei said:

A mod which hasn't been updated with a mod_info.yaml will be assumed to be compatible with only vanilla for now as that's the most likely case. (Translation mods default to being compatible with all versions.)

Translations mods no longer need the mod_info.yaml?

[EricKlei]

14 hours ago, zerstrick said:

Translations mods no longer need the mod_info.yaml?

I've removed that section, it was only relevant for translation mods uploaded before January 2021. It's not possible to upload a mod without mod_info.yaml.

Also changed the example from The Frosty Planet Pack to Spaced Out! for now while we review how to better handle additional DLCs.

 

[EricKlei]

I'm working on an updated version of this guide but quickly wanted to mention the new requiredDlcIds and forbiddenDlcIds format in the public testing branch for U55 is a list, for example:

requiredDlcIds:
- EXPANSION1_ID

If your mod doesn't have any restrictions simply remove supportedContent.

[EricKlei]

The first post has been updated with U55 changes to requiredDlcIds/forbiddenDlcIds, please give it a read and let me know if you have any questions or feedback.

[Sanchozz]

I wanted to run the live version of the game (U54) just to make sure I set up the archived_versions correctly and didn't forget anything.
But it crashes when it sees any mod in the Dev folder with the omitted supportedContent in the mod_info.yaml file.
Even if the mod has a higher minimumSupportedBuild.
Even if the mod is disabled.

Sadly. I usually prefer to check everything carefully before uploading it to the workshop.
PS everything is fine with the mods in the Steam and Local folders.

Quote

[06:11:13.316] [1] [INFO] Test Mod (Test): Setting up mod.
[06:11:13.384] [1] [INFO]     Test Mod has a mod.yaml with a staticID `Sanchozz.ONIMods.Test`, using that from now on.
[06:11:13.390] [1] [ERROR]     Test Mod: mod_info.yaml in folder 'root' does not specify supportedContent. Make sure you spelled it correctly in your mod_info!
    Test Mod: mod_info.yaml in folder 'root' does not specify supportedContent. Make sure you spelled it correctly in your mod_info!
[06:11:13.588] [1] [WARNING] Test Mod: No mod_info.yaml found, default its supported content to 'VANILLA_ID'
[06:11:13.594] [1] [INFO]     Test Mod: Found valid mod_info.yaml in folder 'archived_versions/previous_U53': ALL at 643502
[06:11:13.598] [1] [INFO] Test Mod: Successfully loaded from path 'archived_versions/previous_U53' with content 'DLL'.

Quote

minimumSupportedBuild: 658890
version: 1.0.0
APIVersion: 2

mod_info.yaml

[EricKlei]

Unfortunately you'll need to use the local folder to test your mod on older versions of the game. If you prefer you can continue using supportedContent. After the follow update (U56) releases in the future both the live and previous update branches will contain support for required/forbidden.

[sakura_sk]

On 3/7/2025 at 9:51 PM, EricKlei said:

Unfortunately you'll need to use the local folder to test your mod on older versions of the game.

Does that mean that the U54 as "previous version" won't work for mods when U55 releases?

[EricKlei]

Mods will still work on U54 as long as there's a version (root or in archived_versions) with supportedContent defined. The issue Sanchozz is describing only happens if the mod is in installed in the mods/dev folder since there is additional error checking to give modders feedback when their mod is configured incorrectly. When installed in mods/local or /mods/steam this error message is downgraded into a warning and will not crash the game.

[SGT_Imalas]

The logging for the dlc limitations is a bit broken atm, it logs the required list entries for the "forbiddenDlcIds" info

"[...] forbiddenDlcIds='{packagedModInfo.requiredDlcIds.DebugToCommaSeparatedList()} [...]"