Modding:Code Tutorial Essentials

From Vintage Story Wiki
This page contains changes which are not marked for translation.

This page will give a breakdown of a number of topics and terminology used with code modding. Since some code topics can become quite complex, it is important to read through this page.

This page will also introduce you to the coding tutorials and how to begin with them.

Modding Tutorials

All tutorials within the categorized sections (basic, intermediate, advanced, other) can be made in the same project as one another, as they are all created under the project name "VSTutorial". It is recommended to create a new mod with the same project name, and use this project when you wish to complete any of these tutorials.

When writing code, it's important to keep your code well-organized and documented. Coding styles vary from person to person, however the tutorials will always prefer readability and understandability over efficiency. If there are instances of more efficient code, these may be mentioned at the time.

Code Mods and Content Mods

Code mods should not be thought of as separate to content mods. Most code mods are more of an expansion of content mods, aimed to add more functionality for new or existing content.

Because of this, it is highly recommended that you are experienced with content mods before beginning code mods. Every code tutorial on the wiki will assume that you have completed, or are at least familiar with the basic and intermediate content tutorials.


Vintage Story loads all worlds by using a client/server system. There always exists one server per world, however there can be any number of clients. Each player that joins the world, including a singleplayer world, is classed as a client.

Many aspects of code are split between the server and the client. In general, the client is used for rendering, inputs, and more precise physics calculations. The server determines world logic, most entity logic, and communication between all clients.

Clients cannot directly communicate with other clients. In order to share data, the server must send this to appropriate clients.

Mod System

A Mod System is used as an entry point for your mod, and contains many useful functions for the execution of your mod. A single mod can have multiple mod systems, but must have at least one for any code to be executed.

When creating a mod using the mod template, you will notice that a mod system is automatically generated with a number of functions.

Some useful functions that your mod system can use are:

  • Start - This is called on both the server and the client, and is where you should register blocks, items, entities, and most other things that need registering.
  • StartServerSide - This is called only on the server side. You should register any server-side-only classes and logic here. Most commands will be registered here.
  • StartClientSide - Similarly to StartServerSide, but only called on the client side. You should use this to register and rendering or UI logic here.
  • ShouldLoad - This can be used to control what side your mod should be loaded on. You can use this to make client-only or server-only mods.
  • ExecuteOrder - This is an extremely important function that alters when your mod is loaded. Check the GitHub link below for information on what is loaded in what order.

There are many other functions that are more specific. You can view Mod System on GitHub for a full breakdown of this class.

CoreAPI, CoreServerAPI, CoreClientAPI

The CoreAPI class is extremely important, and is used throughout many different aspects of the game. The CoreServerAPI and CoreClientAPI are specific instances of CoreAPIs for server and client logic respectively.

The CoreAPI is used to handle assets, commands, events, registries, world data, and many other things.

You can find the following classes on GitHub.

  • ICoreAPICommon - A set of functions and fields common to the server and client.
  • ICoreAPI - Extends from ICoreAPICommon, contains a few more useful values.
  • ICoreClientAPI - Extends from ICoreAPI. Contains useful functions and fields that can be used only on the client-side.
  • ICoreServerAPI - Extends from ICoreAPI. Contains useful functions and fields that can be used only on the server-side.

Icon Sign.png

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.

Modding Introduction Getting Started Theme Pack
Content Modding Content Mods Developing a Content Mod Basic Tutorials Intermediate Tutorials Advanced Tutorials Content Mod Concepts
Code Modding Code Mods Setting up your Development Environment
Property Overview ItemEntityBlockBlock BehaviorsBlock ClassesBlock EntitiesBlock Entity BehaviorsWorld properties
Workflows & Infrastructure Modding Efficiency TipsMod-engine compatibilityMod ExtensibilityVS Engine
Additional Resources Community Resources Modding API Updates Programming Languages List of server commandsList of client commandsClient startup parametersServer startup parameters
Example ModsAPI DocsGitHub Repository