ONI Is Upgrading to Harmony 2.0!

[Ipsquiggle]

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

 

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

 

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!

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.

 

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

 

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

 

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.

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

 

Additionally:

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

 

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 2.0.4.0, catching up from 1.2.0.1).
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

Spoiler

 

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.

 

[Cairath]

Better late than never on this one  Thanks! We've really wanted this for a long time

[gabberworld]

good bye old mods who not actively updated

[Peter Han]

Thank you for putting in the effort to update Harmony! I am curious about the timing of your "mergedown", however, will June 10th also feature code base changes to unify Vanilla and the Spaced Out! DLC?

[SharraShimada]

i guess i have to get into active modding myself... because i fear, there will be many (for me) essential mods that will not be updated ever after this change.

 

[babba]

35 minutes ago, SharraShimada said:

i guess i have to get into active modding myself... because i fear, there will be many (for me) essential mods that will not be updated ever after this change.

A multiplayer mod would be great, I can provide oxygen for 1000 player dupe visitors in 1 cycle in my big map - If every player sends 1 dupe and then leaves before the oxygen runs one, we should be ok. Everybody can lag as clients below 1 fps  Arrival is via rockets ( premium ) or drop pods ( saves space ) and everyone gets a pedestal pressi for their own colony to collect in babba`s base. Having such an working mp mod would be an achievement like playing Battlefield with a thousand. Even if someone works 3 years on it, it could be wortwhile, as long the big chat window for everyone gets updated in "real time" - That is the most important hihi

[Ipsquiggle]

To be clear, the timing looks like this:
 

June 10th -- next Spaced Out public testing -- Mergedown (and Harmony2.0) is available on Spaced Out Public Testing

June 24th -- next Spaced Out release -- Mergedown goes live to all Spaced Out players

... some weeks later -- Mergedown is available on Oxygen Not Included Public Testing

... some weeks later -- Mergedown is Live for all players.

 

[SharraShimada]

So, do i get this right? Public test for the DLC will get the update today and will break mods? (for safety reasons i unsubbed to test versions), and DLC will get in inevitably at june 24th?

[gabberworld]

1 hour ago, SharraShimada said:

So, do i get this right? Public test for the DLC will get the update today and will break mods?

it break the all mods yes when that happens, but you can already update because Harmony dll can be downloaded from they webpage 

there no big difference as far i remember expect the

• Change all using Harmony; to using HarmonyLib; in your code
• If you use OnLoad(HarmonyInstance harmony), change it to OnLoad(Harmony harmony)

 

[sakura_sk]

The first week will be interesting... 

[Duck986]

10 hours ago, Ipsquiggle said:

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

This is a bruh moment indeed.

[Cairath]

It shows you guys haven't been around for any previous major changes :P The world is not ending, if anything it'll be a good cutoff for old unsupported mods.

[pether]

17 minutes ago, Cairath said:

The world is not ending, if anything it'll be a good cutoff for old unsupported mods.

I don't think it will be cutoff for them. Judging by what was happening with mods without DLC support, old mods without Harmony 2.0 support will be claimed by random people and "fixed", often without mod or even C# understanding. If game code changed later causing mod to break, such people may lack skills to fix it properly and there will be even more mess in the workshop.

If mod is forgotten by the author and no longer supported it could be understood, but I'm pretty sure there will be attempts to claim mods done by authors who are still around but wait until things are stable and explicitly forbiding stealing their mods... @Ipsquiggle, do you have any power to remove stolen mods from steam when author of the original is still around but wasn't fast enough to update their mods? It would help to clean the inevitable mess and hopefully prevent such bad habbits in the future

About the change - I fear the mess it will bring, but I guess it is nessesary and I'm happy it happens when I am around and aware of changes to update my mods. Also, I am super excited about code merge, it will make life so much easier in the future! Great news, thanks!

[Cairath]

1 minute ago, pether said:

I don't think it will be cutoff for them. Judging by what was happening with mods without DLC support, old mods without Harmony 2.0 support will be claimed by random people and "fixed", often without mod or even C# understanding. If game code changed later causing mod to break, such people may lack skills to fix it properly and there will be even more mess in the workshop.

Unfortunately, this I agree with. In a perfect world people would see that the mod hasn't been updated after the change date and know not to use it. The stealing and reuploading mods and then modders being insulted when asking the original author to take that down... that needs to stop. I've been called many things and more often than not it made me want to pull all mods from the workshop.

[gabberworld]

thing is some mods dont need update that often, it allot depends how mod is made, but with that update now those mods will not work either  who not need active updates

[FreezingSlickT]

Im not a modder, but if the modders like this, than I like this.  Im all for better modding APIs for our creative individuals.

But I also agree with Pether, there will most likely be a lot of stolen mods follow these "events", because of modders being too busy.  These should most likely be stamped out once those mods have updated.

[crazy_xyr]

On 6/10/2021 at 5:55 AM, Ipsquiggle said:

lastWorkingVersion: 466655

lastWorkingBuild  has been changed to lastWorkingVersion ？

[Cairath]

5 hours ago, crazy_xyr said:

lastWorkingBuild  has been changed to lastWorkingVersion ？

It has not. Typo :P 

@Ipsquiggle, you might want to correct that in the first post

[Ipsquiggle]

Today's patch, r467601, changes the target framework of the 0Harmony.dll to 4.7.1. The top post has been updated. It's recommended you retarget your mod projects to that version.

I also fixed the mod_info typo, thank you!

[Brrainz]

Hello ONI community. I am happy that my Harmony library is now an official part of the product. We had the 1.x -> 2.x switch a while ago in the RimWorld community where I first created Harmony to make my first mod. The switch went fine and I am pretty sure it will be for you guys too.

I am still working on Harmony 2.1 but we have commited to making only API compatible changes to it and that will allow ONI to just upgrade to it without mods need to change.

Again,
congrats and keep it up!

Andreas "Brrainz" Pardeike

[Ipsquiggle]

Hello, today's patch contains a significant change to the mod API. The upgrade should be fairly simple, but mods will have to make it in order to continue loading. I'll make up a full post for it and update the top-post here in a day or two when it's solid, but please give it a review and let me know if you encounter any problems with it.

The new API works like this:

• There is a new class, KMod.UserMod2 which becomes the entry point to the mod. Make a new class that inherits from UserMod2 to access the entry point hooks and data.
• Any mod which doesn't have an implementation of UserMod2 will simply have harmony.PatchAll() called for each assembly.
• For any assembly which does have an implementation of UserMod2:
  • The mod system will instantiate an instance of that class.
  • It will fill in some properties, and then call a virtual OnLoad(Harmony harmony) method on that instance. (The base implementation simply calls PatchAll(). )
  • After all mods assemblies have been loaded/patched, the mod system will call virtual OnAllModsLoaded(Harmony harmony, IReadOnlyList<Mod> mods) on that instance. The base implementation of this function does nothing.

This process will require upgrading your mods (full instructions will come soon), but the simple version is:

• Do nothing if you want auto-patching
• Make a class that inherits from KMod.UserMod2 and override the virtual methods as you see fit.

The overall effect of this change is that modders can optionally handle the patching process entirely themselves, as well as perform actions reliably once all mods are loaded but while still in the mod loading part of the startup sequence. As well, this prevents spurious/magic "OnLoad" calls from being triggered. Additionally, this instance may be used to provide additional data to the mod in the future.

Please give it a peek once the update is live and leave your feedback in this thread. Thanks!

[Cairath]

Yay!

But.. what did the poor UserMod do to you that you already replaced it with UserMod2? :P

[pether]

15 hours ago, Ipsquiggle said:

Any mod which doesn't have an implementation of UserMod2 will simply have harmony.PatchAll() called for each assembly.

Do I understand correctly that if I don't make any changes to my mods (except from ofc updating them to use Harmony 2.0 and .Net 4.7.1 from the previous message), and I ignore UserMod2, my mods will work exactly the same as before this patch? I try to estimate how many issues I will encounter during my updates

@Cairath, never ask:

• a man his salary
• a woman her age
• Ipsquiggle what happened to UserMod1

[Cairath]

Well, I'd trade my age for the story about UserMod

 

Regarding your question @pether, if you didn't use any hooks like onload and just relied on the auto patch then skipping UserMod wont hurt you

[Ronivan]

So, the Harmony 2.0 will also be updated for the vanilla version? I mean, I know it will eventually, but I want to know if it will be updated right on next week.