Modding:C Sharp Scripting

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/
  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 at ~/Qud_Code/Assembly-CSharp.csproj

Mod Development Setups

This article may need cleanup to meet quality standards.
Please help improve this page by editing it.

Reason: " These instructions were found to contain errors and need to be revised for further errors."

Modding Using Visual Studio Code (Quick Setup)

Follow these steps in order to get Visual Studio Code to correctly parse and include the base game methods in Intellisense and similar tools (assuming you have the C# VSCode Extension):

  1. On the Caves of Qud main menu, with Mouse Overlay UI toggled on, go to "Modding Utilities" and select "Write Mods.csproj File". This will automatically create an XML file describing the setup needed that VSCode can read.
  2. Find the Mods.csproj file in your CoQ save data folder. On Windows, this is located in %UserProfile%\AppData\LocalLow\Freehold Games\CavesOfQud.
  3. Move it to your main modding directory you intend to work from. It is not recommended that this be a mod folder itself, as that will include both this csproj file and additional VSCode-generated files in the mod itself - it is a better idea to keep mods in their own folders and place the Mods.csproj and other exterior files into a parent folder. If you want to keep your Mods folder tidy, you can create your individual Mod folder elsewhere and then create a hardlink/junction to that folder inside of the Mods folder.
  4. Open VSCode in the folder that contains the Mods.csproj, you should now be able to reference Qud namespaces, classes and methods from your own code. As this just links directly to the DLLs, however, you will only get metadata information about those classes and such, which tends to include function signatures, variable names and similar, but not the actual code within those functions. You can look at the actual code using a decompiler as mentioned above, or if you want your code to directly reference the decompiled code follow the optional step 5.
  5. (Optional) In order to reference the decompiled code rather than the real DLLs, take save the decompiled code into a folder in the same directory as your mods then, to prevent conflicts, delete the "Assembly-CSharp.dll" line from your Mods.csproj. You will have to repeat this step each time the game updates if you want to be working with the most recent code, whereas the DLL links should stay updated. This is similar to the first two steps in the following section.

Note: I sometimes have issues with VSCode or Visual Studio attempting to pull in additional dependencies, which often leads to errors and are not necessary for Qud modding. I do not recommend clicking the "Resolve Dependencies" button if it appears, and if it does you may have to delete the generated ".vs" and "bin" folders in order to get it to work properly again.


Modding Using Visual Studio (Manual Setup)

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.

You may also want to add a reference to UnityEngine.CoreModule.dll in CoQ_Data/Managed if you want to have Visual Studio correctly include Unity code, and the same goes for any of the other dll's used by Qud, though I have found that just including UnityEngine.CoreModule.dll has been enough for all of my purposes.

Debugging

Logging can be done either by outputting text to the in-game player console like this:

XRL.Messages.MessageQueue.AddPlayerMessage("Hello, Im a message!")

Or can be output to the player.log file like this:

UnityEngine.Debug.LogError()

Or by using other standard UnityEngine.Debug methods, as detailed here[1]. Various options for ingame error popups and such can be found in the Debug section of the ingame options.

Errors that occur during the initial build of the game, when all the dependencies such as mods are pulled in are included in build-log.txt which can be useful to look at if there is no useful information in the player.log.

Detailed Scripting Topics