Creating your first script mod¶

Introduction¶

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

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 Content folder):

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 VoxelTycoon.dll and 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 VoxelTycoon.Modding namespace.

Mod class exposes several callbacks, but for our mod it's enough to override just OnGameStarted one:

1
2
3
4
5
6
7

    public class Class1 : Mod
    {
        protected override void OnGameStarted()
        {
            // That's where our mod logic goes.
        }
    }

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:

1
2
3
4
5
6

public Notification Push(NotificationPriority priority,
    Color color,
    string title,
    string message,
    INotificationAction action,
    FontIcon icon)

Let's call it from our mod's code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

protected override void OnGameStarted()
{
    // Maximum priority so we never miss it.
    var priority = NotificationPriority.Critical;

    // Make the notification look fancy by setting the color
    // to the current company color.
    var color = Company.Current.Color;

    var title = "Hello World!";
    var message = "Oh gosh, this is my first ever C# mod " +
    "for VT, and it's actually working for some reason!";

    // Action is executed when player clicks on notification.
    // For the sake of simplicity, we will not cover notification
    // actions in this tutorial, so we just pass default value (null),
    // which effectively means no action will be executed on click.
    var action = default(INotificationAction);

    // Use custom FontAwesome (https://fontawesome.com/icons) icon
    var icon = FontIcon.FaSolid("\uf7e4");

    // And finally, call the API
    NotificationManager.Current.Push(priority,
        color,
        title,
        message,
        action,
        icon);
}

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.1/<project name>.dll directory.

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.

Enjoy yourself¶

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 Mod class provides, like OnUpdate() or 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! 💜