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.

Caves of Qud is programmed in the C Sharp v9.0 language (commonly abbreviated to "C#" or "cs"). 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, meaning that adding new C# code is technically as simple as including .cs files somewhere in your mod directory.

C Sharp mods run with the full privileges of the base game. As such, they represent a security risk if any mod were to include malicious code. Whenever a C Sharp mod is changed, users are required to approve the mod to run before it can be loaded. The user will be prompted with a mod approval popup before creating or loading a save file. If the mod is not approved none of its files will be loaded, including files other than .cs files.

Obtaining the Source Code

There is not a public repository of Caves of Qud's source code. However, there are several third-party tools available for decompiling .dll files into equivalent .cs files. Due to the nature of decompilation the decompiled file will be somewhat different from the original: Names of variables, objects, and methods may be different and there will be no code comments.

ILSpy can be used to decompile the source code. Point it at Assembly-CSharp.dll, which can be found in the QudLibPath directory. From here the code can be browsed from within ILSpy, or you can save the decompiled code and open it with another program. Note that the decompiled code will normally have errors due to being removed from its intended context.

Setting Up a Development Environment

While in theory any plaintext editor can be used for C# programming, this setup guide will detail using Microsoft Visual Studio. Visual Studio natively supports the C# language and ships with the ILSpy .NET decompilation engine included. As such, there is no need to install any extra plugins or third-party tools to start programming with Visual Studio. Note that Microsoft Visual Studio is an entirely seperate program from Microsoft Visual Studio Code.

Visual Studio Setup Guide

1. Create a folder somewhere to act as your modding folder, and create a folder inside of that for your specific mod. This will serve as the working directory for the mod. It is not recommended that this be inside the Mods folder of the game, as this folder will also contain some auto-generated files from Visual Studio that are not necessary to include in your finished mod.
2. Launch Caves of Qud. In the settings menu, navigate to the "Modding" section and enable "Enable Mods (restart required.)", "Select enabled mods on new game.", and "Allow scripting mods. Scripting mods may contain malicious code!".
   
3. Close and re-open the game to allow mods to be enabled. In the bottom-right corner of the title screen, there will be two new options: "Installed Mod Configuration" and "Modding Utilities". Click "Modding Utilities", then select "Write Mods.cproj file". This will create a Mods.cproj file in your configuration files directory. .cproj files are C# project files that Visual Studio can load to configure your development environment.
4. Copy Mods.cproj into the folder that you created as a working directory for your mod, then open it in Visual Studio. Visual Studio will automatically create obj, bin, and .vs directories, which are metadata used by Visual Studio and can be ignored.
5. From here, you are fully set-up to start coding. However, you may want to make some edits to Mods.cproj. Changing its name will change the project name in Visual Studio, which may be helpful for distinguishing multiple projects. You can also edit the fields of the file in order to change your Author title, AssemblyName, or other fields.
   Due to Issue #9116, you may see approximately 50 warnings in the error list. This is because Mods.cproj erroneously contains references to files which do not actually exist in the public release of Caves of Qud. These warnings may safely be ignored, or the erroneous references can be deleted from the Mods.cproj file.
6. You can press F12 in order to navigate to the definition of a selected object, variable, or method. If the definition is in the source code, Visual Studio will automatically decompile and open the relevant file.

Debugging

Debug statements can be written directly to the message log using:

XRL.Messages.MessageQueue.AddPlayerMessage("Hello world!")

Messages can also be written to Player.log using:

UnityEngine.Debug.LogError("Hello world!")

Other UnityEngine.Debug methods are detailed here and can also be used to write to Player.log.

Errors that occur during the initial building-in of your mod files are logged in build-log.txt. These errors will usually cause a mod to be unable to build, which prevents it from being enabled by the player.