Creating your first script mod¶
This tutorial will guide you through the process of creating your first script mod for Voxel Tycoon.
To get a common understanding of how script mods work and what is possible to be done with them, please refer .dll asset documentation page.
We assume that you have at least basic knowledge of development in C# and Unity.
After finishing this tutorial, you will know how to:
- Setup development environment
- Build super simple but working script mod that shows custom in-game notifications
Resulting source code, with some additions, can be found here: https://github.com/voxeltycoon/mods.
Set up the environment¶
Script mods can be built with any tools that could compile your source code into the .NET DLL. This ranges from full-featured IDEs like Visual Studio, to manually calling the compiler on source files.
In this tutorial, we will use Visual Studio (Community 2019) for this purpose, as the most straightforward way to build a .NET DLL on Windows. It can be obtained for free from the official site.
Ensure that you have .NET Desktop development workload installed:
Besides Visual Studio, you'll need - obviously - a licensed copy of Voxel Tycoon to test and publish your mods.
Actually, this concludes all the preparations you need to start developing your first script mod. As you may notice, even Unity installation is not required.
Create a new project¶
After you launch Visual Studio, you'll see the welcome window. Hit Create new project there:
Then choose Class Library (.NET Standard) (make sure you choose C# one, not Visual Basic):
Name your project and choose where it should be placed (this is where your source code will be located, not the result DLL file, so DO NOT choose game's
Now, we need to add references to libraries that contain APIs we want to access. To do this, right-click on the project dependencies item in the Solution Explorer (1), then click on Add Reference... (2):
Reference Manager window will appear. Hit Browse on the left (1) then Browse at the bottom (2) and select
UnityEngine.CoreModule.dll libraries that can be found in
VoxelTycoon_Data/Managed directory inside the game folder (3):
The project for our mod is ready! Now it's time to make it do something.
Write some code¶
As a simple but working example let's make our mod to show a custom in-game notification when the game is loaded.
Inherit from the
Mod abstract class¶
To let the game know what code it should run from our script mod, we need to inherit from the
Mod class, situated at the
Mod class exposes several callbacks, but for our mod it's enough to override just
Access Notification Manager API¶
To show our notification in-game, we need to access Notification Manager. Besides other methods it exposes, the most we interested in currently is this one:
Let's call it from our mod's code:
There's a lot of managers present around the code of Voxel Tycoon. Most of the game API is accessable through them.
You can create your own managers by inheriting from
Run the mod¶
That's it! Our brilliant mod is almost ready to be put in the game.
Compile the mod into a DLL¶
Now we need to compile our source code to a DLL file that can be put into the game. To do this, select Build ➔ Build Solution in the Visual Studio top menu.
After the build process successfully finishes, you will find the result DLL at the
<project location>/bin/Debug/netstandard2.0/<project name>.dll directory.
Depending on chosen build configuration, the DLL may be built to
Release directory instead of
Run the game¶
As we now have a DLL, we can put it into the game. Just copy the DLL to your mod directory inside the game's
Content folder, just as you do with any other mod asset. Now you can run VT, and start the new game with your mod enabled.
Don't forget to put a
mod.json metadata file inside the mod pack folder which will allow the game to locate and load the mod.
To avoid manual copying the DLL file after every change, you can setup post-build event in the project settings.
Congratulations! You've just created such an amazing mod, just as you are! ✨
As a conclusion, take a look at some points that were left outside of the scope of this tutorial:
- One DLL can contain not just one code file, but any amount you need
- Explore other callbacks
Modclass provides, like
Initialize()(called before any assets loaded)
- Mods can read and write data to a save file using corresponding callbacks
- You can debug your code by writing logs or even attaching a debugger
- As stated at Where's API documentation?, feel free to explore the game code base for existent and possible APIs, and let us know what you think!
Happy coding! 💜