[Tutorial] How to create a basic mod for ONI

[chromiumboy]

Hi everyone!

This tutorial is intended to give you a basic overview of how to create a new mod for ONI, get it running, and then upload it to the Steam Workshop. Please note that this tutorial does NOT cover any coding! That's all up to you. If you run into trouble with your mod code, either make a post on this subforum, or pop into the modding channel on the ONI Discord

For this tutorial I will be using MS Visual Studio 2017 under Windows 10. Sorry Mac and Linux users! The process will be much the same, but you will probably need to use a different IDE

Step 1: Start up Visual Studio and create a new project

 

Step 2: From the menu that opens, select '.NET Framework 3.5' from the drop down menu, and then 'Class Library (.NET Framework)' from the list of options. Double check that your under '.NET Framework 3.5'! This is the version that ONI uses. Choose a name for your mod folder and a location to save this folder. If you don't see 'Class Library (.NET Framework)' listed as an option, go to Step 3. Otherwise go to Step 4

 

Step 3: If 'Class Library (.NET Framework)' was not listed as an option in the previous step, click on 'Open Visual Studio Installer' instead. On the new menu that opens, select '.NET desktop development' and then 'Modify'. Once the necessary files are installed (it's quite large from memory), go back to Step 2

 

Step 4: Now go over to the 'Solution Explorer' on the right side of the work space. Right click on 'References' and 'Add Reference'

Here you can add the .dll file references that you will need for coding your mod. '0Harmony.dll', 'UnityEngine.dll', 'UnityEngine.CoreModule.dll', 'Assembly-CSharp-firstpass.dll' and 'Assembly-CSharp.dll' will cover most peoples needs (you can peek into these .dll files to see their code using a program such as dnSpy). You can find these .dll files under '\steamapps\common\OxygenNotIncluded\OxygenNotIncluded_Data\Managed'

I've copied these .dll files into a new folder to keep them with the rest of my mod development files

 

Step 6: Now you can finally write your code! This simple example just gets the ONI log file to write 'Hello World!'. ONI (like many Unity games) is modded by patching the code with Harmony. You can find more information on how to use Harmony here

 

Step 7: When your done coding, build the solution. If the build was successful, there should be no errors listed

 

Step 8: The output of the solution build will be listed in your mod directory, under '\bin\Debug' by default. Copy and paste the mod .dll ('HelloWorld.dll' in this case) into a new folder under '\Klei\OxygenNotIncluded\mods\dev'

 

Step 10: Start Oxygen Not Included. Your mod should be listed at the bottom of the mod menu with the name of the folder that holds your mod .dll. Activate the mod!

 

Step 11: Check the ONI log file (stored under '\AppData\LocalLow\Klei\Oxygen Not Included') to make sure the mod was loaded successfully. In this case, no error messages are listed, and 'Hello World!' was printed into the log. Success!

 

Step 12: When your mod is ready to be uploaded to the Steam Workshop, download and install the ONI Uploader (found under 'Library/Tools' on Steam)

 

Step 13: Once the uploader is installed, open it up. Make sure that you have exited ONI and the process has ended first! If you mod .dll is still in use, and you try to upload it, the upload will fail. Click 'Add' to add your new mod, fill in the required details, and then publish!

Check your Workshop items, and you should find your mod listed there and ready for use. Hope someone finds this tutorial useful!

[Nightinggale]

6 hours ago, chromiumboy said:

Step 8: The output of the solution build will be listed in your mod directory, under '\bin\Debug' by default. Copy and paste the mod .dll ('HelloWorld.dll' in this case) into a new folder under '\Klei\OxygenNotIncluded\mods\dev'

I automated this step. In MSVC, I opened project properties and under build events, I entered:

mkdir "%HOMEPATH%\Documents\Klei\OxygenNotIncluded\mods\local\$(ProjectName)"
copy "$(TargetPath)" "%HOMEPATH%\Documents\Klei\OxygenNotIncluded\mods\local\$(ProjectName)"
IF EXIST  "$(TargetDir)*.json" ( copy "$(TargetDir)*.json" "%HOMEPATH%\Documents\Klei\OxygenNotIncluded\mods\local\$(ProjectName)" )
IF EXIST  "$(TargetDir)*.txt" ( copy "$(TargetDir)*.txt" "%HOMEPATH%\Documents\Klei\OxygenNotIncluded\mods\local\$(ProjectName)" )

It will create the mod dir, copy the DLL file and any .json and .txt files found next to the dll file. The latter part is for config files and txt guides for config files.

Note that I installed in mods\local while the guide mentions mods\dev. Both should work, though Klei said that there are differences, though they haven't said what those differences are.

Also I highly recommend using git to keep track of your source code. It makes life a whole lot easier if something breaks and it used to work because you can both revert and you can use the log to see what you changed when it broke. I have seen people thinking it's too complex to set up and then waste days trying to recover something, which could be solved in minutes if they had used git.

[bambalad]

Great tutorial but I have an issue with step 11.

Initialize engine version: 2018.2.20f1 (cef3e6c0c622)
GfxDevice: creating device client; threaded=1
Direct3D:
    Version:  Direct3D 11.0 [level 11.0]
    Renderer: NVIDIA GeForce GTX 960 (ID=0x1401)
    Vendor:   
    VRAM:     1944 MB
    Driver:   26.21.14.3064
Begin MonoManager ReloadAssembly
- Completed reload, in  0.113 seconds
<RI> Initializing input.

<RI> Input initialized.

<RI> Initialized touch support.

UnloadTime: 0.426320 ms
[00:01:21.245] [1] [INFO] Starting up with a resolution of 1920x1080 @60hz (fullscreen: True)
[00:01:21.313] [1] [INFO] Found player prefs resolution 1920x1080 @60hz (fullscreen: True)
[00:01:21.313] [1] [INFO] Applying resolution 1920x1080 @60hz (fullscreen: True)
[00:01:21.338] [1] [INFO] Development Build: Q3-336724
SYSTEM INFO:
    Platform=WindowsPlayer
    OSname=Windows 7  (6.1.0) 64bit
    OSversion=6.1.7601.0
    CPUmodel=MS-7922 (MSI)
    CPUdeviceType=Desktop
    CPUarch=AMD64
    ProcBits=64
    CPUcount=4
    CPUtype=Intel(R) Core(TM) i5-4460 CPU @ 3.20GHz
    SystemMemoryMegs=16335
    GPUgraphicsDeviceID=5121
    GPUname=NVIDIA GeForce GTX 960
    GPUgraphicsDeviceType=Direct3D11
    GPUgraphicsDeviceVendor=NVIDIA
    GPUgraphicsDeviceVendorID=4318
    GPUgraphicsDeviceVersion=Direct3D 11.0 [level 11.0]
    GPUmemoryMegs=1944
    GPUgraphicsMultiThreaded=False
    GPUgraphicsShaderLevel=50
    GPUmaxTextureSize=16384
    GPUnpotSupport=Full
    GPUsupportedRenderTargetCount=8
    GPUsupports2DArrayTextures=True
    GPUsupports3DTextures=True
    GPUsupportsComputeShaders=True
    GPUsupportsImageEffects=True
    GPUsupportsInstancing=True
    GPUsupportsRenderToCubemap=True
    GPUsupportsShadows=True
    GPUsupportsSparseTextures=False
    System Language=English
[00:01:21.722] [1] [INFO] Initializing at 2019-06-25 00:01:21.722
[00:01:21.723] [1] [INFO] Save path: C:\Users\Bumbaclad\Documents\Klei\OxygenNotIncluded
[00:01:21.731] [1] [INFO] Load mod database
[00:01:21.807] [1] [INFO] ModLoader.dll failed to load. Either it is not present or it encountered an error
[00:01:21.808] [1] [INFO] Load mods:
[00:01:21.808] [1] [INFO] Using built-in mod system...looking for DLL mods in C:\Users\Bumbaclad\Documents\Klei\OxygenNotIncluded\mods/
[00:01:21.809] [1] [INFO] Loading MOD dll: Hello World.dll
[00:01:21.853] [1] [INFO] Failed to load mod hello world...disabling

 

[chromiumboy]

@Nightinggale Thanks for that! That automation looks handy

@bumbaclad Not entirely sure why it failed to load (ONI error messages aren't very informative unfortunately). Try renaming your files so they do not contain spaces and double check that your code matches mine

[Nightinggale]

I found the difference between the local and the dev directories. A crashed mod will disable all mods, except if at least one mod in dev is active. This is an apparently undocumented feature on the forum (dev is better for mod creators is all the forum says), but if you crash the preview and read the log, it actually has a reference there, hence how I figured it out.

Use dev, not local if you create your own mods.

[Maebeknot]

This was way to flipping hard to find. Why is this not a sticky!

[miauly]

On Linux, the folder should be Dev, not dev, so: mods\Dev\SomeMod\SomeMod.dll .

[Nightinggale]

On 8/1/2019 at 9:45 PM, Maebeknot said:

This was way to flipping hard to find. Why is this not a sticky!

I think it has something to do with the fact that only Klei can sticky topics. Not only is it possible that nobody asked them, they announced in the Launch changelog that they will bring their own guide to the modding subforum.

However I say this should be stickied. If Klei releases something better later, then it can be unstickied later. There is no reason not to sticky the best thread on the topic at all times, even if "the best" might not always be the same.