Modding:C Sharp Scripting: Difference between revisions

(25 intermediate revisions by 14 users not shown)

Line 1:

[[Category:Modding]]

[[Category:Modding]][[Category:Modding Resources]]{{Modding Info}}

~~==Overview==~~

Caves of Qud loads a majority of it's content via reflection. You may add new files to it's 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.~~

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 <code>.cs</code> files somewhere in your mod directory.

~~==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 https://www.jetbrains.com/decompiler/ or some other tool: http://stackoverflow.com/questions/2646707/something-better-than-net-reflector on~~ <u>~~Caves of Qud\CoQ_Data\Managed\Assembly-CSharp~~.~~dll~~</u>

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

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 <code>.cs</code> files.

==~~=Cross-Platform (Including Linux)=~~==

==Obtaining the Source Code==

~~[https:~~//~~www~~.~~monodevelop.com/ MonoDevelop]~~, ~~which is cross-platform (~~and ~~in particular runs on Linux), comes with its own disassembly tool~~.

There is not a public repository of Caves of Qud's source code. However, there are several third-party tools available for decompiling <code>.dll</code> files into equivalent <code>.cs</code> 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.

~~# Run MonoDevelop~~.

[https://github.com/icsharpcode/ILSpy/releases ILSpy] can be used to decompile the source code. Point it at <code>Assembly-CSharp.dll</code>, which can be found in the [[File_locations | 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.

~~# Go~~ to ~~File→Open…~~.

~~# Locate the abovementioned assembly file and open~~ it. ~~This will open~~ the ~~Assembly Browser~~.

~~# In~~ the ~~dropdown next to where it says "Language"~~, ~~select "C#".~~

~~# Now~~ you can ~~start digging in~~ the ~~disassembled C# source~~ code ~~by selecting some of~~ the ~~game's classes~~ from ~~the sidebar~~.

==~~Detailed Scripting Topics~~==

==Setting Up a Development Environment==

* [[Modding: ~~Creating New Mutations~~|~~Creating~~ new ~~mutations~~]]

* [[~~Modding~~: ~~Activated Abilities|Adding active abilities]~~]

While in theory any plaintext editor can be used for C# programming, this setup guide will detail using [https://visualstudio.microsoft.com/ Microsoft Visual Studio]. Visual Studio natively supports the C# language and ships with the [https://github.com/icsharpcode/ILSpy 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===

# 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.

# 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!". <br>[[File:CoQ_cs_ModdingSettings.png|1024px]]

# 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.csproj file". This will create a <code>Mods.csproj</code> file in your [[File_locations | configuration files directory]]. <code>.csproj</code> files are C# project files that Visual Studio can load to configure your development environment.

# Copy <code>Mods.csproj</code> into the folder that you created as a working directory for your mod, then open it in Visual Studio. Visual Studio will automatically create <code>obj</code>, <code>bin</code>, and <code>.vs</code> directories, which are metadata used by Visual Studio and can be ignored.

# From here, you are fully set-up to start coding. However, you may want to make some edits to <code>Mods.csproj</code>. 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. <br>Due to [https://bitbucket.org/bbucklew/cavesofqud-public-issue-tracker/issues/9116 Issue #9116], you may see approximately 50 warnings in the error list. This is because <code>Mods.csproj</code> 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 <code>Mods.csproj</code> file.

# 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!")

</syntaxhighlight>

Messages can also be written to <code>Player.log</code> using:

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

</syntaxhighlight>

Other <code>UnityEngine.Debug</code> methods are detailed [https://docs.unity3d.com/ScriptReference/Debug.html here] and can also be used to write to <code>Player.log</code>.

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

@@ Line 1: / Line 1: @@
-[[Category:Modding]]
+[[Category:Modding]][[Category:Modding Resources]]{{Modding Info}}
-==Overview==
-Caves of Qud loads a majority of it's content via reflection. You may add new files to it's 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.
+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 <code>.cs</code> files somewhere in your mod directory.
-==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 https://www.jetbrains.com/decompiler/ or some other tool: http://stackoverflow.com/questions/2646707/something-better-than-net-reflector on <u>Caves of Qud\CoQ_Data\Managed\Assembly-CSharp.dll</u>
-The XRL.World.Parts namespace contains all the part definitions in the game, so it's a good place to start digging.
+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 <code>.cs</code> files.
-===Cross-Platform (Including Linux)===
+==Obtaining the Source Code==
-[https://www.monodevelop.com/ MonoDevelop], which is cross-platform (and in particular runs on Linux), comes with its own disassembly tool.
+There is not a public repository of Caves of Qud's source code. However, there are several third-party tools available for decompiling <code>.dll</code> files into equivalent <code>.cs</code> 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.
-# Run MonoDevelop.
+[https://github.com/icsharpcode/ILSpy/releases ILSpy] can be used to decompile the source code. Point it at <code>Assembly-CSharp.dll</code>, which can be found in the [[File_locations | 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.
-# Go to File→Open….
-# Locate the abovementioned assembly file and open it. This will open the Assembly Browser.
-# In the dropdown next to where it says "Language", select "C#".
-# Now you can start digging in the disassembled C# source code by selecting some of the game's classes from the sidebar.
-==Detailed Scripting Topics==
+==Setting Up a Development Environment==
-* [[Modding: Creating New Mutations|Creating new mutations]]
-* [[Modding: Activated Abilities|Adding active abilities]]
+While in theory any plaintext editor can be used for C# programming, this setup guide will detail using [https://visualstudio.microsoft.com/ Microsoft Visual Studio]. Visual Studio natively supports the C# language and ships with the [https://github.com/icsharpcode/ILSpy 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===
+# 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.
+# 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!". <br>[[File:CoQ_cs_ModdingSettings.png|1024px]]
+# 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.csproj file". This will create a <code>Mods.csproj</code> file in your [[File_locations | configuration files directory]]. <code>.csproj</code> files are C# project files that Visual Studio can load to configure your development environment.
+# Copy <code>Mods.csproj</code> into the folder that you created as a working directory for your mod, then open it in Visual Studio. Visual Studio will automatically create <code>obj</code>, <code>bin</code>, and <code>.vs</code> directories, which are metadata used by Visual Studio and can be ignored.
+# From here, you are fully set-up to start coding. However, you may want to make some edits to <code>Mods.csproj</code>. 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. <br>Due to [https://bitbucket.org/bbucklew/cavesofqud-public-issue-tracker/issues/9116 Issue #9116], you may see approximately 50 warnings in the error list. This is because <code>Mods.csproj</code> 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 <code>Mods.csproj</code> file.
+# 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:
+<syntaxhighlight lang="c#">
+XRL.Messages.MessageQueue.AddPlayerMessage("Hello world!")
+</syntaxhighlight>
+Messages can also be written to <code>Player.log</code> using:
+<syntaxhighlight lang="c#">
+UnityEngine.Debug.LogError("Hello world!")
+</syntaxhighlight>
+Other <code>UnityEngine.Debug</code> methods are detailed [https://docs.unity3d.com/ScriptReference/Debug.html here] and can also be used to write to <code>Player.log</code>.
+Errors that occur during the initial building-in of your mod files are logged in <code>build-log.txt</code>. These errors will usually cause a mod to be unable to build, which prevents it from being enabled by the player.
+{{Modding Navbox}}