javisar/ONI-Modloader

A modloader for Oxygen Not Included

ONI-Modloader

A simple mod loader for Oxygen Not Included based in Harmony

Forums in Klei

Disclaimers

• Please DON'T REPORT BUGS you encounter to Klei while mods are active.
• BE AWARE that many of the mods are still a WIP and may fail. If you are having problems use a clean ONI installation and try to test the mods one by one to narrow the error. Then post a issue in github.
• We DO NOT take any responsibility for broken saves or any other damage. Use this software at your own risk.
• If you load a savegame, it probably requires that you have exactly the same mods when you saved it.

This project uses source code of and is based on: Harmony, ModLoader Installer, Besiege Modloader, OnionPatcher

NOTE: Tested on LU-361684

Report Bugs for ONI-Modloader here: https://github.com/javisar/ONI-Modloader/issues

Mods based in Harmony

• Javisar's Mods Forum
• Cairath's Mods Forum
• Rainbow's Designs Mods Forum
• MidnightSteam's Mods
• MooreDavid's Mods Forum
• Sijko's Mods Forum
• Blindfold's Mods
• EtiamNullam's Mods Forum
• AntiBlueQuirk's Mods Forum
• lfricken's Mods Forum Find more in the Steam Workshop

For Mod Request to the Community post them in Klei Forums For ONI-Modloader feature request post them in ModLoader GitHub.

Quick Start

ONI-Modloader

1. Download the Latest Version
2. Copy ModLoader.dll to ONI Managed folder:
   • Windows: \OxygenNotIncluded\OxygenNotIncluded_Data\Managed\
   • Mac: /OxygenNotIncluded/OxygenNotIncluded.app/Contents/Resources/Data/Managed/
3. Move your mods to the Mods folder:
   • Windows: \OxygenNotIncluded\Mods\
   • Mac: /OxygenNotIncluded/OxygenNotIncluded.app/Contents/Resources/Mods/
4. Start your game and check for logs in output_log.txt or Player.log.

ONI builtin Modloader (Steam)

1. If you want to use instead the ONI builtin modloader (used for Steam), you have to remove 'ModLoader.dll' from 'Managed' folder. If ONI detects a modloader, it bypasses Steam mods.
2. Move your mods to the Mods folder. Be sure that you put each mod in its own folder:
   • Windows: %USERPROFILE%\Documents\Klei\OxygenNotIncluded\mods\dev\
   • Mac: ???
3. Start your game and check for logs in output_log.txt or Player.log.

How it works

• The MODLOADER loads C# Harmony Patcher and also all Harmony Based mods in /Mods/ path.

Installation

ONI-Modloader 0. Prerequisites:

• Make SURE you're using the latest version from Github main branch.
• Make SURE you're using a fresh install of ONI. Check Verify Integrity Files function in Steam in the ONI game Properties>LocalFiles tab.
• Make sure you deleted all previous modloader file in:
  • Windows: \OxygenNotIncluded\OxygenNotIncluded_Data\Managed\
  • Mac: /OxygenNotIncluded/OxygenNotIncluded.app/Contents/Resources/Data/Managed/

1. Click "Clone or Download" and "Download ZIP" for the current version as the releases may not be up to date.
2. Copy the contents of the "Managed" folder to the folder:
   • Windows: \OxygenNotIncluded\OxygenNotIncluded_Data\Managed\
   • Mac: /OxygenNotIncluded/OxygenNotIncluded.app/Contents/Resources/Data/Managed/
3. Create "Mods" folder in the ONI main directory.
   • Windows: \OxygenNotIncluded\Mods\
   • Mac: /OxygenNotIncluded/OxygenNotIncluded.app/Contents/Resources/Mods/
4. Check for error logs in:
   • \OxygenNotIncluded\OxygenNotIncluded_Data\Managed\Mod_Log.txt

Uninstallation

Remove ModLoader.dll from \OxygenNotIncluded\OxygenNotIncluded_Data\Managed\ folder.

Mods Installation

Requirements

• .NET Framework v3.5
• Harmony Patcher v1.2.0.1
• Visual Studio 2015

Creating a Mod

0. Feel free to mess with any of the mods from https://github.com/javisar/ONI-Modloader-Mods
1. 'Clone or download' the project from the mod repo.
2. Copy the following files from ONI Managed folder '\OxygenNotIncluded\OxygenNotIncluded_Data\Managed' to the mod solution folder '\Source\lib'
   • UnityEngine.dll
   • UnityEngine.CoreModule.dll
   • Any needed unity UnityEngine.*.dll
   • Any needed ONI Assembly-CSharp-*.dll
3. Open the solution with Visual Studio.
4. Create a new class project.
   • To create a Project from scratch the right one is: Visual C#-Class Library (.NET Framework).
   • If you don't find it like when you have installed Visual Studio with Unity you need to tools-add tools or features and install: .NET Desktop Development.
   • It's available a Visual Studio Project Template
     • Copy the .zip file to ~\Documents\Visual Studio 2019\Templates\ProjectTemplates\Visual C# to access the template in VS
5. Add the previous libs as references of the project.
6. Compile it to generate the mod dll file.
7. Test your mod. Move you mod folder to: a. ONI-Modloader * Windows: %PROGRAMFILES(X86)%\Steam\steamapps\common\OxygenNotIncluded\Mods
   * Mac: /OxygenNotIncluded/OxygenNotIncluded.app/Contents/Resources/Mods/ b. ONI Builtin Modloader (Steam) * Windows: %USERPROFILE%\Documents\Klei\OxygenNotIncluded\mods\local
   * Mac: ???
8. Check the tutorials at the end of the page.
   • Harmony is a code injector which will help you to inject your .dll with the help of the modloader.
9. If you want to go into the ONI code you need to peek with a decompiler like JetBrains dotPeek or ILSpy.
10. If you need more help please ask at The Discord Server in the Modding Channel

Note: Dlls will be recognized by the mod loader if they reside in the main mod directory and subfolders.

How to debug mods

SIMPLE (recommended) The easier way to debug a mod is to use the Unity debug logs:

• Include in your VS project references the library from ONI managed folder: UnityEngine.CoreModule
• Insert in your code log dump lines like: Debug.Log("...");
• Check for the logs in output_log.txt or Player.log

ADVANCED

• Check in output_log.txt the Unity version used by ONI. Look for it in the first lines: Example: Initialize engine version: 2018.2.7f1
• Download from here the corresponding "mono.dll" file. This is mono modified to enable debugging.
• Replace mono.dll in ONI folder: \OxygenNotIncluded\Mono\EmbedRuntime\
• Visual Studio
  1. Install Unity for Visual Studio
  2. Configure your VS project to output Debugging Info. You must generate .pdb file with complete info.
  3. Compile your project
  4. Execute "lib\pdb2mdb.exe name.dll". This will generate in the same folder a .mdb file. "pdb2mdb.exe" for VS can be found here
  5. Exe, pdb and mdb files must be in Mods ONI folder.
     • If you use the Project Template, steps 4 and 5 will execute as a script automatically after the mod is rebuilt
  6. Run Oxygen Not Included.
  7. In VS, select option "Attach to Unity Debugger" and enter the IP: 127.0.0.1:55555
  8. Now your VS must be connected to the Game and stop in your breakpoints.
• dnSpy
  1. Follow this guide

Tutorials

• https://github.com/pardeike/Harmony/wiki/
• https://github.com/roxxploxx/RimWorldModGuide/wiki/SHORTTUTORIAL:-Harmony
• https://github.com/UnlimitedHugs/RimworldHugsLib/wiki/Introduction-to-Patching
• https://github.com/UnlimitedHugs/RimworldHugsLib/wiki/Detouring
• https://oxygennotincluded.gamepedia.com/Guide/Working_with_the_Game_Files
• https://github.com/Mpstark/ModTek/wiki/Writing-ModTek-DLL-mods
• Transpiler Tutorial
• https://github.com/blushiemagic/tModLoader/wiki/Another-Simple-Harmony-Transpiler-Tutorial
• Harmony Transpiler Help
• https://rimworldwiki.com/wiki/Modding_Tutorials/Decompiling_source_code

Downloads

Choose 'Clone or Download'.