Modding:Code Tutorial Simple Block

This page is in progress! Come back soon!

Introduction

Objective

In this tutorial, you will be introduced to code modding by creating a block with custom functionality. You will create the assets for this project, find out how block classes are registered, and use a number of different functions. The block you will be creating is a trampoline, where as an entity collides with it, they will bounce.

Prerequisites

It is recommended to use the same project for all newer code tutorials, with the project name "VSTutorial". If you have not yet done this, please follow the following tutorials:

1. Preparing For Code Mods
2. Creating A Code Mod

This tutorial also assumes that you have read:

• Code Tutorial Essentials

Assets

Before you get started with any coding, it is important that you create the assets for your new trampoline block.

In Visual Studio, your mod's assets are easy to access from the solution explorer. Right click on the folder called assets, and then select Open Folder in File Explorer. This will open the assets folder for your mod, which is an identical format to the assets folder in content mods. The opened folder should only contain another folder labeled vstutorial.

You need to add a few asset files for the trampoline. As always, these can be downloaded from GitHub here.

The downloaded zip file contains a folder called vstutorial. Copy this folder over your own, and the asset files will be added. You can verify this by going back to Visual Studio, looking at the solution explorer, and expanding the assets folder. You should now have a trampoline block type, as well as a lang and texture file.

Run the game, launch a world, and check the creative menu. You should see the trampoline block. It looks fancy, but has absolutely no functionality yet.

Playing Vintage Story in fullscreen mode?

It is highly recommended to run the game in windowed mode when making code mods. If your code results in an error, Visual Studio will attempt to gain focus, and Vintage Story will stop responding. You can press F11 to easily switch between the fullscreen and windowed modes.

Block Class

Close the game and go back to Visual Studio. To add custom functionality to the trampoline block, you'll need to create a block class.

A block class is a script that offers custom functionality for any specific blocktype assets. Note that each blocktype can only have a single attached block class.

Creating a Block Class

Before you create a new block class, you should create a new folder called 'Blocks'. It is good practice to keep your classes and other scripts in folders relevant to what they are. In the solution explorer, right click on VSTutorial (the project, not the one labelled solution), hover over Add, and click New Folder. You can then enter a name for your folder.

You need a name for your new block's class. Generally, classes in Vintage Story follow the naming convention of {Type}{Name}. So, in the example of a trampoline block class, you should call this block class "BlockTrampoline".

With your folder now created, you need to create a new class. Right click the new folder, hover over Add, and select Class. This will open a menu with a lot of templates, and an input field to enter your class name. Make sure you have selected the standard Class at the top of the template list, and enter the name 'BlockTrampoline.cs'. Click Add, and your class will be created.

The trampoline block's class should open automatically, but you can open it manually by double clicking its entry in the solution explorer.

Explaining Block Classes

Let's have a quick run down of how a block class works. Replace the entire contents of the new class with the following code:

BlockTrampoline.cs

//Here are the imports for this script. Most of these will add automatically. using Vintagestory.API.Common; using Vintagestory.API.MathTools; /* * The namespace the class will be in. This is essentially the folder the script is found in. * If you need to use the BlockTrampoline class in any other script, you will have to add 'using VSTutorial.Blocks' to that script. */ namespace VSTutorial.Blocks { /* * The class definition. Here, you define BlockTrampoline as a child of Block, which * means you can 'override' many of the functions within the general Block class. */ internal class BlockTrampoline : Block { //Any code within this 'override' function will be called when a trampoline block is placed. public override void OnBlockPlaced(IWorldAccessor world, BlockPos blockPos, ItemStack byItemStack = null) { //Log a message to the console. api.Logger.Event("Trampoline Block Placed!"); //Perform any default logic when our block is placed. base.OnBlockPlaced(world, blockPos, byItemStack); } //Any code within this 'override' function will be called when a trampoline block is broken. public override void OnBlockBroken(IWorldAccessor world, BlockPos pos, IPlayer byPlayer, float dropQuantityMultiplier = 1) { //Log a message to the console. api.Logger.Event("Trampoline Block Broken!"); //Perform any default logic when our block is broken (e.g., dropping the block as an item.) base.OnBlockBroken(world, pos, byPlayer, dropQuantityMultiplier); } } }

Note the code comments throughout the file. These are marked by double slashes ( // ) or any text between /* and */. These give brief explanations on what every line of this example does.

For further explanation, on line 15, the BlockTrampoline class is defined as a child of the Block class, which is in turn a child of the CollectibleObject class, and then the RegistryObject class. This essentially means that any function within these three inherited classes marked as 'virtual', 'abstract', or 'override' can be given custom functionality. For an exhaustive list of functions and attributes that can be overriden, take a look at the API documentation for the Block and CollectibleObject methods.

Why so many code comments?

There is much debate about how many code comments are too many, and when/where they should be used. Although many people who are experienced with C# or other C programming languages may find this code easy to understand, this tutorial is designed for those who may not have ever used a C programming language, or even any programming language.

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.