Modding:C Sharp Scripting

This page is about modding. See the modding overview for an abstract on modding.

This page is about modding. See the modding overview for an abstract on modding.

Overview

Caves of Qud loads a majority of its content via reflection. You may add new files to its database of reflectable objects by including .cs files in your mod. These files are compiled at runtime into an assembly and the type resolver will first check for types in the mod assembly before checking the Caves of Qud game assembly, thus you may add new types or override existing types by including classes with the right naming convention in your mod.

Since your mod runs with full privileges, users must approve mods each time they change, to allow any changes in code to be screened before they execute. This approval mechanism is currently only available via the overlay UI so it either must be enabled or mod approval must be disabled for scripting mods to work properly. If your mod scripts are not approved, no files in your mod will be loaded, to prevent definitions from not having the appropriate classes available in the mod's assembly.

Nosing Around

There's no official DLL to assemble against or open source project but if you want to dig around in the source code you can use ILSpy, dotPeek, or one of various other decompilation tools on Caves of Qud\CoQ_Data\Managed\Assembly-CSharp.dll

The XRL.World.Parts namespace contains all the part definitions in the game, so it's a good place to start digging.

Cross-Platform (Including Linux)

MonoDevelop, which is cross-platform (and in particular runs on Linux), comes with its own disassembly tool.

1. Run MonoDevelop.
2. Go to File→Open….
3. Locate the abovementioned assembly file and open it. This will open the Assembly Browser.
4. In the dropdown next to where it says "Language", select "C#".
5. Now you can start digging in the disassembled C# source code by selecting some of the game's classes from the sidebar.

Working on Mac

Sometimes, Monodevelop/Visual Studio do not render the assembly properly when you munge in the raw DLL.

To get around this, use ILSpy to decompile the code:

1. Install Visual Studio: http://visualstudio.microsoft.com/vs/mac/
   • Make sure you have the [.net Core SDK](https://download.visualstudio.microsoft.com/download/pr/19f39d7d-3296-4ed2-af75-f0190d074d43/84949e2b33ccdc6b7c51d5835df2844e/dotnet-sdk-2.2.301-osx-gs-x64.pkg)
2. Open up a terminal and install ilspycmd: dotnet tool install ilspycmd -g
3. Find the directory Caves of Qud is installed in - for Steam this is "$HOME/Library/Application Support/Steam/steamapps/common/Caves of Qud/CoQ.app"
4. Using the full path of the Assembly file, run the following in a terminal:
   • ilspycmd -p -o ~/Qud_Code "$HOME/Library/Application Support/Steam/steamapps/common/Caves of Qud/CoQ.app/Contents/Resources/Data/Managed/Assembly-CSharp.dll"
   • You can replace '~/Qud_Code' with any other directory, if you have a certain place you want to put it
5. Open Visual Studio, then open the csproj file a ~/Qud_Code/Assembly-CSharp.csproj

Modding Using Visual Studio

Follow these steps in order to get Visual Studio to correctly parse and include the decompiled code while you are writing your mod code (there are other methods, but this is the one I used):

1. Using ILSpy, decompile Assembly-CSharp.dll as described above.
2. Right click on the "Assembly-CSharp" folder in the sidebar and select "Save Code", and then save it as a Visual Studio Project wherever you want, ideally outside of your mod code or the base game files, as otherwise things could get confused quick.
3. In Visual Studio, create a new project from existing code, and select the folder that contains your mod.
4. Once that project is open, go to File > Add > Existing Project and select the Visual Studio Project you saved your disassembled code as. You should now have both the disassembled code and your mod folder open as projects in a single solution.
5. Go to Project > Project Dependencies and add the decompiled code project as a dependency of your mod project
6. Right click on your mod project in the Solution Explorer, and select Add > Reference, and then go to "Projects" in the sidebar and select the disassembled code, before clicking "OK"
7. Congrats, Visual Studio should now correctly parse your mod scripts against the existing game scripts.

Detailed Scripting Topics

• Adding Code to the Player
• Creating new mutations
• Adding active abilities