ONI Is Upgrading to Harmony 2.0! (2024)

Hello modders!

Over the course of this last year, many in this community have requested that we update the version of Harmony that we ship with the game, in order to smooth out mod development and make sure modders have access to the latest features the Harmony API provides! We're also making some improvements to our mod-loading process at the same time, so that all the breakage happens at once.

Beginning June 24th, we will be shipping Harmony in all Spaced Out! versions of the game.

This upgrade will require modders to update all .dll mods!

It is also the case that the major code changes we're doing right now are going to break a significant number of mods, and later when the Vanilla and DLC codebases are finally fully merged, all the existing Vanilla .dll mods will have broken anyways. We'd rather not break any mods at all, but since it's going to happen, we're opting to put all the breakage into a single update, and this gives you some time to prepare.

The Mergedown Process -- Use mod_info.yaml

As we unify the codebases, all these changes (including the Harmony 2.0 update) will slowly roll down through various versions of the game, like this:

Players who own Spaced Out! are now running this new code (whether the DLC is toggled on or off from in-game).

The changes will be coming to all ONI players in the next couple updates, but for the time being there will still be two codebases of the game.

Once your mod has been made compatible, it will remain compatible for the rest of the Mergedown. (Breakage from normal ongoing development aside ONI Is Upgrading to Harmony 2.0! (1) ) Be sure to use mod_info.yaml and the archive folder to separate the versions of your mod and make the transition seamless for your users! (More details below)

How do I update my mod?

There are several key changes you'll need to make:

1. Change all using Harmony; to using HarmonyLib; in your code

ONI Is Upgrading to Harmony 2.0! (2)

2. One class in your project must subclass KMod.UserMod2. (This is the main entrypoint class that will host OnLoad and contain references to your mod data.)

ONI Is Upgrading to Harmony 2.0! (3)

3. If you currently use void OnLoad(HarmonyInstance harmony), change it to override void OnLoad(Harmony harmony) on your UserMod2-derived class. Note that the type of the harmony class passed in has changed as well!

ONI Is Upgrading to Harmony 2.0! (4)

Note: if you override OnLoad, you will have to call harmony.PatchAll() yourself, or handle patching manually.

4. Make sure your project targets .NET Framework 4.7.1. You may need to install this from the Visual Studio installer in the tools menu.

ONI Is Upgrading to Harmony 2.0! (5)

5. Update your mod_info.yaml to indicate you're using the new API version

ONI Is Upgrading to Harmony 2.0! (6)

6. In mod_info.yaml, "lastWorkingBuild" has been renamed to "minimumSupportedBuild" (and has improved behaviour, as described in this post)

ONI Is Upgrading to Harmony 2.0! (7)

7. Finally, two new fields have been added to help users and other modders interact with your mods, please take the time to fill them out!

First is "version" in mod_info.yaml. This is a string of numbers and periods that will show up on the mods screen in-game for users.

ONI Is Upgrading to Harmony 2.0! (8)

Second is "staticID" in mod.yaml. The "staticID" will be used as the ID for the Harmony instance, and can be referenced by other mods to more easily cooperate with your mod.

(For those who don't know, you can add a single mod.yaml file in the root folder of your mod. This allows your mod to contain descriptive information for when the mod is being run from the local/dev folder, and also hosts "staticID".)

ONI Is Upgrading to Harmony 2.0! (9)


  • A number of methods in Harmony have changed signature or scope, so various compile errors will have to be resolved
  • As always, a number of changes have happened in the ONI code, so those errors will have to be resolved
  • Update your mod_info.yaml as described below for best compatibility. NOTE! If you're currently using a single version of your mod that runs on Vanilla and Expansion1, you will likely want to two versions of the mod for the duration of this Harmony 2.0 rollout.

Finally, upload the new version of your mod! Be sure to use the new tags to indicate its compatibility. ONI Is Upgrading to Harmony 2.0! (10)

So what's new in Harmony, anyways?

Here's the official Harmony update information.
Here's the full list of patch notes (Reminder, we're on, catching up from
The full Harmony 2.0 documentation.

In Conclusion

Please let me know if there are any gotchas or missing steps I should include in this post!

A huge thanks to everyone in this community! I know from personal experience how much work it is to keep modding a game that is in active development, but the champions here nonetheless have made a workshop full of amazing mods! It's always exciting to browse through and see what's new, and to get the chance to play visions of the game that are different than our own. How cool is it that these things can co-exist side-by-side? So again, THANK-YOU!

mod_info.yaml for supporting all versions of the game


It's good to be familiar with how mod_info.yaml and the archive folder work, but here's a configuration that should be good-to-go.

Though there are numerous ways to set up your archive folders to get the result you want, this one should work for simple cases.

If you currently have two versions of your mod

MyOniMod/|- mod_info.yaml| > supportedContent: VANILLA_ID,EXPANSION1_ID| > minimumSupportedBuild: 467401|- (normal mod contents)|- archived_versions/ |- vanilla_pre_mergedown/ | |- mod_info.yaml | | > supportedContent: VANILLA_ID | | > minimumSupportedBuild: 466654 | |- (normal mod contents) |- expansion1_pre_mergedown/ |- mod_info.yaml | > supportedContent: EXPANSION1_ID | > minimumSupportedBuild: 466654 |- (normal mod contents)

If you currently have one version of your mod

MyOniMod/|- mod_info.yaml| > supportedContent: VANILLA_ID,EXPANSION1_ID| > lastWorkingVersion: 466655|- (normal mod contents)|- archived_versions/ |- pre_mergedown/ |- mod_info.yaml | > supportedContent: VANILLA_ID,EXPANSION1_ID | > lastWorkingVersion: 466654 |- (normal mod contents)

If you are having trouble with a specific case, please ask in this thread.

ONI Is Upgrading to Harmony 2.0! (2024)


Top Articles
Latest Posts
Article information

Author: Fredrick Kertzmann

Last Updated:

Views: 6238

Rating: 4.6 / 5 (46 voted)

Reviews: 93% of readers found this page helpful

Author information

Name: Fredrick Kertzmann

Birthday: 2000-04-29

Address: Apt. 203 613 Huels Gateway, Ralphtown, LA 40204

Phone: +2135150832870

Job: Regional Design Producer

Hobby: Nordic skating, Lacemaking, Mountain biking, Rowing, Gardening, Water sports, role-playing games

Introduction: My name is Fredrick Kertzmann, I am a gleaming, encouraging, inexpensive, thankful, tender, quaint, precious person who loves writing and wants to share my knowledge and understanding with you.