Setting up mod_info.yaml and archived_versions

[Ipsquiggle]

TLDR: If the Mod Uploader is preventing you from uploading your mod because of a missing “mod_info.yaml”, place a file in your mod’s root directory with the following syntax:

# either or both of VANILLA_ID, EXPANSION1_ID, ALL
supportedContent: VANILLA_ID
# The build number of the last version of the game you tested your mod with
minimumSupportedBuild: 447213

 

---

 

Hello Modders! We know you’re all excited to start adapting your current ONI mods to work with the new Spaced Out! content. In preparation for this, we’ve added mod_info.yaml as a way to specify which version of the game your mod is compatible with. This is part of the short term plan outlined below for how to support both versions of the game.

Currently published mods will still function as intended, and the game will just assume they were designed for the base game. Going forward, the mod uploader will require mod_info.yaml, so all new mods need to declare which versions they support, and what build number of the game they were tested on.

mod_info.yaml Specs

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.

It contains two values: supportedContent and minimumSupportedBuild.

supportedContent

This lists the game versions this mod supports. At the moment, there are two versions:
VANILLA_ID <- Base game of ONI
EXPANSION1_ID <- Spaced Out!

For example, if your mod works in both versions of the game, your mod_info.yaml could specify

supportedContent: VANILLA_ID,EXPANSION1_ID

You can also use the keyword ALL if your mod has no compatibility issues.
 

supportedContent: ALL

minimumSupportedBuild

This is the build number displayed in ONI at the time that you publish your mod. This will allow supporting old versions of the game as well as preview versions of the game, so please get in the habit of updating this when you publish your mod.

minimumSupportedBuild: 447213

(If this sounds familiar to archived_versions.yaml, you're right! We have deprecated the archived_versions.yaml file for archiving, and use the values in mod_info.yaml instead.)

Supporting both Vanilla and Spaced Out! (plus preview!) with the archived_versions folder

We anticipate that several mods will not be able to support both versions of the game with the same build. Using mod_info.yaml, it will be possible to publish two or more builds of your mod in the same distribution, and the game will dynamically load the correct build based on whether the DLC is enabled.

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

MyOniMod/
|- mod_info.yaml (supportedContent:EXPANSION1_ID)
|- (normal mod contents)
|- archived_versions/
    |- vanilla_444111/
    |   |- mod_info.yaml (supportedContent:VANILLA_ID)
    |   |- (normal mod contents)
    |- expansion1_old/
        |- mod_info.yaml (supportedContent:EXPANSION1_ID)
        |- (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 what version and build number the player is currently on.

Let’s go over an example:

 

Spoiler

 

1. Suppose you've got a mod working with the base version of ONI, on version 441000. Add a mod_info.yaml with these contents:

supportedContent: VANILLA_ID
minimumSupportedBuild: 441000

 

2. You decide to update your mod to work with Spaced Out!, which is at 442000.

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

<your mod folder>/archived_versions/vanilla

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:

supportedContent: EXPANSION1_ID
minimumSupportedBuild: 442000

Develop your mod for the new expansion features and publish it in that root folder. Players on the base game will get the version from the archive folder, and players on Spaced Out! will get the version from the top-level folder.

 

3. Later, we open up a public_testing branch for Spaced Out! that changes the build number to 443000. As before, make a new archive folder called something like:

<your mod folder>/archived_versions/spacedout_old

and copy all your top-level mod files into it (including the mod_info.yaml).

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

supportedContent: EXPANSION1_ID
minimumSupportedBuild: 443000

You can update your mod for the preview branch and publish it in that root folder. Players on the newest preview version of the game will get the newest version of your mod, and players not on the previous will continue playing the previous 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 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, or vanilla players!

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 goes live!

What about old abandoned mods?

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.)

The Long Term Plan

It has always been the goal for the base game of ONI and Spaced Out! to share the same code base, and we plan to merge the two before Spaced Out! leaves Early Access. When this happens, it will be much easier for a single build of your mod to support both versions of the game, and DLC-specific behaviour can be run conditionally based on an API that we will provide.

We are working hard to make this a possibility, but cannot give a date as to when that will happen. Until then, give mod_info.yaml and the archived_versions folder a try! Happy modding!

 

---

What about Translations?

We're going to make all translation mods cross-compatible all the time by being careful about when we reuse existing strings vs. adding new ones. Those working on translations should always work from the newest possible .pot file (i.e. Spaced Out!, preview branch) and their translation will work with all versions of the game. If you have a reason for your translation to only work with certain DLC or during public_testing, you can still use the archive_versions described above.

If you just want to always work on the latest version, include a mod_info.yaml with these contents and you'll be good to go:

supportedContent: ALL
minimumSupportedBuild: 0

 

[Primalflower]

kanim stuff still appears to be borked

EDIT: i get lots of errors like this when loading mods that have anything to do with kanim files!

[18:49:53.482] [1] [ERROR] KAnimBatchManager is not ready when loading anim:anim_starfield_bg
KAnimBatchManager is not ready when loading anim:anim_starfield_bg 

my log for loading the mod "Fashionistic" is included:

Player.log

Edited January 12, 2021 by Lbphero
elaboration

[asquared31415]

Game errors when using a mod_info.yaml file, and refuses to show the mod. 

Attached is the yaml file used and the output log.

There exists only the content in the root directory, meant for use with spaced out DLC only.  Is this a misconfiguration or an error in the game?

edit: even using the provided example with supported ALL and version 0 doesn't load, same error

 

I also had issues with other mods that don't have yaml files creating more errors, but could not reproduce.

mod_info.yaml Player.log

The comment at the start of the mod_info.yaml file is apparently REQUIRED or it causes a parsing error.  This should be noted somewhere, or preferably fixed.

Upon further investigation, it was an encoding issue, the default encoding was UTF8 for my IDE and it caused a lot of issues

Edited January 12, 2021 by asquared31415

[Ipsquiggle]

48 minutes ago, Lbphero said:

kanim stuff still appears to be borked

Is this a mod you're developing, or something from the Workshop?

43 minutes ago, asquared31415 said:

Upon further investigation, it was an encoding issue, the default encoding was UTF8 for my IDE and it caused a lot of issues

We load mod_info.yaml as UTF8-encoded, so that's strange. Let me know if any other clues pop up.

[Primalflower]

1 minute ago, Ipsquiggle said:

Is this a mod you're developing, or something from the Workshop?

this is my own mod that im developing 

[asquared31415]

Opening that bad yaml file in a hex editor shows a `EF BB BF` byte sequence at the start which is definitely wrong.  Not sure how it happened.  I think it may have appeared from copy/pasting from the forums since it's rich text, and my editor didn't allow me to remove it.  It works now with the default UTF8 encoding without those weird bytes.  Sorry for bringing that up, it was my error somehow, but it seemed like it was something wrong with the game since it just said parsing errors for something that appeared identical.

[Ipsquiggle]

6 minutes ago, Lbphero said:

this is my own mod that im developing 

Gotcha. I'll take a look!

[asquared31415]

Here's an example log of a mod with anims failing to load.  This is from my Meep mod, which replaces some textures in the base game.  But the issue also happens for anything that tries to load a kanim.

Player.log

[Primalflower]

27 minutes ago, Ipsquiggle said:

Gotcha. I'll take a look!

just incase you did not see, I edited my original comment with a log of me crashing with my mod. 

[pether]

I'm not sure if I understand...

If my mod_info.yaml defines lastWorkingVersion as 441000 and later you guys release version 442000 do I need to update mod_info to version 442000 so my mod could be executed? (ofc assuming that the game code wasn't changed to the point my mod makes no sense, like patching non-existing methods). Or if I make some simple mod can I release it with info defining 441000, and then never look on it again with hopes that your next 3 years of update will not affect it at all?

@Ipsquiggle can you please clarify?

Edited January 12, 2021 by pether

[asquared31415]

I believe the game will try and find the mod version that matches the right content, and make sure that the tested version is less than or equal to the game's version.  So if you had archived versions with 441000 and 443000 and you were running game version 442000 (and they all have the right content) it would select the 441000 version.  If there were no higher versions, it would still see the latest version mod and use that, if I understand right.

[Ipsquiggle]

40 minutes ago, pether said:

I'm not sure if I understand...

If my mod_info.yaml defines lastWorkingVersion as 441000 and later you guys release version 442000 do I need to update mod_info to version 442000 so my mod could be executed? (ofc assuming that the game code wasn't changed to the point my mod makes no sense, like patching non-existing methods). Or if I make some simple mod can I release it with info defining 441000, and then never look on it again with hopes that your next 3 years of update will not affect it at all?

@Ipsquiggle can you please clarify?

The logic is this (in all cases for this example "archive" includes the mod in the root folder):

1. First we filter on supportedContent -- an archive is completely excluded if the current content doesn't match one of the entries in this list.
2. Then we look for the archive with the lowest lastWorkingBuild which is greater or equal to the game version. i.e. if you have mods at versions 6, 8, and 10, and the game is at v. 7, then it will load the mod for v. 8 which is the "lowest greater version".
3. If there is no "greater" mod than the game version, we take the highest lastWorkingBuild which is less than the game version. i.e. if you have mods at version 6, 8, and 10, and the game is at v. 15, then the mod for v. 10 will be used.

This logic might seem convoluted, but in practice it means this:

• So long as there is an archive that supports the current content (vanilla, spaced out), it'll load regardless of what number you have in there.
• If you have a mod working on the release branch, you don't need to update its build number unless you're adding a new archive.
• If we start a testing branch, make an archive whose lastWorkingBuild is the last "release" version you've seen it working with. Then make the new version for the testing branch with a (higher) testing branch lastWorkingBuild. The right users will get the right mod for each branch.
• If you did that, then when release "catches up" to the test branch, they'll automatically start using the new version of the mod. Old archives will sit there unused.

[McLeoud]

7 hours ago, Ipsquiggle said:

What about Translations?

And why there is no more preview pictures for translation mods in main menu?

[Cairath]

Hey @Ipsquiggle, thanks for the update. Have you guys thought about adding a workshop 'requires <insert dlc name>' thingy? It shows up when filtering mods, and steam would tell players that they do not have the required DLC to make use of the mod. Would be very useful for mods that are DLC-specific.

[Ipsquiggle]

16 hours ago, McLeoud said:

And why there is no more preview pictures for translation mods in main menu?

Preview pictures for translations seem to be working fine for me. Mind posting a screenshot and logfile in a new bug report?

6 hours ago, Cairath said:

Hey @Ipsquiggle, thanks for the update. Have you guys thought about adding a workshop 'requires <insert dlc name>' thingy? It shows up when filtering mods, and steam would tell players that they do not have the required DLC to make use of the mod. Would be very useful for mods that are DLC-specific.

In the workshop itself, you can mark a mod as requiring a DLC. It doesn't appear to allow filtering on search results itself, but when you view a specific mod it has a banner highlighting the needed DLC if the player doesn't have it. Is this what you're looking for?

[Cairath]

Yeeep, that was my "I'm blind" moment of the day, sorry :P

[Chirby]

My translation mod lost the preview image and now the upload fail 

[jonius]

return my DLC pleeeeeeeeeeeeeeeeeeeeeez 

[Ipsquiggle]

2 hours ago, Chirby said:

My translation mod lost the preview image and now the upload fail 

If you upload C:\Users\<username>\AppData\Local\Oxygen Not Included Uploader\ModUploader.log, I'll try and figure out what's happening here.

[McLeoud]

4 hours ago, Ipsquiggle said:

Preview pictures for translations seem to be working fine for me. Mind posting a screenshot and logfile in a new bug report?

I've just posted a screenshot and short description in bugs reports here:

https://forums.kleientertainment.com/klei-bug-tracker/oni/there-is-no-more-preview-pics-for-translation-mods-r28153/

Hope it'll help.

[Chirby]

15 hours ago, Ipsquiggle said:

If you upload C:\Users\<username>\AppData\Local\Oxygen Not Included Uploader\ModUploader.log, I'll try and figure out what's happening here.

Heereee it go!

ModUploader.log

[Swoop5994]

Well i have my C:\Users\User1\Documents\Klei\OxygenNotIncluded\Mods\Steam\''1818138009'' it seems there is a number folder for each mod with the modname.DLL(that is the root right ?

) in each one. i tried to copy paste the  ''mod_info.yaml''.in the same folder as the mod.DLL        My mod_info.yaml have the following lines inside:                                     supportedContent: ALL
                                                                                                             lastWorkingBuild: 447268 

 i aint got any mods who are working with my DLC...i did had a popup about the mod being installed when i openned the game but in the mod tabs there is still the not compatible with dlc description.

I've also looked into C:\Users\User1\Documents\Klei\OxygenNotIncluded\Mods\ mods.json all my suscribed mods are in there in form of a list they looks like that                                                                                                                                                        "label": {
                                                                          "distribution_platform": 1,
                                                                          "id": "1717463209",
                                                                          "version": 1567686205,
                                                                           "title": "Bigger Camera Zoom Out"
                                                                            },
                                                                           "status": 1,
                                                                           "enabled": false,      <=====
                                                                           "enabledForDlc": [],  <===== should i change something ?? 
                                                                           "crash_count": 0,
                                                                           "reinstall_path": null

 

Maybe i have to install the mods manually without the workshop ?? or unsuscribe from the beta_branch ?? anyone got a clue of how i could make some the mods works ? (im suscribed on the workshop with roughly 150 and none of them is working atm)

 

Thanks everyone

 

Please can i have some help i dont know what to do next...

Edit : my game is on another drive than the C: it is in D: program files could that be part of my problem ?

Edited January 14, 2021 by Swoop5994

[Rainbowdesign]

If klei makes an update but my mod still works do i have to still make a change to lastworking build to have it continue working or can i just leave it as it is?

[pether]

@Rainbowdesign here is already answer for you:

On 1/12/2021 at 10:56 PM, Ipsquiggle said:

The logic is this (in all cases for this example "archive" includes the mod in the root folder):

1. First we filter on supportedContent -- an archive is completely excluded if the current content doesn't match one of the entries in this list.
2. Then we look for the archive with the lowest lastWorkingBuild which is greater or equal to the game version. i.e. if you have mods at versions 6, 8, and 10, and the game is at v. 7, then it will load the mod for v. 8 which is the "lowest greater version".
3. If there is no "greater" mod than the game version, we take the highest lastWorkingBuild which is less than the game version. i.e. if you have mods at version 6, 8, and 10, and the game is at v. 15, then the mod for v. 10 will be used.

Your case is #3: if you had a mod working on version 10, then game updated to version 15 but your mod didn't, it will still be used.

[Solra Bizna]

On 1/12/2021 at 12:21 PM, asquared31415 said:

Opening that bad yaml file in a hex editor shows a `EF BB BF` byte sequence at the start which is definitely wrong.  Not sure how it happened.  I think it may have appeared from copy/pasting from the forums since it's rich text, and my editor didn't allow me to remove it.  It works now with the default UTF8 encoding without those weird bytes.  Sorry for bringing that up, it was my error somehow, but it seemed like it was something wrong with the game since it just said parsing errors for something that appeared identical.

A lot of text editors, including Notepad, like to put those bytes at the beginning of a UTF-8-encoded text file as a misguided way of marking it as UTF-8. It's the UTF-8 version of the "byte order mark" that appears at the beginning of a UTF-16 text file to mark it as big- or little-endian UTF-16—a question which does not apply at all to UTF-8. In programming contexts (markup, program code) all it does is destroy the number one advantage of UTF-8, by putting a bunch of garbage at the beginning of what is otherwise an ASCII-ish text file. A lot of compilers and parsers have a kludge where they go out of their way to ignore that byte sequence at the beginning of the file, but apparently not Klei's YAML parser.

tl;dr the problem isn't you, it's Notepad.