Custom Code

It is possible to load custom code into the game using the mod loader. The mod loader provides various APIs to make interacting with the game easier. This guides assumes a basic familiarity with C# development.

There are two ways of loading code into the game: By referencing an already compiled DLL file or by distributing the source code and letting the game compile the code.

Both ways have advantages and disadvantages: Letting the game compile the code (this is then called a "Script Assembly") means that the only thing required to write code is a basic plain text editor, although an editor with syntax highlighting is recommended (e.g. Notepad++, Visual Studio Code, or Atom), and it's a bit easier to set up.

Compiling the code manually before passing it to the game requires more setup and larger/more complicated tools (usually Visual Studio, although there are other options, like MonoDevelop). There are significant benefits though, especially for larger projects. Most noticeably, a good autocompletion engine as well as immediate syntax and other error checking is invaluable for quickly writing a lot of code.

Setup

No matter which way of writing code you want to use, the assembly can be set up using the createassembly command.

When using compiled assemblies, it is recommended, but not required, to install the Visual Studio Tools for Unity using the Visual Studio installer. If you don't, pass the noUnityTools argument to createassembly (or ignore the warning it prints).

Especially when using a full IDE and compiled code reading the Project Layout section is also important.

Note: Always add all assemblies to the Assemblies element, even if they don't contain a ModEntryPoint. Is is only possible to call various mod loader APIs from assemblies listed in the mod manifest.

Executing Code on Startup

If the code is only intended to add blocks behaviour to blocks, this may not be needed. For most mods, it will be required to execute some code whenever the mod is loaded.

This is done by creating a a class that inherits from Modding.ModEntryPoint and overrides the OnLoad method.

Security

There are some restrictions on the available .NET framework classes and methods that are allowed. These are enforced by the mod loader when loading the assembly. This mostly concerns IO methods, as mods are not allowed to access files outside of their mod directory to protect players. Use the ModIO class for file IO inside the mod directory.

What is blacklisted:

  • System.IO, System.Net, System.Xml, except for classes that cannot be constructed with arbitrary paths (Stream, {Binary, Text}{Writer, Reader}, MemoryStream) or otherwise used to actually do IO (System.IO.Path, System.IO.SeekOrigin).
  • System.Reflection, System.Runtime.InteropServices
  • System.Diagnostics, System.Security, except for Stopwatch and Cryptography
  • Mono.CSharp, Mono.Cecil, Mono.CompilerServices
  • System.CodeDom.Compiler, CSharpCompiler, IKVM
  • UnityEngine.WWW, InternalModding

The IO related classes and namespaces are replaced by the ModIO class and the resources system.

The other namespaces should not be needed by mods. Reflection can occasionally be useful for mods but cannot be allowed because it could be used to circumvent all other restrictions.

APIs

There are various APIs provided by the mod loader to interact with the game. These are all contained in the Modding namespace.

It is also permissible to use internal game classes contained in other namespaces (or the global namespace). These are relatively nice to work with sometimes, but can also be rather obscure.

One exception is the InternalModding namespace which cannot be accessed by mods.

Only APIs in the Modding namespace are considered stable. Everything else may change without notice when the game updates, so try doing things with the Modding namespace as far as possible, but it's okay to access other classes when needed.

Important APIs

  • The Events class provides C# events for various things that may happen in the game.
  • The ModNetworking class provides an API to send messages across the network in multiplayer sessions.
  • The Modding.Common, Modding.Blocks and Modding.Entities namespaces provide representation of many in-game objects like Blocks, Entities and Players.
  • The Configuration class provides a way to store and access persistent data.
  • The ModIO class provides file-access methods.
  • The ModKeys class provides an API for keybindings that the user can rebind.

Some other APIs are described in the API document. Others are closely related to specific features of the mod loader and explained in the documentation for these features.

For concrete documentation explaining these classes and their methods, see the API documentation.