opus modding two.md

Now with 100% less recompiling! And 100% more downloading. Sorry.

Download the following:

• The two executables (Opus Patcher, Modded Opus), which you can get from the releases on their respective repos (on my GitHub profile). -The former runs on .NET Framework, which is required to patch with Opus Magnum's executable, and the latter runs on .NET Core, which has libraries I rely on.

• Mono.Cecil, available from NuGet (https://www.nuget.org/). If you're unfamiliar with NuGet and simply want to play, download the package using the link on the sidebar, rename it from a .nupkg to a .zip, extract it to a folder, and copy Mono.Cecil.dll from the net40 directory.

  • Mono.Cecil provides tools for patching an executable, used to extract strings from the game.

• Steamworks.NET.Standard.Windows.x86, Ionic.Zip.

  • These are dependencies for the game itself. Although the game holds onto its own reduced versions of these libraries, the recompiled version references the full, newest version of these. Get these from NuGet in exactly the same way (sorry!).
  • If you're on Mac or Linux... sorry. Try using the version appropriate for your platform, but if that doesn't work, feel free to fix it.
  • Steamworks.NET.Standard.Windows.x86 will probably just be Steamworks.NET.dll

• keys.txt, patch.diff, mappings.csv, contained in the Modded Opus repo on my GitHub profile.

  • These are used by the executables and are specific to Opus Magnum
  • keys.txt is used while extracting strings; patch.diff fixes the decompilation, and will eventually contain mod loading code. mappings.csv contains human-readable (and in certain cases, .NET readable) names for intermediary names.

• Install .NET Core Runtime for x86 (https://dotnet.microsoft.com/download/dotnet-core/current/runtime).

  • It's fine if you have the x64 version installed.
  • It's best to let it download to the default location ("C:/Program Files (x86)/dotnet/"). Don't worry if you install it to elsewhere, it'll just be sliiightly more annoying later.

Once you have these downloaded, you won't have to redownload them. Except the last three; key.txt needs one last miiinor change, while patch.diff and mappings.csv will be updated everytime the mod loader updates. I hope to bundle the dependancies into the executables in the future too.

Place the two executables in the same folder, and make sure Modded Opus is named "Modded Opus.exe".

Run Opus Patcher (which can be named anything), with the following command line arguments in this order:

• The path to your Lightning.exe (the game's executable). On Windows, this will probably be something along the lines of "C:\Program Files (x86)\Steam\steamapps\common\Opus Magnum\Lightning.exe".
• The path to your keys.txt.
• The path to your mappings.csv.
• The path to your patch.diff.

This will produce a couple of files. All you need to care about for running is:

• ModdedLightning.exe, ModdedLightning.runtimeconfig.json, runModded.bat. Copy these three files to your Opus Magnum folder, alongside the aforementioned Steamworks.NET.Standard and Ionic.Zip. While the file says its an executale, trying to just run it will crash because I did something wrong and stupid - instead, you have to run it with dotnet <path to ModdedLightning>, which happens to be what runModded.bat does if you installed it to the default directory. If you didn't, just update the path to dotnet.

And now you can play Opus Magnum with mods! And by that, I mean you can't do anything more than in vanilla (and a select few things are actually broken...). Instead, now I can work on mod loading, and hopefully other people can work on making mod installation less painful.

If you're interested in helping with mods, keep reading! Otherwise, shoo!

The other files produced are:

• decomp.cs: The decompiled, patched code.
• intermediary.txt: The mappings between the nonsense obfuscated names and intermediary names. The original code contains certain unobfuscated names, nearly all of which are left in because the game wouldn't run otherwise (e.g. overrides of C# library functions), and this file allows for finding them quickly. This will also come in handy if the game updates, hopefully making it possible to keep existing mappings on a game update.
• out.csv: A ~,~ mapping of string keys to strings, dumped by Opus Patcher and used in recompilation to avoid needing to preserve the string unmangling function (I couldn't get it to work ;~;) and help out in mapping.

The current process is annoying, puts everything into a single patch file, and will cause me major issues if/when the game updates. I really should change this, and if anyone could help with that, it would be incredibly convenient.